gsk_attribute_set_enum()

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 will be one of the return codes 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_AIA_CDP_PRIORITY

Specifies the priority order that the AIA and CDP extensions are checked for revocation information.

Specify GSK_AIA_CDP_PRIORITY_ON to indicate that the AIA extension is processed prior to the CDP extension during certificate revocation checking. This means that any OCSP responders specified in the AIA extension or the OCSP responder specified in GSK_OCSP_URL are contacted before attempting to contact the HTTP servers specified in the URI values in the CDP extension. This is the default setting.

Specify GSK_AIA_CDP_PRIORITY_OFF to indicate that the CDP extension is queried prior to the AIA extension. This means that HTTP servers in the URI values in the CDP extension are contacted before attempting to contact the OCSP responders in the AIA extension or the OCSP responder specified in GSK_OCSP_URL.

GSK_AIA_CDP_PRIORITY can be specified only for an SSL environment.

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, Start of change

PKCS #12 file End of change

, and PKCS #11 token certificates as these certificates are always validated to the root CA certificate.

GSK_CERT_VALIDATE_KEYRING_ROOT can be specified only 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 be specified only for an SSL environment.

GSK_CRL_CACHE_EXTENDED

Specifies that LDAP extended CRL cache support is enabled.

Specify GSK_CRL_CACHE_EXTENDED_ON to indicate that LDAP extended CRL cache support is enabled. LDAP extended CRL cache support enables the following support:

LDAP CRLs are only cached when there is an expiration time present and it is greater than the current time.
A limit on the maximum number of CRLs that can be stored in the LDAP cache which can be overridden by specifying GSK_CRL_CACHE_SIZE. The default is 32.
By default, GSK_CRL_CACHE_TEMP_CRL is disabled.

Specify GSK_CRL_CACHE_EXTENDED_OFF to indicate that LDAP basic CRL cache support is enabled. When LDAP basic CRL cache support is enabled, retrieved LDAP CRLs are only cached if GSK_CRL_CACHE_TIMEOUT is greater than 0 and GSK_CRL_CACHE_SIZE is set to a non-zero number. Start of change LDAP basic CRL cache support is the default. End of change

Note: When set to GSK_CRL_CACHE_EXTENDED_ON, the GSK_CRL_CACHE_TIMEOUT value is ignored.

GSK_CRL_CACHE_EXTENDED can be specified only for an SSL environment.

GSK_CRL_CACHE_TEMP_CRL

Specifies if a temporary LDAP CRL cache entry is added to the LDAP CRL cache when the CRL does not reside on the LDAP server.

Specify GSK_CRL_CACHE_TEMP_CRL_ON if a temporary CRL cache entry is be added to the LDAP CRL cache.

Specify GSK_CRL_CACHE_TEMP_CRL_OFF if a temporary CRL cache entry is not to be added to the LDAP CRL cache.

If a temporary CRL is cached, it will prevent continual attempts to contact the LDAP server and will allow connections to be successful.

GSK_CRL_CACHE_TEMP_CRL can be specified only for an SSL environment.

GSK_CRL_SECURITY_LEVEL

Specifies the level of security to be used when contacting LDAP servers to check CRLs for revoked certificates during certificate validation.

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 retrieved. This is the default.
GSK_CRL_SECURITY_LEVEL_HIGH: Certificate validation requires revocation information to be provided by the LDAP server.

GSK_CRL_SECURITY_LEVEL can be specified only for an SSL environment.

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_ENABLE_CLIENT_SET_PEERID

Specify GSK_ENABLE_CLIENT_SET_PEERID_ON to enable the use of a cached GSK_PEER_ID for SSL V3, TLS 1.0, or higher client connections. GSK_ENABLE_CLIENT_SET_PEERID can be specified only for an SSL environment and is only applicable for client connections. GSK_ENABLE_CLIENT_SET_PEERID_OFF is the default setting.

GSK_ENABLE_CLIENT_SET_PEERID_ON limits the number of full client handshakes that can be cached over the lifetime of the SSL environment to a maximum number of 4.29 billion. If this maximum number is reached, all new SSL connections that are not using a cached GSK_PEER_ID will result in full handshakes and will not add entries into the session cache. Also, if the maximum number is reached, reusing a cached GSK_PEER_ID is allowed as long as the GSK_PEER_ID can still be located in the cache.

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 be specified only for an SSL environment.

GSK_HTTP_CDP_ENABLE

Specifies whether the HTTP URIs within the CDP extension are to be utilized for certificate revocation checking.

Specify GSK_HTTP_CDP_ENABLE_OFF to indicate that certificate revocation checking with the HTTP URI values in the CDP is not enabled. This is the default.

Specify GSK_HTTP_CDP_ENABLE_ON to indicate that certificate revocation checking with the HTTP URI values in the CDP extension is enabled.

GSK_HTTP_CDP_ENABLE can be specified only for an SSL environment.

GSK_OCSP_ENABLE

Specifies whether the AIA extensions are to be used for certificate revocation checking.

Specify GSK_OCSP_ENABLE_ON to activate certificate revocation checking using the HTTP URI values in the certificate's AIA extension.

Specify GSK_OCSP_ENABLE_OFF to disable use of the AIA extension. This is the default.

If GSK_OSCP_URL is specified, GSK_OCSP_ENABLE is set to ON, and GSK_OCSP_URL_PRIORITY is set to ON, then the order the responders are used is GSK_OCSP_URL defined responder first and then the responders identified in the AIA extension. If GSK_OCSP_URL is specified, GSK_OCSP_ENABLE is set to ON and GSK_OCSP_URL_PRIORITY is set to OFF, then the order that responders are used is the responders identified in the AIA extension first and then the GSK_OCSP_URL defined responder.

