gsk_attribute_set

Sets an enumerated value.

Format

   #include <gskssl.h>

   gsk_status gsk_attribute_set_enum (
                                       gsk_handle         ssl_handle,
                                       GSK_ENUM_ID        enum_id,
                                       GSK_ENUM_VALUE     enum_value)

Parameters

ssl_handle: Specifies an SSL environment handle that is returned by gsk_environment_open() or an SSL connection handle that is returned by gsk_secure_socket_open().
enum_id: Specifies the enumeration identifier.
enum_value: Specifies the enumeration value.

Results

The function return value is 0 (GSK_OK) if no error is detected. Otherwise, it is one of the return codes that are listed in the gskssl.h include file. These are some possible errors:

[GSK_ATTRIBUTE_INVALID_ID]: The enumeration identifier is not valid or cannot be used with the specified handle.
[GSK_INVALID_HANDLE]: The handle is not valid.
[GSK_INVALID_STATE]: The environment or connection is not in the open state.

Usage

The gsk_attribute_set_enum() routine sets an enumerated value for an SSL environment or an SSL connection. The environment or connection must be in the open state and not in the initialized state (that is, gsk_environment_init() or gsk_secure_socket_init() has not been called).

The values set using this service are treated as independent values. They are not validated with other values set using gsk_attribute_set_buffer(), gsk_attribute_set_enum(), or gsk_attribute_set_tls_extensions() APIs until used together to perform a SSL/TLS handshake by calling gsk_secure_socket_init().

These enumeration identifiers are supported:

GSK_CERT_VALIDATE_KEYRING_ROOT

Specifies the setting of how certificates in a SAF key ring are validated. Specify GSK_CERT_VALIDATE_KEYRING_ROOT_ON if SAF key ring certificates must be validated to the root CA certificate. Specify GSK_CERT_VALIDATE_KEYRING_ROOT_OFF if SAF key ring certificates are only validated to the trust anchor certificate. If a sole intermediate certificate is found in a SAF key ring and the next issuer is not found in the same SAF key ring, the intermediate certificate acts as a trust anchor and the certificate chain is considered complete. By default, SAF key ring certificates are only validated to the trust anchor certificate. This setting does not affect the validation of SSL key database file and PKCS #11 token certificates as these certificates are always validated to the root CA certificate.

GSK_CERT_VALIDATE_KEYRING_ROOT can only be specified for an SSL environment.

GSK_CERT_VALIDATION_MODE

Specifies the method of certificate validation. RFC 2459, RFC 3280, and RFC 5280 describe differing methods of certificate validation. Specify GSK_CERT_VALIDATION_MODE_2459 if certificate validation according to the RFC 2459 method is required, GSK_CERT_VALIDATION_MODE_3280 if certificate validation according to the RFC 3280 method is required, or GSK_CERT_VALIDATION_MODE_5280 if certificate validation according to the RFC 5280 method is required.

Specify GSK_CERT_VALIDATION_MODE_ANY if certificate validation can use any supported X.509 certificate validation method.

GSK_CERT_VALIDATION_MODE can only be specified for an SSL environment.

GSK_CRL_SECURITY_LEVEL

Specify the level of security to be used when contacting an LDAP server to check for revoked certificates in a Certificate Revocation List (CRL). CRLs located are cached according to the GSK_CRL_CACHE_TIMEOUT setting of the SSL environment. To enforce contact with the LDAP server for each CRL check, CRL caching must be disabled. If a CRL is not defined, an empty CRL is placed in the CRL cache to prevent repeated calls to the LDAP server. This entry is not cleared until the CRL cache timeout is reached. See gsk_attribute_set_numeric_value() and Environment variables for more information about the GSK_CRL_CACHE_TIMEOUT setting. GSK_CRL_SECURITY_LEVEL can only be specified at the environment level.

Three levels of security are available:

GSK_CRL_SECURITY_LEVEL_LOW - Certificate validation does not fail if the LDAP server cannot be contacted.
GSK_CRL_SECURITY_LEVEL_MEDIUM - Certificate validation requires the LDAP server to be contactable, but does not require a CRL to be defined. This is the default.
GSK_CRL_SECURITY_LEVEL_HIGH - Certificate validation requires the LDAP server to be contactable, and a CRL to be defined.

GSK_CLIENT_AUTH_ALERT

Specify GSK_CLIENT_AUTH_NOCERT_ALERT_OFF if the SSL server application is to allow client connections where client authentication is requested and the client fails to supply an X.509 certificate. Specify GSK_CLIENT_AUTH_NOCERT_ALERT_ON if the SSL server application is to terminate client connections where client authentication is requested and the client fails to supply an X.509 certificate.

