TTLSSignatureParms statement

Parameters

name

A string 1 - 32 characters in length that specifies the name of this TTLSSignatureParms statement.

Rule: If this TTLSSignatureParms statement is not specified inline in another statement, a name value must be provided. If a name is not specified for an inline TTLSSignatureParms statement, a nonpersistent system name is created.

ClientECurves

Specifies the list of ECDH (Elliptic curve Diffie-Hellman) curves that are supported by the client, in order of preference for use.

• For TLSv1.0, TLSv1.1, TLSv1.2: This list is used by the client to guide the server as to which elliptical curves are preferred when using cipher suites that use elliptical curve cryptography.
• For TLSv1.3: This list is used by the client to guide the server as to which elliptic curves are preferred and to guide group selection for encryption and decryption of handshake messages.

Only NIST recommended curves along with x25519 and x448 can be specified.

Restriction: For TLSv1.0, TLSv1.1, and TLSv1.2, if x25519 or x448 is specified and the partner is using an ECDSA certificate, the certificate's elliptic curve must also be included in the ClientECurves list of curves. AT-TLS does not support X25519 and x448 certificates.

For TLSv1.0, TLSv1.1, and TLSv1.2, to allow the use of Brainpool standard curve certificates for a TLS connection, the list must contain only the ANY curve name constant.

Restriction: Brainpool certificates cannot be used in FIPS mode or if the negotiated protocol is TLSv1.3.

Restriction: When TLSv1.3 is enabled, a value of ANY will result in a failure.

If a ClientECurves parameter is specified more than once, the values are concatenated to create a single list of elliptic curve enumerators. The ANY curve name constant cannot be specified in combination with any specific curve values. For System SSL, the GSK_CLIENT_ECURVE_LIST value is set to the concatenated value or to NULL if ANY is specified.

The curves value is a string of one or more 4-character curve enumerators or a single curve name constant. The curve string cannot have blanks between the curve enumerators. If duplicate curves are specified, the first instance is used and all other instances are ignored. The maximum number of curves is 16. For System SSL, see Table 16. Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3 in z/OS® Cryptographic Services System SSL Programming for a list of valid elliptic curves and the TLS versions for which the curves are supported. Table 1 lists the supported elliptic curve name constants.

default_client_ecurves

For an environment action, the default is dependent on whether TLSv1.3 is enabled for the environment action or not.

• If TLSv1.3 is enabled for the environment action, the default is 002100230024002500190029 which includes secp224r1, secp256r1, secp384r1, secp521r1, secp192r1, x25519.
• If TLSv1.3 is not enabled for the environment action, the default is 00210023002400250019 which includes secp224r1, secp256r1, secp384r1, secp521r1, secp192r1.

For a connection action, if the TLSv1.3 parameter is explicitly configured for the connection action, the default is determined as follows:

• If TLSv1.3 is enabled for the connection action, the default is 002100230024002500190029 which includes secp224r1, secp256r1, secp384r1, secp521r1, secp192r1, x25519.
• If TLSv1.3 is disabled for the connection action, the default is 00210023002400250019 which includes secp224r1, secp256r1, secp384r1, secp521r1, secp192r1.
• Otherwise, if TLSv1.3 is not configured for the connection action, there is no default and the setting is determined by the associated environment action.

Table 1. ClientEcurves/ ServerKexECurves

Elliptic curve name constants	Elliptic Curve Enumerator	Supported TLS versions
secp192r1	0019	TLS V1.0, V1.1, V1.2
secp224r1	0021	TLS V1.0, V1.1, V1.2
secp256r1	0023	TLS V1.0, V1.1, V1.2, V1.3
secp384r1	0024	TLS V1.0, V1.1, V1.2, V1.3
secp521r1	0025	TLS V1.0, V1.1, V1.2, V1.3
x25519	0029	TLS V1.0, V1.1, V1.2, V1.3
x448	0030	TLS V1.0, V1.1, V1.2, V1.3

Table 2. ClientKeyShareGroups/ServerKeyShareGroups for TLSv1.3

Elliptic curve name constants	Elliptic Curve Enumerator
secp256r1	0023
secp384r1	0024
secp521r1	0025
x25519	0029
x448	0030

Requirement: Elliptic Curve requires ICSF to be active. See Elliptic Curve Cryptography Support in z/OS Cryptographic Services System SSL Programming for more information.

ClientKeyShareGroups

Specifies the list of key share groups supported by the client during a TLSv1.3 handshake. During a TLSv1.3 handshake, the client sends key shares for the groups in this list that are in common and in the same order as the supported groups list (ClientECurves curves). The server selects a group based on the client’s preferred order and the key share groups that it supports. The client and server use the selected group to encrypt and decrypt TLSv1.3 handshake messages.

The groups value is a string of one or more 4-character group enumerators or a single group name constant. The groups string cannot have blanks between the group enumerators. If duplicate groups are specified, the first instance is used and all other instances are ignored. The maximum number of groups is 16. See Table 2 for a list of the elliptic curve name constants supported for ClientKeyShareGroups.

