gsk_attribute_get_enum()

Gets an enumerated value.

Format

   #include <gskssl.h>

   gsk_status gsk_attribute_get_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: Returns 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 is closed or the SSL connection is established.

Usage

The gsk_attribute_get_enum() routine returns an enumerated value for an SSL environment or an SSL connection.

These enumeration identifiers are supported:

GSK_3DES_KEYCHECK

Returns GSK_3DES_KEYCHECK_ON when key parts are compared for uniqueness.

Returns GSK_3DES_KEYCHECK_OFF when key parts are not compared for uniqueness.

GSK_3DES_KEYCHECK can be specified only for an SSL environment.

GSK_AIA_CDP_PRIORITY

Returns GSK_AIA_CDP_PRIORITY_ON to indicate that the AIA extension and GSK_OCSP_URL is queried before examining the CDP extension.

Returns GSK_AIA_CDP_PRIORITY_OFF to indicate that the HTTP URI values specified in the CDP extension is contacted before attempting to contact the OCSP responders in the AIA extension or the OCSP responder that are specified in GSK_OCSP_URL.

GSK_AIA_CDP_PRIORITY can be specified only for an SSL environment.

GSK_CERT_VALIDATE_KEYRING_ROOT

Returns GSK_CERT_VALIDATE_KEYRING_ROOT_ON if SAF key ring certificates must be validated to the root CA certificate.

Returns 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.

GSK_CERT_VALIDATE_KEYRING_ROOT can only be specified for an SSL environment.

GSK_CERT_VALIDATION_MODE

Returns GSK_CERT_VALIDATION_MODE_2459 if certificate validation is based on the RFC 2459 method, GSK_CERT_VALIDATION_MODE_3280 if certificate validation is based on the RFC 3280 method, and GSK_CERT_VALIDATION_MODE_5280 if certificate validation is based on the RFC 5280 method.

Returns 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_CLIENT_AUTH_ALERT

Returns GSK_CLIENT_AUTH_NOCERT_ALERT_OFF if the SSL server application is configured to allow client connections where client authentication is requested and the client failed to supply an X.509 certificate.

Returns GSK_CLIENT_AUTH_NOCERT_ALERT_ON if the SSL server application is configured to terminate client connections where client authentication is requested and the client failed to supply an X.509 certificate.

GSK_CLIENT_AUTH_ALERT can be specified only for an SSL environment.

GSK_CLIENT_AUTH_TYPE

Returns GSK_CLIENT_AUTH_FULL_TYPE if received certificates are validated by the System SSL runtime and GSK_CLIENT_AUTH_PASSTHRU_TYPE otherwise.

GSK_CLIENT_AUTH_TYPE can be specified only for an SSL environment.

GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE

Returns GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE_2048 when a client application wants to enforce a minimum group size of 2048 for each ephemeral DH server handshake.

Returns GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE_LEGACY when a client application wants to enforce a minimum group size of 1024 for each new server handshake in non-FIPS mode and group size 2048 when operating in FIPS mode.

GSK_CLIENT_EPHEMERAL_DH_GROUP_SIZE can be specified only for an SSL environment.

GSK_CRL_CACHE_TEMP_CRL

Returns GSK_CRL_CACHE_TEMP_CRL_ON if a temporary LDAP CRL cache entry is added to the LDAP CRL cache when the CRL does not exist on the LDAP server.

Returns GSK_CRL_CACHE_TEMP_CRL_OFF if a temporary LDAP CRL cache entry is not added to the LDAP CRL cache when the CRL does not exist on the LDAP server.

GSK_CRL_CACHE_TEMP_CRL can be specified only for an SSL environment.

GSK_CRL_CACHE_EXTENDED

Returns GSK_CRL_CACHE_EXTENDED_ON to indicate that LDAP extended CRL cache support is enabled.

Returns GSK_CRL_CACHE_EXTENDED_OFF to indicate that LDAP basic CRL cache support is enabled.

GSK_CRL_CACHE_EXTENDED can be specified only for an SSL environment.

GSK_CRL_SECURITY_LEVEL

