gsk_attribute_get_enum()--Get enumerated information about a secure session or an SSL environment
Syntax
#include <gskssl.h> int gsk_attribute_get_enum(gsk_handle my_gsk_handle, GSK_ENUM_ID enumID, GSK_ENUM_VALUE *enumValue);Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The gsk_attribute_get_enum() function is used to obtain values for specific enumerated data for a secure session or an SSL environment.
Parameters
- my_gsk_handle (Input)
- Indicates one of the following handles:
- The handle for the secure session. (my_session_handle)
- The handle for the SSL environment. (my_env_handle)
- enumID (Input)
- The following values can be used to retrieve information about the secure
session or SSL environment that is either defaulted or explicitly set:
-
GSK_PROTOCOL_TLSV1 (407) - Whether the TLS Version 1.x
protocols are enabled or disabled for this secure session or SSL environment.
The enumValue returned will be one of the following values:
- GSK_PROTOCOL_TLSV1_ON (518) - TLS Version 1.x protocols are enabled.
- GSK_PROTOCOL_TLSV1_OFF (519) - TLS Version 1.x protocols
are disabled.
For compatibility with previous releases, this value is a master switch for all of the TLS version 1.x protocols. Each of the individual TLS1x protocol settings (GSK_PROTOCOL_TLSV10, GSK_PROTOCOL_TLSV11, and GSK_PROTOCOL_TLSV12) will override this setting, however those individual settings get their default value from this setting.
- GSK_PROTOCOL_TLSV12 (438) - Whether the TLS Version 1.2
protocol is enabled or disabled for this secure session or SSL environment. The
enumValue returned will be one of the following values:
- GSK_TRUE (1) - TLS Version 1.2 protocol is enabled.
- GSK_FALSE (0) - TLS Version 1.2 protocol is disabled.
- GSK_PROTOCOL_TLSV11 (437) - Whether the TLS Version 1.1
protocol is enabled or disabled for this secure session or SSL environment. The
enumValue returned will be one of the following values:
- GSK_TRUE (1) - TLS Version 1.1 protocol is enabled.
- GSK_FALSE (0) - TLS Version 1.1 protocol is disabled.
- GSK_PROTOCOL_TLSV10 (436) - Whether the TLS Version 1.0
protocol is enabled or disabled for this secure session or SSL environment. The
enumValue returned will be one of the following values:
- GSK_TRUE (1) - TLS Version 1.0 protocol is enabled.
- GSK_FALSE (0) - TLS Version 1.0 protocol is disabled.
- GSK_PROTOCOL_SSLV3 (404) - Whether the SSL Version 3
protocol is enabled or disabled for this secure session or SSL environment. The
enumValue returned will be one of the following values:
- GSK_PROTOCOL_SSLV3_ON (512) - SSL Version 3 protocol is enabled.
- GSK_PROTOCOL_SSLV3_OFF (513) - SSL Version 3 protocol is disabled.
- GSK_PROTOCOL_SSLV2 (403) - Whether the SSL Version 2
protocol is enabled or disabled for this secure session or SSL environment. The
enumValue returned will be one of the following values:
- GSK_PROTOCOL_SSLV2_ON (510) - SSL Version 2 protocol is enabled.
- GSK_PROTOCOL_SSLV2_OFF (511) - SSL Version 2 protocol is disabled.
- GSK_SESSION_TYPE (402) - Type of handshake to be used for
this secure session or SSL environment. The enumValue returned will be one
of the following values:
- GSK_CLIENT_SESSION (507) - Secure sessions act as clients.
- GSK_SERVER_SESSION (508) - Secure sessions act as a server with no client authentication. The client certificate is not requested.
- GSK_SERVER_SESSION_WITH_CL_AUTH (509) - Secure sessions act as a server that requests the client to send a certificate. The value for GSK_CLIENT_AUTH_TYPE will determine what happens if the client certificate is not valid or not provided.
- GSK_SERVER_SESSION_WITH_CL_AUTH_CRITICAL (594) - Secure sessions act as a server that requires the client to send a certificate. If the client does not send a certificate, the secure session will not start, and gsk_secure_soc_init() will return GSK_ERROR_NO_CERTIFICATE. This provides the same functionality as setting GSK_SERVER_SESSION_WITH_CL_AUTH and GSK_IBMI_CLIENT_AUTH_REQUIRED.
- GSK_CLIENT_AUTH_TYPE (401) - Type of client authentication
to use for this session. The enumValue returned will be one of the following values:
- GSK_CLIENT_AUTH_FULL (503) - All received certificates are
validated. If a certificate that is not valid is received, the secure session
does not start, and an error code is returned from
gsk_secure_soc_init().
If no certificate is sent by the client, the start of the secure session is successful. Applications can detect this situation by checking the GSK_CERTIFICATE_VALIDATION_CODE enumId via gsk_attribute_get_numeric_value(). A numValue of GSK_ERROR_NO_CERTIFICATE will indicate no certificate was sent by client. In this case, the application is responsible for the authentication of the client.
- GSK_CLIENT_AUTH_PASSTHRU (505) - All received certificates
are validated. If validation is successful or validation fails because the
certificate is expired, or does not have a trusted root, the
secure session will start. For the other validation failure cases the secure
session does not start, and an error code is returned from
gsk_secure_soc_init(). Applications can detect the situation
where the secure session started but validation failed by checking the
GSK_CERTIFICATE_VALIDATION_CODE enumId via
gsk_attribute_get_numeric_value(). The numValue will
indicate the certificate validation return code for client's certificate. In
this situation, the application is responsible for the authentication of the
client.
If no certificate is sent by the client, the start of the secure session is successful. Applications can detect this situation by checking the GSK_CERTIFICATE_VALIDATION_CODE enumId as well. A numValue of GSK_ERROR_NO_CERTIFICATE will indicate no certificate was sent by client. In this case, the application is also responsible for the authentication of the client.
- GSK_IBMI_CLIENT_AUTH_REQUIRED (6995) - All received certificates are validated. If a certificate that is not valid is received, the secure session does not start, and an error code is returned from gsk_secure_soc_init(). If no certificate is sent by the client, the secure session does not start, and an error code of GSK_ERROR_NO_CERTIFICATE is returned from gsk_secure_soc_init().
- GSK_CLIENT_AUTH_FULL (503) - All received certificates are
validated. If a certificate that is not valid is received, the secure session
does not start, and an error code is returned from
gsk_secure_soc_init().
-
GSK_ALLOW_UNAUTHENTICATED_RESUME (423) - Indicate if a
cached handshake can be used if the client did not provide a certificate
during the initial handshake. This attribute is only relevant when the
server is configured for optional (GSK_CLIENT_AUTH_PASSTHRU or
GSK_CLIENT_AUTH_FULL) client authentication. The enumValue returned will be one of the following values:
- GSK_ALLOW_UNAUTHENTICATED_RESUME_ON (588) - A session resume can use a session ID without an associated client certificate for the cached handshake.
- GSK_ALLOW_UNAUTHENTICATED_RESUME_OFF (589) - A session resume attempt will force a full SSL handshake if the proposed session ID to resume does not have an associated client certificate. The server will have the opportunity to ask the client for a certificate again.
- GSK_PROTOCOL_USED (405) - Which protocol was used for this
secure session. The enumValue returned will be one of the following values:
- GSK_PROTOCOL_USED_TLSV12 (596) - The protocol used for this secure session is TLS Version 1.2
- GSK_PROTOCOL_USED_TLSV11 (595) - The protocol used for this secure session is TLS Version 1.1
- GSK_PROTOCOL_USED_TLSV1 (520) - The protocol used for this secure session is TLS Version 1.0
- GSK_PROTOCOL_USED_SSLV3 (515) - The protocol used for this secure session is SSL Version 3.
- GSK_PROTOCOL_USED_SSLV2 (514) - The protocol used for this
secure session is SSL Version 2.
- GSK_SID_FIRST (406) - Whether a full handshake or
abbreviated handshake occurred for this secure session. The enumValue
returned will be one of the following values:
- GSK_SID_IS_FIRST (516) - A full handshake occurred for this secure session.
- GSK_SID_NOT_FIRST (517) - An abbreviated handshake occurred for this secure session.
- GSK_SERVER_AUTH_TYPE (410) - Type of server authentication
to use for this session. The enumValue returned will be one of the following values:
- GSK_SERVER_AUTH_FULL (534) - All received
certificates are validated. If a certificate that is not valid is received, the
secure session does not start, and an error code is returned from
gsk_secure_soc_init(). If no certificate is sent by the
server, the secure session does not start, and an error code of
GSK_ERROR_NO_CERTIFICATE is returned from
gsk_secure_soc_init().
- GSK_SERVER_AUTH_PASSTHRU (535) - All received certificates
are validated. If validation is successful or validation fails because the
certificate has expired or does not have a trusted root, the
secure session will start. For the other validation failure cases the secure
session does not start, and an error code is returned from
gsk_secure_soc_init(). Applications can detect the situation
where the secure session started but validation failed by checking the
GSK_CERTIFICATE_VALIDATION_CODE enumId via
gsk_attribute_get_numeric_value().
The numValue will indicate the certificate validation return code for
server's certificate. In
this situation, the application is responsible for the authentication of the
server.
It is highly recommended that this option only be used if an alternate authentication method is used.
- GSK_SERVER_AUTH_FULL (534) - All received
certificates are validated. If a certificate that is not valid is received, the
secure session does not start, and an error code is returned from
gsk_secure_soc_init(). If no certificate is sent by the
server, the secure session does not start, and an error code of
GSK_ERROR_NO_CERTIFICATE is returned from
gsk_secure_soc_init().
- GSK_ENVIRONMENT_CLOSE_OPTIONS (411) -
Type of special close options to use for this environment. If
gsk_environment_close() is issued prior to all secure sessions being closed, the active
secure sessions will continue to work and the environment close will effectively be
delayed. The resources for the SSL environment will not be freed up until after the last
secure session closes. No new secure sessions will be allowed to start using the closed
SSL environment. The enumValue returned will be one of the following values:
- GSK_DELAYED_ENVIRONMENT_CLOSE (536) - Enable the environment close callback routine support.
- GSK_NORMAL_ENVIRONMENT_CLOSE (537) - Field is ignored.
-
GSK_OCSP_ENABLE (426) - Enable Online Certificate Status
Protocol (OCSP) certificate revocation checking using Authority Information Access
(AIA) certificate extension information. If the certificate being validated
has an AIA extension, the first OCSP responder identified in the AIA
extension will be queried for revocation status. See the usage notes for
further use of this attribute in conjunction with GSK_OCSP_URL.
The enumValue returned will be one of the following values:
- GSK_TRUE (1) - Enable OCSP certificate revocation checking via AIA extension.
- GSK_FALSE (0) - Disable OCSP certificate revocation checking via AIA extension.
- GSK_OCSP_NONCE_GENERATION_ENABLE (428) - Enable OCSP nonce
extension generation as part of the OCSP request.
The enumValue returned will be one of the following values:
- GSK_TRUE (1) - Enable OCSP nonce extension generation and send nonce in OCSP requests.
- GSK_FALSE (0) - Disable OCSP nonce extension generation.
- GSK_OCSP_NONCE_CHECK_ENABLE (427) - Determine if OCSP
nonce extension checking is required. The nonce extension improves security
to prevent replay attacks by validating that the request matches the
response. The enumValue returned will be one of the following values:
- GSK_TRUE (1) - Enable OCSP nonce extension validation. If the OCSP response nonce does not match the nonce sent in the OCSP request, the response is rejected.
- GSK_FALSE (0) - Disable OCSP nonce extension validation.
Setting GSK_OCSP_NONCE_CHECK_ENABLE to GSK_TRUE will automatically set GSK_OCSP_NONCE_GENERATION_ENABLE to GSK_TRUE.
- GSK_OCSP_RETRIEVE_VIA_GET (435) - The method with
which the OCSP request will be sent. If enumValue is set to GSK_TRUE, the
OCSP request will be sent via HTTP GET if the total request size after
BASE64 encoding is less than or equal to 255 bytes. If enumValue is
GSK_FALSE or the total request size after encoding is greater than 255 bytes
the request will be sent via HTTP POST. The enumValue returned will be one of the following values:
- GSK_TRUE (1) - Send OCSP request via HTTP GET when possible.
- GSK_FALSE (0) - Always send OCSP request via HTTP POST.
This option must be set to GSK_TRUE as one of the steps to comply with RFC 5019: The Lightweight Online Certificate Status Protocol (OCSP) Profile for High-Volume Environments.
- GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT (451) -
Client session RFC 5746 renegotiation indication requirement level. The
initial system SSL default is GSK_FALSE however that default can be changed
using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
The enumValue returned will be one of the following values:
- GSK_TRUE (1) - The server must provide RFC 5746 renegotiation indication during the initial handshake in order for the handshake to be successful. Warning - The client will no longer be able to handshake with servers that have not or can not be updated to support RFC 5746.
- GSK_FALSE (0) - RFC 5746 renegotiation indication from the server is not required on initial handshake. RFC 5746 renegotiation indication will still be required for all renegotiated handshakes.
- GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER (452) -
Server session RFC 5746 renegotiation indication requirement level. The
initial system SSL default is GSK_FALSE however that default can be changed
using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
The enumValue returned will be one of the following values:
- GSK_TRUE (1) - The client must provide RFC 5746 renegotiation indication during the initial handshake in order for the handshake to be successful. Warning - The server will no longer be able to handshake with clients that have not or can not be updated to support RFC 5746.
- GSK_FALSE (0) - RFC 5746 renegotiation indication from the client is not required on initial handshake. RFC 5746 renegotiation indication will still be required for all renegotiated handshakes.
- GSK_CERTREQ_DNLIST_ENABLE (457) - Enables the sending of
the distinguished name (DN) list in the CertificateRequest message. This
attribute only applies to a server.
The enumValue returned will be one of the following values:
- GSK_TRUE (1) - The DN list is sent.
- GSK_FALSE (0) - The DN list is not sent.
-
GSK_PROTOCOL_TLSV1 (407) - Whether the TLS Version 1.x
protocols are enabled or disabled for this secure session or SSL environment.
The enumValue returned will be one of the following values:
- enumValue (Output)
- Specifies a pointer to an integer in which to place the value of the requested information.
Authorities
No authorization is required.
Return Value
gsk_attribute_get_enum() returns an integer. Possible values are:
- [GSK_OK]
- gsk_attribute_get_enum() was successful.
- [GSK_ATTRIBUTE_INVALID_ID]
- The specified enumID was not valid.
- [GSK_INVALID_HANDLE]
- The specified handle was not valid.
- [GSK_IBMI_ERROR_INVALID_POINTER]
- The enumValue pointer is not valid.
- [GSK_ERROR_UNSUPPORTED]
- The enumID is currently not supported.
- [GSK_ERROR_IO]
- An error occurred in SSL processing, check the errno value.
Error Conditions
When the gsk_attribute_get_enum() API fails with return code [GSK_ERROR_IO], errno can be set to:
- [EINTR]
- Interrupted function call.
- [EDEADLK]
- Resource deadlock avoided.
- [ETERM]
- Operation terminated.
If an errno is returned that is not in this list, look in Errno Values for UNIX®-Type Functions for a description of the errno.
Usage Notes
- The following GSK_ENUM_ID values may be retrieved from the SSL environment
after gsk_environment_open().
- GSK_PROTOCOL_TLSV12
- GSK_PROTOCOL_TLSV11
- GSK_PROTOCOL_TLSV10
- GSK_PROTOCOL_TLSV1
- GSK_PROTOCOL_SSLV3
- GSK_PROTOCOL_SSLV2
- GSK_SESSION_TYPE
- GSK_CLIENT_AUTH_TYPE
- GSK_SERVER_AUTH_TYPE
- GSK_ENVIRONMENT_CLOSE_OPTIONS
- GSK_OCSP_ENABLE
- GSK_OCSP_NONCE_CHECK_ENABLE
- GSK_OCSP_NONCE_GENERATION_ENABLE
- GSK_OCSP_RETRIEVE_VIA_GET
- GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT
- GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER
- GSK_ALLOW_UNAUTHENTICATED_RESUME
- GSK_CERTREQ_DNLIST_ENABLE
- The following GSK_ENUM_ID values may be retrieved from the secure session
after gsk_secure_soc_open().
- GSK_PROTOCOL_TLSV12
- GSK_PROTOCOL_TLSV11
- GSK_PROTOCOL_TLSV10
- GSK_PROTOCOL_TLSV1
- GSK_PROTOCOL_SSLV3
- GSK_PROTOCOL_SSLV2
- GSK_PROTOCOL_USED
- GSK_SESSION_TYPE
- GSK_CLIENT_AUTH_TYPE
- GSK_SID_FIRST
- GSK_SERVER_AUTH_TYPE
- The following GSK_ENUM_ID values are defaulted after gsk_secure_soc_open() and will be set for the
secure session after gsk_secure_soc_init() or
gsk_secure_soc_misc().
- GSK_PROTOCOL_USED
- GSK_SID_FIRST
- When
GSK_IBMI_APPLICATION_ID is set, the settings of some of the SSL environment
attributes will be determined by the corresponding value in the Application ID
definition in Digital Certificate Manager (DCM). These are the enum
attributes that can be overwritten by DCM during the call to gsk_environment_init():
- GSK_PROTOCOL_TLSV12
- GSK_PROTOCOL_TLSV11
- GSK_PROTOCOL_TLSV10
- GSK_PROTOCOL_TLSV1
- GSK_PROTOCOL_SSLV3
- GSK_PROTOCOL_SSLV2
- GSK_OCSP_ENABLE
- GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT
- GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER
Related Information
- gsk_attribute_get_buffer()--Get
character information about a secure session or an SSL environment
- gsk_attribute_get_numeric_value()--Get
numeric information about a secure session or an SSL environment
- gsk_attribute_get_cert_info()--Get
information about a local or partner certificate
- gsk_attribute_set_enum()--Set
enumerated information for a secure session or an SSL environment
- gsk_environment_close()--Close the SSL
environment
- gsk_environment_init()--Initialize an
SSL environment
- gsk_environment_open()--Get a handle for
an SSL environment
- gsk_secure_soc_close()--Close a secure
session
- gsk_secure_soc_init()--Negotiate a secure
session
- gsk_secure_soc_misc()--Perform
miscellaneous functions for a secure session
- gsk_secure_soc_open()--Get a handle for a
secure session
- gsk_strerror()--Retrieve GSK runtime error message
API introduced: V5R1
Top | UNIX-Type APIs | APIs by category |