GSK_CLIENT_AUTH_ALERT can be specified only for an SSL environment and is only applicable for server sessions with client authentication active.

GSK_CLIENT_AUTH_TYPE

Specifies GSK_CLIENT_AUTH_FULL_TYPE to validate client certificates. If a certificate is not valid, the connection is not started and an error code is returned by the gsk_secure_socket_init() routine. If an LDAP server is specified, the LDAP server is queried for CA certificates and certificate revocation lists. If the LDAP server is not available, only local validation is performed. If no client certificate is received and either GSK_CLIENT_AUTH_ALERT is not specified or is set to GSK_CLIENT_AUTH_NOCERT_ALERT_OFF, the connection is successful. The application can check for this case by calling the gsk_attribute_get_cert_info() routine and checking for a NULL return address.

When a client's certificate is being requested, the client can be required to provide a certificate by setting GSK_CLIENT_AUTH_ALERT to GSK_CLIENT_NOCERT_ALERT_ON. If no certificate is received, the requested handshake fails. See gsk_attribute_set_enum() for more information about the GSK_CLIENT_AUTH_ALERT setting.

Specify GSK_CLIENT_AUTH_PASSTHRU_TYPE to bypass client certificate validation. The application can retrieve the certificate by calling the gsk_attribute_get_cert_info() routine.

GSK_CLIENT_AUTH_TYPE can be specified only for an SSL environment and is only applicable for server sessions with client authentication active.

GSK_EXTENDED_RENEGOTIATION_INDICATOR

Specify GSK_EXTENDED_RENEGOTIATION_INDICATOR_OPTIONAL to not require the renegotiation indicator during initial handshake. This is the default.

Specify GSK_EXTENDED_RENEGOTIATION_INDICATOR_CLIENT to allow the client initial handshake to proceed only if the server indicates support for RFC 5746 Renegotiation.

Specify GSK_EXTENDED_RENEGOTIATION_INDICATOR_SERVER to allow the server initial handshake to proceed only if the client indicates support for RFC 5746 Renegotiation.

Specify GSK_EXTENDED_RENEGOTIATION_INDICATOR_BOTH to allow the server and client initial handshakes to proceed only if partner indicates support for RFC 5746 Renegotiation.

GSK_EXTENDED_RENEGOTIATION_INDICATOR can only be specified for an SSL environment.

GSK_PROTOCOL_SSLV2

Specifies GSK_PROTOCOL_SSLV2_ON to enable the SSL Version 2 protocol or GSK_PROTOCOL_SSLV2_OFF to disable the SSL Version 2 protocol. The SSL V2 protocol should be disabled whenever possible since the SSL V3 and TLS protocols provide significant security enhancements.

GSK_PROTOCOL_SSLV2 can be specified for an SSL environment or an SSL connection.

When operating in FIPS mode, the SSL Version 2 protocol is not used. Enabling this protocol has no effect.

When TLS extensions are defined for the client and any of the TLS protocols are enabled for the connection, the SSL Version 2 protocol is not used. Enabling this protocol has no effect.

GSK_PROTOCOL_SSLV3

Specifies GSK_PROTOCOL_SSLV3_ON to enable the SSL Version 3 protocol or GSK_PROTOCOL_SSLV3_OFF to disable the SSL Version 3 protocol.

GSK_PROTOCOL_SSLV3 can be specified for an SSL environment or an SSL connection.

When operating in FIPS mode, the SSL Version 3 protocol is not used. Enabling this protocol has no effect.

GSK_PROTOCOL_TLSV1

Specifies GSK_PROTOCOL_TLSV1_ON to enable the TLS Version 1.0 protocol or GSK_PROTOCOL_TLSV1_OFF to disable the TLS Version 1.0 protocol.

GSK_PROTOCOL_TLSV1 can be specified for an SSL environment or an SSL connection.

GSK_PROTOCOL_TLSV1_1

Specifies GSK_PROTOCOL_TLSV1_1_ON to enable the TLS Version 1.1 protocol or GSK_PROTOCOL_TLSV1_1_OFF to disable the TLS Version 1.1 protocol.

GSK_PROTOCOL_TLSV1_1 can be specified for an SSL environment or an SSL connection.

GSK_PROTOCOL_TLSV1_2