Returns GSK_CRL_SECURITY_LEVEL_LOW if certificate validation does not fail if the LDAP server cannot be contacted.

Returns GSK_CRL_SECURITY_LEVEL_MEDIUM if certificate validation requires the LDAP server to be contactable, but does not require a CRL to be defined.

Returns GSK_CRL_SECURITY_LEVEL_HIGH if certificate validation requires that CRL revocation information is provided from the LDAP server.

GSK_ENABLE_CLIENT_SET_PEERID

Returns GSK_ENABLE_CLIENT_SET_PEERID_ON if the use of a cached peer ID was enabled for the current SSL environment by a call to gsk_attribute_set_enum() for this enum.

Returns GSK_ENABLE_CLIENT_SET_PEERID_OFF if the use of a cached peer ID was not enabled for the current SSL environment.

GSK_ENABLE_CLIENT_SET_PEERID is only valid for an SSL V3, TLS 1.0, or higher secure connection and is only meaningful if specified for a client connection within an SSL environment.

GSK_EXTENDED_RENEGOTIATION_INDICATOR

Returns GSK_EXTENDED_RENEGOTIATION_INDICATOR_OPTIONAL if renegotiation indication is not required during the initial SSL V3 or TLS handshake. This is the default.

Returns GSK_EXTENDED_RENEGOTIATION_INDICATOR_CLIENT if the client initial handshake is allowed to proceed only if the server indicates support for RFC 5746 renegotiation.

Returns GSK_EXTENDED_RENEGOTIATION_INDICATOR_SERVER if the server initial handshake is allowed to proceed only if the client indicates support for RFC 5746 renegotiation.

Returns GSK_EXTENDED_RENEGOTIATION_INDICATOR_BOTH if the server and client initial handshakes are allowed to proceed only if the partner indicates support for RFC 5746 renegotiation.

GSK_EXTENDED_RENEGOTIATION_INDICATOR can only be specified for an SSL environment.

GSK_HTTP_CDP_ENABLE

Returns GSK_HTTP_CDP_ENABLE_ON if certificate revocation checking is using the HTTP URI values in the CDP extension to locate an HTTP server.

Returns GSK_HTTP_CDP_ENABLE_OFF if certificate revocation checking is not using the HTTP URI values in the CDP extension.

GSK_HTTP_CDP_ENABLE can be specified only for an SSL environment.

GSK_OCSP_ENABLE

Returns GSK_OCSP_ENABLE_ON if certificate revocation checking is using the HTTP URI values in the AIA extension to locate an OCSP responder.

Returns GSK_OCSP_ENABLE_OFF if certificate revocation checking is not using the HTTP URI values in the AIA extension.

GSK_OCSP_ENABLE can be specified only for an SSL environment.

GSK_OCSP_NONCE_CHECK_ENABLE

Returns GSK_OCSP_NONCE_CHECK_ENABLE_ON if the nonce in the OCSP response is verified to ensure it matches the nonce sent in the OCSP request.

Returns GSK_OCSP_NONCE_CHECK_ENABLE_OFF if checking of the nonce in the OCSP response is disabled.

GSK_OCSP_NONCE_CHECK_ENABLE can be specified only for an SSL environment.

GSK_OCSP_NONCE_GENERATION_ENABLE

Returns GSK_OCSP_NONCE_GENERATION_ENABLE_ON if OCSP requests include a generated nonce.

Returns GSK_OCSP_NONCE_GENERATION_ENABLE_OFF if OCSP nonce generation is disabled.

GSK_OCSP_NONCE_GENERATION_ENABLE can be specified only for an SSL environment.

GSK_OCSP_RETRIEVE_VIA_GET

Returns GSK_OCSP_RETRIEVE_VIA_GET_ON if the HTTP GET request should be used when sending an OCSP request.

Returns GSK_OCSP_RETRIEVE_VIA_GET_OFF if the HTTP request will always be sent via an HTTP POST.

GSK_OCSP_RETRIEVE_VIA_GET can be specified only for an SSL environment.

GSK_OCSP_URL_PRIORITY