If a ClientKeyShareGroups parameter is specified more than once, the values are concatenated to create a single list of groups enumerators. For System SSL, the GSK_CLIENT_TLS_KEY_SHARES value is set to the concatenated value.

For System SSL, see Table 16. Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3 in z/OS Cryptographic Services System SSL Programming for a list of valid elliptic curves and the TLS versions for which the group is supported. Table 2 lists the supported key share group constants.

default_key_share

For an environment action, the default value for ClientKeyShareGroups is the first value in the ClientECurves list that is supported for TLSv1.3. For example, if the default value for ClientECurves is used then the default value for ClientKeyShareGroups is 0023.

For a connection action, if ClientECurves is specified or defaulted, the default value for ClientKeyShareGroups is the first value in the configured ClientECurves list that is supported for TLSv1.3. Otherwise, there is no default and the setting is determined by the associated environment action.

ServerKexECurves

Specifies the list of ECDH (Elliptic curve Diffie-Hellman) curves that are supported by the server during a TLS V1.0, TLS V1.1, or TLS V1.2 handshake. This list is used by the server to limit which elliptic curves can be used for the handshake key exchange when an ephemeral ECDH cipher (TLS_ECDHE_xxx) is utilized.

The curves value is a string of one or more 4-character curve enumerators or a single curve name constant. The curve list cannot have blanks between the curve enumerators. If duplicate curves are specified, the first instance is used, and all other instances are ignored.

If a ServerKexECurves parameter is specified more than once, the values are concatenated to create a single list of curve enumerators. For System SSL, the GSK_SERVER_ALLOWED_KEX_ECURVES value is set to the concatenated value.

For System SSL, see Table 29. Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3 in z/OS Cryptographic Services System SSL Programming for a list of valid elliptic curves and the TLS versions for which the curve is supported. Table 1 lists the supported elliptic curve name constants.

For an environment action, the default value for ServerKexECurves is 00230024002500210019 which includes secp256r1, secp384r1, secp521r1, secp224r1, secp192r1.

For a connection action, there is no default for ServerKexECurves - the setting is determined by the associated environment action.

ServerKeyShareGroups

Specifies the list of key share groups that are supported by the server during a TLSv1.3 handshake. During a TLSv1.3 handshake, the server uses the client's preferred key share group order and selects a group that it supports (as defined by ServerKeyShareGroups). The client and server use the selected group to encrypt and decrypt TLSv1.3 handshake messages.

The groups value is a string of one or more 4-character group enumerators or a single group name constant. The groups string cannot have blanks between the group enumerators. If duplicate groups are specified, the first instance is used and all other instances are ignored. The maximum number of groups is 16. See Table 2 for a list of the key share group constants.

If a ServerKeyShareGroups parameter is specified more than once, the values are concatenated to create a single list of group enumerators. For System SSL, the GSK_SERVER_TLS_KEY_SHARES value is set to the concatenated value.

For System SSL, see Table 16. Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 and supported key share definitions for TLS V1.3 in z/OS Cryptographic Services System SSL Programming for a list of valid elliptic curves and the TLS versions for which the group is supported. Table 2 lists the supported key share group constants.

For an environment action, the default value for ServerKeyShareGroups is 00230024002500290030 which includes secp256r1, secp384r1, secp521r1, x25519, x448.

For a connection action, there is no default for ServerKeyShareGroups - the setting is determined by the associated environment action.

SignaturePairs

Specifies the signature algorithm pairs that are supported by the client or server for use in digital signatures of X.509 certificates and TLS handshake messages. These pairs are sent by either the client or server to the session partner to indicate which signature algorithm pairs are supported. If a SignaturePairsCert parameter(s) is specified, the SignaturePairs parameter(s) setting is only used for validating TLS handshake messages. SignaturePairs specification only has relevance for sessions using TLSv1.2 or later.

If a SignaturePairs parameter is specified more than once, the values are concatenated to create a single list of signature algorithm pairs. For System SSL, the GSK_TLS_SIG_ALG_PAIRS value is set to the concatenated value.

The algorithms value is a string of one or more 4-character signature algorithm pairs or a single signature algorithm pair constant. The algorithm string cannot have blanks between each signature algorithm pair. If duplicate signature algorithm pairs are specified, the first instance is used and all other instances are ignored. The maximum number of signature algorithm pairs is 64. For System SSL, see Table 17. Signature algorithm pair and certificate signature pair definitions for TLS V1.2 and TLS V1.3 in z/OS Cryptographic Services System SSL Programming for a list of valid signature algorithm pairs. Table 3 lists the supported signature algorithm pair constants and the TLS versions for which they are supported.

default_signature_pairs

For an environment action, the default is dependent on whether TLSv1.3 is enabled for the environment action or not.