Specify GSK_PROTOCOL_TLSV1_2_ON to enable the TLS Version 1.2 protocol or GSK_PROTOCOL_TLSV1_2_OFF to disable the TLS Version 1.2 protocol.

GSK_PROTOCOL_TLSV1_2 can be specified for an SSL environment or an SSL connection.

GSK_RENEGOTIATION

Specify GSK_RENEGOTIATION_NONE to disable SSL V3 and TLS handshake renegotiation as a server and allow RFC 5746 renegotiation. This is the default.

Specify GSK_RENEGOTIATION_DISABLED to disable SSL V3 and TLS handshake renegotiation as a server and also disable RFC 5746 renegotiation.

Specify GSK_RENEGOTIATION_ALL to allow SSL V3 and TLS handshake renegotiation as a server while also allowing RFC 5746 renegotiation.

Specify GSK_RENEGOTIATION_ABBREVIATED to allow SSL V3 and TLS abbreviated handshake renegotiation as a server for resuming the current session only, while disabling SSL V3 and TLS full handshake renegotiation as a server. With this enumeration value set, the System SSL session ID cache is not checked when resuming the current session. RFC 5746 renegotiation is allowed.

GSK_RENEGOTIATION can only be specified for an SSL environment.

GSK_RENEGOTIATION_PEER_CERT_CHECK

Specify GSK_RENEGOTIATION_PEER_CERT_CHECK_OFF to not perform an identity check against the peer's certificate during renegotiation. This allows the peer certificate to change during renegotiation. This is the default.

Specify GSK_RENEGOTIATION_PEER_CERT_CHECK_ON to perform a comparison against the peer's certificate to ensure that certificate does not change during renegotiation.

GSK_RENEGOTIATION_PEER_CERT_CHECK can only be specified for an SSL environment.

GSK_SESSION_TYPE

Specifies GSK_CLIENT_SESSION to perform the SSL handshake as a client, GSK_SERVER_SESSION to perform the SSL handshake as a server, or GSK_SERVER_SESSION_WITH_CL_AUTH to perform the SSL handshake as a server requiring client authentication.

GSK_SESSION_TYPE can be specified for an SSL environment or an SSL connection.

GSK_SUITE_B_PROFILE

Specifies the Suite B profile that an SSL server or client applies to TLS sessions. RFC 5430 defines the cipher suites that are valid for use when using the compliant Suite B profile for TLS. Specify:

GSK_SUITE_B_PROFILE_128 if only the 128-bit Suite B security profile is required.
GSK_SUITE_B_PROFILE_192 if only the 192-bit Suite B security profile is required.
GSK_SUITE_B_PROFILE_ALL if both the 128-bit and 192-bit Suite B security profiles are required.
GSK_SUITE_B_PROFILE_OFF if the Suite B security profile is not to be applied to any TLS sessions.

GSK_SUITE_B_PROFILE can only be specified for an SSL environment.

Because this setting affects the cipher suites that are allowed, this also has an implicit effect on the Elliptic Curves and Certificates that can be used. Suite B Cryptography requires that key establishment and authentication algorithms that are used in TLS sessions be based on Elliptic Curve Cryptography, and that the encryption algorithm be AES.

For more information about the cipher suites, elliptic curves, and certificates that are allowed by Suite B, see Suite B cryptography support.

GSK_SYSPLEX_SIDCACHE

Returns GSK_SYSPLEX_SIDCACHE_ON if sysplex session caching is enabled for this application or GSK_SYSPLEX_SIDCACHE_OFF if sysplex session caching is not enabled. GSK_SYSPLEX_SIDCACHE can be specified only for an SSL environment.

GSK_T61_AS_LATIN1

Specify GSK_T61_AS_LATIN1_ON to use the ISO8859-1 character set when processing a TELETEX string. Specify GSK_T61_AS_LATIN1_OFF to use the T.61 character set. The default is to use the ISO8859-1 character set.

Note: Selecting the incorrect character set can cause strings to be converted incorrectly. GSK_T61_AS_LATIN1 can be specified only for an SSL environment. This setting is global and affects all string conversions for all SSL environments.

GSK_V3_CIPHERS

Specify GSK_V3_CIPHERS_CHAR2 if the cipher specification is specified using 1 or more 2-character values in GSK_V3_CIPHER_SPECS. Specify GSK_V3_CIPHERS_CHAR4 if the cipher specification is specified using 1 or more 4-character values in GSK_V3_CIPHER_SPECS_EXPANDED. GSK_V3_CIPHERS can be specified for an SSL environment or an SSL connection.

Format

Parameters

Results

Usage

Related Topics