VMSSL Command Syntax

Operands

KEYFILE pathname

specifies the name of the certificate database (key database file or PKCS #12 file) that is to be used by the SSL server. The given name is case sensitive, and can be specified as an absolute or as a relative pathname. The default key database file name is /etc/gskadm/Database.kdb

CACHELIFE duration

specifies the amount of time (in hours, minutes or seconds) that a session cache entry is to be valid. Cache entries older than the given duration are considered expired and no longer can be used. The minimum duration is 0, and the maximum is 24 hours, which is also the default.

Note: For information about adjusting the CACHELIFE setting, see Monitoring the Server Session Cache.

H

indicates that duration is specified in hours. This is the default.

M

indicates that duration is specified in minutes.

S

indicates that duration is specified in seconds.

CACHECleanup frequency

specifies the frequency (as a number of connections) at which the SSL server is to remove expired entries from the shared session cache. The default is to perform clean up operations for every 100 connections that are processed. The minimum frequency is 10 and the maximum is 1000.

Note that cleanup operations are performed on a per-server basis. Thus, cleanup might not be performed every frequency connections (based on values reported by an SSLADMIN QUERY STATUS or NETSTAT CONFIG SSL command), but every frequency connections, as perceived by an individual server.

FIPS

instructs the SSL server to operate in accordance with a particular Federal Information Processing Standard (FIPS) cryptographic standard configuration. This restricts the behavior of the SSL server to approved protocols and cipher suites.

Specifying the FIPS operand is equivalent to specifying the MODE FIPS-140-2 operand.

MODE

establishes a baseline of functionality for the entire SSL server. The values that can be specified for standard are:

FIPS-140-2

indicates that the SSL server should operate according to Federal Information Protection Standard (FIPS) 140-2. This mode allows only TLS protocols to be used, and restricts the usage of some cipher suites.

Specifying the MODE FIPS-140-2 operand is equivalent to specifying the FIPS operand.

NIST-800-131a

indicates that the SSL server should operate according to NIST Special Publication 800-131a. This requires the use of TLS 1.2, restricts the usage of certain cipher suites, and mandates the use of RSA, DSA, or Diffie Hellman keys of 2048 or greater for all secure connections.

Note:

• MODE can be specified multiple times to enable available standards of operation. In cases where multiple standards are enabled, the maximum common subset of functionality will be enabled.
• MODE FIPS-140-2 is the preferred method of enabling FIPS-compliant behavior for the SSL server; it should replace use of the FIPS operand.
• If MODE NIST-800-131A is enabled, all protocols other than TLS 1.2 will be automatically disabled.
• Specifying MODE FIPS-140-2 requires that the SSL server be associated with a FIPS-compliant certificate database.

PROTOcol version

specifies a version of the SSL or TLS protocols to be enabled or disabled for cryptographic use in the operation of this SSL server. The PROTOCOL keyword can be specified multiple times with one version per keyword. Inclusion or exclusion is denoted by a + or - symbol. If no symbol is specified, the default of inclusion is used.

The values that can be specified for version are:

TLSV1_2

indicates Transport Layer Security (TLS) 1.2. This is the highest level of cryptographic strength the SSL Server can enable. Certain cipher suites are only available when TLS 1.2 issued. Export ciphers and DES ciphers are excluded from use in TLS 1.2. TLS 1.2 is enabled by default.

TLSV1_1

indicates TLS 1.1. TLS 1.1 is similar to TLS 1.0, though it excludes use of the Export ciphers. TLS 1.1 is disabled by default.

TLSV1_0

indicates TLS 1.0.

SSLV3

indicates Secure Socket Layer (SSL) 3.

SSLV2

indicates SSL 2.

Note:

• PROTOCOL can be specified multiple times. In cases where conflicting instances exist, the most recent instance is used for SSL server processing.
• SSLV2 is incompatible with the TLS protocols. If any level of TLS is specified, SSLV2 is automatically disabled.
• The SSL protocols (SSLV2 and SSLV3) cannot be enabled when running in FIPS mode.
• The SSL server will not initialize if all protocols are disabled.

EXEMPT cipher_suite

EXEMPT strength_set

specifies a cipher suite, or a set of such suites that have common strength, that should not be used by the SSL server.

Note:

• RC4_56_SHA, RC4_EXP1024_56_SHA, and DES_EXP1024_56_SHA were accepted as valid cipher suite names in releases prior to z/VM 5.4. They are no longer supported.
• For cipher suite names, V2 and V3 designate the version of SSL or TLS used by the SSL Server. In cases where a cipher suite is V2 and V3 compliant, specifying that suite name for exemption exempts V2 and V3.
• Inclusion or exclusion of specific versions of SSL or TLS through the PROTOCOL operand can change the cipher suites available to the SSL server, even when using EXEMPT on a common-strength basis.
• The following cipher suites are disabled by default:
  V3 Code Name
  
  0000 - NULL                          
  0001 - NULL_MD5                
  0002 - NULL_SHA                  
  0003 - RC4_40_MD5              
  0004 - RC4_128_MD5            
  0005 - RC4_128_SHA              
  0006 - RC2_40_MD5
  0009 - DES_56_SHA
  000A - 3DES_168_SHA
  000C - DH_DSS_DES
  000D - DH_DSS_3DES
  000F - DH_RSA_DES  
  0010 - DH_RSA_3DES
  0012 - DHE_DSS_DES
  0015 - DHE_RSA_DES
  0030 - DH_DSS_AES_128
  0031 - DH_RSA_AES_128
  0036 - DH_DSS_AES_256
  0037 - DH_RSA_AES_256
  0068 - DH_DSS_AES_256_SHA256
  0069 - DH_RSA_AES_256_SHA256              
  003B - NULL_SHA256
  003E - DH_DSS_AES_128_SHA256
  003F - DH_RSA_AES_128_SHA256
  00A0 - DH_RSA_AES_128_GCM_SHA256
  00A1 - DH_RSA_AES_256_GCM_SHA384
  00A4 - DH_DSS_AES_128_GCM_SHA256
  00A5 - DH_DSS_AES_256_GCM_SHA384
  C001 - ECDH_ECDSA_NULL_SHA                                                
  C002 - ECDH_ECDSA_RC4_128_SHA                                              
  C003 - ECDH_ECDSA_3DES_EDE_SHA                                            
  C004 - ECDH_ECDSA_AES_128_SHA                                              
  C005 - ECDH_ECDSA_AES_256_SHA                                              
  C007 - ECDHE_ECDSA_RC4_128_SHA                                            
  C00B - ECDH_RSA_NULL_SHA                                                  
  C00C - ECDH_RSA_RC4_128_SHA                                                
  C00D - ECDH_RSA_3DES_EDE_SHA                                              
  C00E - ECDH_RSA_AES_128_SHA                                                
  C00F - ECDH_RSA_AES_256_SHA
  C010 - ECDHE_RSA_NULL_SHA
  C011 - ECDHE_RSA_RC4_128_SHA  
  C025 - ECDH_ECDSA_AES_128_SHA256
  C026 - ECDH_ECDSA_AES_256_SHA384
  C029 - ECDH_RSA_AES_128_SHA256
  C02A - ECDH_RSA_AES_256_SHA384
  C02D - ECDH_ECDSA_AES_128_GCM_SHA256
  C02E - ECDH_ECDSA_AES_256_GCM_SHA384                                      
  C031 - ECDH_RSA_AES_128_GCM_SHA256                                        
  C032 - ECDH_RSA_AES_256_GCM_SHA384
  
• Management by strength:
  • Disallows modifications on a per-cipher basis
  • Works only for the cipher suites that are enabled by default for the TLS/SSL server
  • Should not be used in environments with complex or rapidly changing encryption requirements

ENABLE cipher_suite

specifies a cipher suite that should be used by the SSL server.

Notes:

• ENABLE can be used only when managing cipher suites by name. ENABLE cannot be used in conjunction with the strength keywords (LOW or NONE, for example).
• Like EXEMPT, ENABLE cannot be used if EXEMPT processing is being handled by strength.
• If the same cipher suite is specified for ENABLE and EXEMPT:
  1. EXEMPT processing is handled first, regardless of DTCPARMS ordering in releases prior to z/VM 6.3.
  2. The most recent instance is used for SSL server processing in z/VM 6.3 and later.

The possible values for cipher_suite follow in Table 1 and Table 2:

Strength set names can be specified in abbreviated form, with the first character of each accepted as the minimum value.

TLSFALLBACKSCSV

instructs the TLS/SSL server to act in accordance with RFC 7507. This option enables protection against protocol downgrade attacks. ON is enabled by default.

GSKTRACE trace_mask

specifies that detailed SSL trace information should be captured by the SSL server. The type of the information captured is controlled by a bit mask that is determined by the supplied trace mask value, which can be specified as a decimal (nnn), octal (0nnn), or hexadecimal (0xhh) value. No trace option is enabled if the bit mask is 0 or if the GSKTRACE operand is omitted, and all trace options are enabled if the trace mask is 0xffff.

The following trace mask options are available:

• 0x01 = Trace function entry
• 0x02 = Trace function exit
• 0x04 = Trace errors
• 0x08 = Include informational messages
• 0x10 = Include EBCDIC data dumps
• 0x20 = Include ASCII data dumps

These options can be combined so that the desired tracing is performed. For example, to trace only errors and include informational messages, specify the GSKTRACE operand as one of the following:

GSKTRACE 12
GSKTRACE 014
GSKTRACE 0x0C 

SSL trace information is written to the BFS file /tmp/user_id.gskssl.%.trc where user_id is replaced by the SSL server user ID, and the percent sign (%) is replaced with a numeric process identifier. For example, if the user ID of the SSL server is SSL00001 and the process identifier in effect is 247, the trace file produced will be: /tmp/ssl00001.gskssl.247.trc.

The GSKTRACE command creates a readable copy of SSL trace information. For more information, consult SSL Tracing in z/VM: TCP/IP User's Guide.

NOTRAce

specifies that all tracing is turned off. This is the default.

TRAce

specifies that tracing is to be performed. The TRACE operand is intended for use in diagnosing SSL server operational problems, in consultation with the IBM® support center. Use of this operand to perform detailed SSL server tracing is strongly discouraged in production environments.

NORMal

specifies that a trace entry is recorded to indicate a successful connection. This is the default if TRACE is specified.

CONNections

specifies that a trace entry is recorded for connection state changes and handshake results.

NODATA

specifies that no data is displayed for send and receive trace entries. This is the default if CONNECTIONS is specified.

DATA

specifies that the first 20 bytes of data are displayed for send and receive trace entries.

FLOW

specifies that flow of control and system activity are traced.

DEBug

specifies that extensive tracing is done for all control and system activity as well as data on all connections.

ALL

specifies that tracing is done for all connections. This is the default if TRACE is specified.

ip_address

specifies that tracing is done only for activity associated with this IP address.

:port

..port

specifies that tracing is done only for activity associated with this port.

Note: The format :port is not valid with IPv6 addresses, use ..port instead.

length

specifies the number of bytes of data to be presented when the CONNECTIONS DATA operand is used. The connection data is represented in hexadecimal, as well as in ASCII and EBCDIC, in unencrypted form. The length must be specified as 0, or as a number in the range of 1 to 65535. The value zero (0) or the keyword ALL indicates that all available data is to be presented. The default is to display 20 bytes of data. Note that a suitable tracing target (such as an IP address, port, or connection number) must be designated when a length value other than the default is to be used.

VMDUMP error_type

instructs the SSL server to create a virtual machine dump when an error of the indicated type is encountered. In addition, the affected server initiates the creation of dumps for its associated TCP/IP stack and DCSS agent servers, when conditions allow for this.

error_type

identifies the type of errors for which a virtual machine dump is to be created. Possible values for 'error_type' are:

Error

specifies that a dump is to be created for an unexpected severe error condition. This is the default.

Socket

specifies that a dump is to be created for unexpected socket-related errors only.

Note:

• The SSL server (or server pool) requires authorization to use the non-general version of the CP FOR command when the VMDUMP operand is specified. IBM-defined privilege class C provides this authorization.
• The virtual machine dumps created by using the VMDUMP operand are processed using the SYSTEM operand of the CP VMDUMP command (thus, dumps are transferred to the user specified on the SYSTEM_USERIDS CP configuration statement of the SYSTEM CONFIG file).

Usage Notes

1. DTCPARMS file changes become effective only when the SSL server is restarted.
2. Certain informational messages are always displayed at the SSL server console to:
   • acknowledge the receipt of SSLADMIN commands
   • report potential security breaches, such as a message digest not matching the message during the handshake
3. A key database that is created as a FIPS mode database, can only be updated by gskkyman or by using the CMS APIs executing in FIPS mode. Such a database, however, may be opened as read-only when executing in non-FIPS mode. Key databases created while in non-FIPS mode cannot be opened when executing in FIPS mode. For additional FIPS mode information and considerations, consult SSL Certificate/Key Management and SSL Tracing Information in z/VM: TCP/IP User's Guide.
4. To use a PKCS #12 file in FIPS mode, the file must be protected using TDES. When creating a PKCS #12 file from certificates within a key database file, using the gskkyman utility, the key database must be a FIPS key database.
5. For information about trace output, see the z/VM: TCP/IP Diagnosis Guide.

Messages