GSK_OCSP_ENABLE can be specified only for an SSL environment.

GSK_OCSP_NONCE_CHECK_ENABLE

Specifies if OCSP response nonce checking is on or off.

Specify GSK_OCSP_NONCE_CHECK_ENABLE_ON to have the nonce in the OCSP response verified to ensure it matches the nonce sent in the OCSP request.

Note: Setting GSK_OCSP_NONCE_CHECK_ENABLE_ON also implies that GSK_OCSP_NONCE_GENERATION_ENABLE_ON is also set to ON.

Specify GSK_OCSP_NONCE_CHECK_ENABLE_OFF to disable checking of the nonce in the OCSP response. This is the default.

GSK_OCSP_NONCE_CHECK_ENABLE can be specified only for an SSL environment.

GSK_OCSP_NONCE_GENERATION_ENABLE

Specifies whether the OCSP request includes a generated nonce.

Specify GSK_OCSP_NONCE_GENERATION_ENABLE_ON to enable nonce generation.

Specify GSK_OCSP_NONCE_GENERATION_ENABLE_OFF to disable OCSP nonce generation. This is the default.

GSK_OCSP_NONCE_GENERATION_ENABLE can be specified only for an SSL environment.

GSK_OCSP_RETRIEVE_VIA_GET

Specifies whether the HTTP request to the OCSP responder is sent using the HTTP Get Method or the HTTP Post method.

Specify GSK_OCSP_RETRIEVE_VIA_GET_ON to indicate that the HTTP GET method should be used when sending an OCSP request whose total request size after Base64 encoding is less than 255 bytes. This option allows HTTP caching on the OCSP responder when the responder has been enabled for caching.

Specify GSK_OCSP_RETRIEVE_VIA_GET_OFF to indicate the HTTP request should always be sent via an HTTP Post method. This is the default.

GSK_OCSP_RETRIEVE_VIA_GET can be specified only for an SSL environment.

GSK_OCSP_URL_PRIORITY

Specifies the order of precedence for contacting the OCSP responder locations if both GSK_OCSP_URL and GSK_OCSP_ENABLE are active.

Specify GSK_OCSP_URL_PRIORITY_ON to indicate that the GSK_OCSP_URL defined responder will be used first and then the responders identified in the AIA extension. This is the default.

Specify GSK_OCSP_URL_PRIORITY_OFF to indicate that the responder identified in the AIA extension will be used first and then the GSK_OCSP_URL defined responder.

GSK_OCSP_URL_PRIORITY can be specified only 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 be specified only 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 be specified only for an SSL environment.

GSK_REQ_CACHED_SESSION

Specify GSK_REQ_CACHED_SESSION_ON to require the cached session identified by GSK_PEER_ID to be used for an upcoming SSL V3, TLS 1.0, or higher secure connection. If either a cached or full handshake is allowed, specify GSK_REQ_CACHED_SESSION_OFF.

GSK_REQ_CACHED_SESSION_OFF is the default setting.

GSK_REQ_CACHED_SESSION can be specified only for an SSL environment and is only applicable for client connections.

GSK_REVOCATION_SECURITY_LEVEL

Specifies the level of security to be used when contacting an OCSP responder or an HTTP server specified in a URI value of the CDP extension.

Three levels of security are available:

GSK_REVOCATION_SECURITY_LEVEL_LOW: Certificate validation does not fail if the OCSP responder or HTTP server specified in the URI value of the CDP extension cannot be contacted.
GSK_REVOCATION_SECURITY_LEVEL_MEDIUM: Certificate validation requires the OCSP responder or the HTTP server in a URI value in the CDP extension to be contactable. For an OCSP responder, it must be able to provide a valid certificate revocation status. If the certificate status is revoked or unknown, certificate validation fails. For an HTTP server in a CDP extension, it must be contactable and able to provide a CRL. This is the default setting.
GSK_REVOCATION_SECURITY_LEVEL_HIGH: Certificate validation requires revocation information to be provided by the OCSP responder or HTTP server. If OCSP revocation checking via the AIA extension is enabled, there must be HTTP URI values present in the certificate that are able to be contactable and able to provide a valid certificate revocation status. If HTTP CRL checking is enabled, there must be HTTP URI values in the CDP extension that are able to be contactable and able to provide a CRL.

GSK_REVOCATION_SECURITY_LEVEL can be specified only 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 be specified only 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_TLS_CBC_PROTECTION_METHOD

Specifies an optional SSL V3.0 or TLS V1.0 CBC IV protection method when writing application data.

Specify GSK_TLS_CBC_PROTECTION_METHOD_NONE to indicate that no CBC protection is enabled. This is the default.

Specify GSK_TLS_CBC_PROTECTION_METHOD_ZEROBYTEFRAGMENT to indicate that zero byte record fragmenting is enabled. When specified, a zero byte record fragment is sent before the application data records are sent.

Specify GSK_TLS_CBC_PROTECTION_METHOD_ONEBYTEFRAGMENT to indicate that one byte record fragmenting is enabled. When specified, the first record is sent in two record fragments with the first record fragment containing only one byte of application data. The rest of the application data from the first record is sent in the second record fragment. All the following records are written whole. For example, a write of 256 bytes of data that is broken into 64 byte record fragments would be written as:

1 byte, 63 bytes, 64 bytes, 64 bytes, 64 bytes

GSK_TLS_CBC_PROTECTION_METHOD can only be specified for an SSL environment.

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.

gsk_attribute_set_enum()

Format

Parameters

Results

Usage

Related Topics