Returns GSK_OCSP_URL_PRIORITY_ON if the GSK_OCSP_URL defined responder will first be used and then the responders identified in the AIA extension.

Returns GSK_OCSP_URL_PRIORITY_OFF if the responders 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_PEER_CERT_MIN_VERSION

Returns GSK_PEER_CERT_MIN_VERSION_3 when the partner's X.509 end-entity certificate must be version 3.

Returns GSK_PEER_CERT_MIN_VERSION_ANY when the partner's X.509 end-entity certificate can be any supported System SSL version.

GSK_PEER_CERT_MIN_VERSION can be specified only for an SSL environment.

GSK_PROTOCOL_SSLV2

Returns GSK_PROTOCOL_SSLV2_ON if the SSL Version 2 protocol is enabled and GSK_PROTOCOL_SSLV2_OFF if the SSL Version 2 protocol is not enabled.

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

GSK_PROTOCOL_SSLV3

Returns GSK_PROTOCOL_SSLV3_ON if the SSL Version 3 protocol is enabled and GSK_PROTOCOL_SSLV3_OFF if the SSL Version 3 protocol is not enabled.

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

GSK_PROTOCOL_TLSV1

Returns GSK_PROTOCOL_TLSV1_ON if the TLS Version 1 protocol is enabled and GSK_PROTOCOL_TLSV1_OFF if the TLS Version 1 protocol is not enabled.

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

GSK_PROTOCOL_TLSV1_1

Returns GSK_PROTOCOL_TLSV1_1_ON if the TLS Version 1.1 protocol is enabled and GSK_PROTOCOL_TLSV1_1_OFF if the TLS Version 1.1 protocol is not enabled.

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

GSK_PROTOCOL_TLSV1_2

Returns GSK_PROTOCOL_TLSV1_2_ON if the TLS Version 1.2 protocol is enabled and GSK_PROTOCOL_TLSV1_2_OFF if the TLS Version 1.2 protocol is not enabled.

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

GSK_PROTOCOL_USED

Returns GSK_PROTOCOL_USED_SSLV2 if the SSL Version 2 protocol was used to establish the connection, GSK_PROTOCOL_USED_SSLV3 if the SSL Version 3 protocol was used to establish the connection, GSK_PROTOCOL_USED_TLSV1 if the TLS Version 1.0 protocol was used to establish the connection, GSK_PROTOCOL_USED_TLSV1_1 if the TLS Version 1.1 protocol was used to establish the connection, or GSK_PROTOCOL_USED_TLSV1_2 if the TLS Version 1.2 protocol was used to establish the connection.

GSK_NULL is returned if a connection is not established. GSK_PROTOCOL_USED can be specified only for an SSL connection.

GSK_RENEGOTIATION

Returns GSK_RENEGOTIATION_NONE if SSL V3 and TLS handshake renegotiation as a server is disabled, while RFC 5746 renegotiation is allowed. This is the default.

Returns GSK_RENEGOTIATION_DISABLED if SSL V3 and TLS handshake renegotiation, including RFC 5746 renegotiation, is disabled.

Returns GSK_RENEGOTIATION_ALL if SSL V3 and TLS handshake renegotiation as a server is enabled.

Returns GSK_RENEGOTIATION_ABBREVIATED if SSL V3 and TLS abbreviated handshake renegotiation for resuming the current session only is permitted as a server. RFC 5746 renegotiation is also allowed.

GSK_RENEGOTIATION can only be specified for an SSL environment.

GSK_RENEGOTIATION_PEER_CERT_CHECK

Returns GSK_RENEGOTIATION_PEER_CERT_CHECK_OFF if an identity check against the peer's certificate is not performed during renegotiation. This is the default.

Returns GSK_RENEGOTIATION_PEER_CERT_CHECK_ON if a comparison is performed 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_REQ_CACHED_SESSION

Returns GSK_REQ_CACHED_SESSION_ON if a particular cached session peer ID is wanted for an upcoming SSL V3, TLS 1.0, or higher secure connection.