• If TLSv1.3 is enabled for the environment action, the default is 0601060305010503040104030402030103030302020102030202080608050804 which includes the following:
  • TLS_SIGALG_SHA512_WITH_RSA, TLS_SIGALG_SHA512_WITH_ECDSA,
  • TLS_SIGALG_SHA384_WITH_RSA, TLS_SIGALG_SHA384_WITH_ECDSA,
  • TLS_SIGALG_SHA256_WITH_RSA, TLS_SIGALG_SHA256_WITH_ECDSA,
  • TLS_SIGALG_SHA256_WITH_DSA, TLS_SIGALG_SHA224_WITH_RSA,
  • TLS_SIGALG_SHA224_WITH_ECDSA, TLS_SIGALG_SHA224_WITH_DSA,
  • TLS_SIGALG_SHA1_WITH_RSA, TLS_SIGALG_SHA1_WITH_ECDSA,
  • TLS_SIGALG_SHA1_WITH_DSA, TLS_SIGALG_SHA512_WITH_RSASSA_PSS,
  • TLS_SIGALG_SHA384_WITH_RSASSA_PSS,
  • TLS_SIGALG_SHA256_WITH_RSASSA_PSS.
• If TLSv1.3 is not enabled for the environment action, the default is 0601060305010503040104030402030103030302020102030202 which does not include the following:
  • TLS_SIGALG_SHA512_WITH_RSASSA_PSS,
  • TLS_SIGALG_SHA384_WITH_RSASSA_PSS,
  • TLS_SIGALG_SHA256_WITH_RSASSA_PSS.

For a connection action, if the TLSv1.3 parameter is explicitly configured for the connection action, the default is determined as follows:

• If TLSv1.3 is enabled for the connection action, the default is 0601060305010503040104030402030103030302020102030202080608050804.
• If TLSv1.3 is disabled for the connection action, the default is 0601060305010503040104030402030103030302020102030202.
• Otherwise, if TLSv1.3 is not configured for the connection action, there is no default and the setting is determined by the associated environment action.

Table 3. SignaturePairs/ SignaturePairsCert

Signature algorithm pair constant	Hexadecimal characters	Supported TLS Versions
TLS_SIGALG_MD5_WITH_RSA	0101	TLS V1.2
TLS_SIGALG_SHA1_WITH_RSA	0201	TLS V1.2
TLS_SIGALG_SHA1_WITH_DSA	0202	TLS V1.2
TLS_SIGALG_SHA1_WITH_ECDSA	0203	TLS V1.2
TLS_SIGALG_SHA224_WITH_RSA	0301	TLS V1.2
TLS_SIGALG_SHA224_WITH_DSA	0302	TLS V1.2
TLS_SIGALG_SHA224_WITH_ECDSA	0303	TLS V1.2
TLS_SIGALG_SHA256_WITH_RSA	0401	TLS V1.2, V1.3
TLS_SIGALG_SHA256_WITH_DSA	0402	TLS V1.2
TLS_SIGALG_SHA256_WITH_ECDSA	0403	TLS V1.2, V1.3
TLS_SIGALG_SHA384_WITH_RSA	0501	TLS V1.2, V1.3
TLS_SIGALG_SHA384_WITH_ECDSA	0503	TLS V1.2, V1.3
TLS_SIGALG_SHA512_WITH_RSA	0601	TLS V1.2, V1.3
TLS_SIGALG_SHA512_WITH_ECDSA	0603	TLS V1.2, V1.3
TLS_SIGALG_SHA256_WITH_RSASSA_PSS	0804	TLS V1.2, V1.3
TLS_SIGALG_SHA384_WITH_RSASSA_PSS	0805	TLS V1.2, V1.3
TLS_SIGALG_SHA512_WITH_RSASSA_PSS	0806	TLS V1.2, V1.3

SignaturePairsCert

Specifies the signature algorithm pairs that are supported by the client or server for use in digital signatures of X.509 certificates. These pairs can be sent by either the client or server to the session partner to indicate which signature algorithm pairs are supported. The SignaturePairsCert parameter(s) setting overrides the SignaturePairs parameter(s) setting when checking the digital signatures of the peer’s X.509 certificates.

SignaturePairsCert specification only has relevance for sessions using TLSv1.3 or later.

If a SignaturePairsCert parameter is specified more than once, the values are concatenated to create a single list of signature algorithm pairs. For System SSL, the GSK_TLS_CERT_SIG_ALG_PAIRS value is set to the concatenated value. If not specified, the GSK_TLS_SIG_ALG_PAIRS setting (from the SignaturePairs parameter) is used to indicate which signature algorithm pairs the client or server supports for use in digital signatures of X.509 certificates.

The algorithms value is a string of one or more 4-character signature algorithm pairs or a single signature algorithm pair constant. The algorithm string cannot have blanks between each signature algorithm pair. If duplicate signature algorithm pairs are specified, the first instance is used and all other instances are ignored. The maximum number of signature algorithm pairs is 64. For System SSL, see Table 17. Signature algorithm pair and certificate signature pair definitions for TLS V1.2 and TLS V1.3 in z/OS Cryptographic Services System SSL Programming for a list of valid signature algorithm pairs. Table 3 lists the supported signature algorithm pair constants and the TLS versions for which they are supported.