Returns GSK_REQ_CACHED_SESSION_OFF if cached session reuse is not active.

GSK_REQ_CACHED_SESSION is only meaningful if specified for a client connection.

GSK_REVOCATION_SECURITY_LEVEL

Returns GSK_REVOCATION_SECURITY_LEVEL_LOW if certificate validation does not fail if the OCSP responder or HTTP server specified in the URI value of the CDP extension cannot be contacted.

Returns GSK_REVOCATION_SECURITY_LEVEL_MEDIUM if certificate validation requires the OCSP responder or the HTTP server specified in the URI value of the CDP extension to be contactable.

Returns GSK_REVOCATION_SECURITY_LEVEL_HIGH if certificate validation requires revocation information is provided by an OCSP responder or HTTP server.

GSK_REVOCATION_SECURITY_LEVEL can be specified only for an SSL environment.

GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE

Returns GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE_2048 when an application wants to enforce a minimum group size of 2048 for each ephemeral DH server handshake.

Returns GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE_LEGACY when an application wants to enforce a minimum group size of 1024 for each new server handshake in non-FIPS mode and group size 2048 when operating in FIPS mode.

Returns GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE_MATCH when an application wants to match the server group size strength to the strength of the server's certificate for each new server handshake.

GSK_SERVER_EPHEMERAL_DH_GROUP_SIZE can be specified only for an SSL environment.

GSK_SERVER_FALLBACK_SCSV

Returns GSK_SERVER_FALLBACK_SCSV_ON to indicate that the server supports the TLS fallback Signaling Cipher Suite Value (SCSV) when included in the client's supported cipher list during an SSL or TLS handshake.

Returns GSK_SERVER_FALLBACK_SCSV_OFF to indicate that the server ignores the SCSV when included in the client's supported cipher list during an SSL or TLS handshake.

GSK_SERVER_FALLBACK_SCSV can be specified only for an SSL environment.

GSK_SERVER_OCSP_STAPLING

Returns GSK_SERVER_OCSP_STAPLING_OFF if the server is not enabled to contact the configured OCSP responders to retrieve the OCSP responses for the server's end entity certificate or the server's certificate chain.

Returns GSK_SERVER_OCSP_STAPLING_ENDENTITY if the server is enabled to contact the configured OCSP responders to retrieve the OCSP response for the server's end entity certificate.

Returns GSK_SERVER_OCSP_STAPLING_ANY if the server is enabled to contact the configured OCSP responders to retrieve the OCSP responses for the server's end entity certificate or the server's certificate chain.

GSK_SERVER_OCSP_STAPLING can be specified only for an SSL environment.

GSK_SERVER_OCSP_STAPLING_CERTSTATUS

Returns GSK_SERVER_OCSP_STAPLING_CERTSTATUS_ENDENTITY if the server is able to successfully retrieve the OCSP response for the server's end entity certificate and send it back to the client.

Returns GSK_SERVER_OCSP_STAPLING_CERTSTATUS_ANY if the server is able to successfully retrieve the OCSP responses for more than one of the server's certificates in its chain and sends them back to the client.

Returns GSK_SERVER_OCSP_STAPLING_CERTSTATUS_OFF if the server is not configured for OCSP stapling or is unable to successfully retrieve the OCSP responses for the server's end entity certificate or any certificates in the server's chain.

GSK_SERVER_OCSP_STAPLING_CERTSTATUS can be specified only for an SSL connection.

GSK_SESSION_TYPE

Returns GSK_CLIENT_SESSION if the SSL handshake is to be performed as a client, GSK_SERVER_SESSION if the SSL handshake is to be performed as a server, or GSK_SERVER_SESSION_WITH_CL_AUTH if the SSL handshake is to be performed as a server requiring client authentication.

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

GSK_SID_FIRST

Returns GSK_SID_IS_FIRST if a full SSL handshake was performed to establish the connection or GSK_SID_NOT_FIRST if an existing session was used to establish the connection.

GSK_NULL is returned if a connection is not established.

GSK_SID_FIRST can be specified only for an SSL connection.

GSK_SUITE_B_PROFILE

Returns the Suite B for TLS profile setting. Returns:

GSK_SUITE_B_PROFILE_128 if the 128-bit Suite B security profile is being applied by the SSL client or server to TLS sessions.
GSK_SUITE_B_PROFILE_128MIN if the 128-bit minimum Suite B security profile is being applied by the SSL client or server to TLS sessions.
GSK_SUITE_B_PROFILE_192 if the 192-bit Suite B security profile is being applied by the SSL client or server to TLS sessions.
GSK_SUITE_B_PROFILE_192MIN if the 192-bit minimum Suite B security profile is being applied by the SSL client or server to TLS sessions.
GSK_SUITE_B_PROFILE_ALL if either the 128-bit or 192-bit Suite B security profile is allowed by the SSL client or server for TLS sessions.
GSK_SUITE_B_PROFILE_OFF if there is no Suite B security profile being applied by the SSL client or server to TLS sessions.

GSK_SUITE_B_PROFILE can be specified only for an SSL environment.

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

Returns GSK_T61_AS_LATIN1_ON if the ISO8859-1 character set is used when converting a string tagged as TELETEXSTRING or GSK_T61_AS_LATIN1_OFF if the T.61 character set is used.

GSK_T61_AS_LATIN1 can be specified only for an SSL environment.

The GSK_T61_AS_LATIN1 setting is global and applies to all SSL environments.

GSK_TLS_CBC_PROTECTION_METHOD

Returns GSK_TLS_CBC_PROTECTION_METHOD_NONE to indicate that no CBC protection is enabled.

Returns GSK_TLS_CBC_PROTECTION_METHOD_ZEROBYTEFRAGMENT to indicate that zero byte record fragmenting is enabled.

Returns GSK_TLS_CBC_PROTECTION_METHOD_ONEBYTEFRAGMENT to indicate that one byte record fragmenting is enabled.

GSK_TLS_CBC_PROTECTION_METHOD can be specified only for an SSL environment.

GSK_TLSEXT_MFL

Returns GSK_TLSEXT_MFL_OFF if the Maximum Fragment Length type TLS extension is not negotiated, and the SSL connection is therefore using the default fragment length (16384 bytes).

Returns GSK_TLSEXT_MFL_512, GSK_TLSEXT_MFL_1024, GSK_TLSEXT_MFL_2048 or GSK_TLSEXT_MFL_4096 if the Maximum Fragment Length type TLS extension is negotiated, where the returned value reflects the negotiated maximum fragment length.

GSK_TLSEXT_MFL can be specified only for an SSL connection.

GSK_TLSEXT_SERVER_OCSP_STAPLING

Returns GSK_TLSEXT_SERVER_OCSP_STAPLING_ON if at least one of the OCSP stapling TLS extensions Certificate Status Request or Multiple Certificate Status Request are negotiated and in use.

Returns GSK_TLSEXT_SERVER_OCSP_STAPLING_OFF if the OCSP stapling TLS extensions Certificate Status Request and Multiple Certificate Status Request are not negotiated.

GSK_TLSEXT_SERVER_OCSP_STAPLING can be specified only for an SSL connection.

GSK_TLSEXT_SNI

Returns GSK_TLSEXT_SNI_ON if the Server Name Indication type TLS extension is negotiated and is in use.

Returns GSK_TLSEXT_SNI_OFF if the Server Name Indication type TLS extension is not negotiated.

GSK_TLSEXT_SNI can be specified only for an SSL connection.

GSK_TLSEXT_THMAC

Returns GSK_TLSEXT_THMAC_ON if the Truncated HMAC type TLS extension is negotiated and is in use.

Returns GSK_TLSEXT_THMAC_OFF if the Truncated HMAC type TLS extension is not negotiated.

GSK_TLSEXT_MFL can be specified only for an SSL connection.

GSK_V3_CIPHERS

Returns GSK_V3_CIPHERS_CHAR2 if two character V3 cipher specifications are in use.

Returns GSK_V3_CIPHERS_CHAR4 if four character V3 cipher specifications are in use.

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