gsk_attribute_set_enum()--Set enumerated information for a secure session or environment

 #include <gskssl.h>

 int gsk_attribute_set_enum(gsk_handle my_gsk_handle,
                            GSK_ENUM_ID enumID,
                            GSK_ENUM_VALUE enumValue);

The gsk_attribute_set_enum() function is used to set a specified enumerated type attribute to an enumerated value in the secure session or 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 secure environment. (my_env_handle)

enumID  (Input) 

Indicates one of the following operations:

• GSK_PROTOCOL_TLSV13 (4030) - Enables or disables the TLS Version 1.3 protocol. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable TLS Version 1.3.
  • GSK_FALSE (0) - Disable TLS Version 1.3.
  
  
  
• GSK_PROTOCOL_TLSV12 (438) - Enables or disables the TLS Version 1.2 protocol. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable TLS Version 1.2.
  • GSK_FALSE (0) - Disable TLS Version 1.2.
  
  
  
• GSK_PROTOCOL_TLSV11 (437) - Enables or disables the TLS Version 1.1 protocol. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable TLS Version 1.1.
  • GSK_FALSE (0) - Disable TLS Version 1.1.
  
  
  
• GSK_PROTOCOL_TLSV10 (436) - Enables or disables the TLS Version 1.0 protocol. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable TLS Version 1.0.
  • GSK_FALSE (0) - Disable TLS Version 1.0.
  
  
  
• GSK_PROTOCOL_TLSV1 (407) - Enables or disables all of the TLS Version 1.x protocols. enumValue must specify one of the following:
  
  
  • GSK_PROTOCOL_TLSV1_ON (518) - Enable TLS Version 1.x.
  • GSK_PROTOCOL_TLSV1_OFF (519) - Disable TLS Version 1.x.
  
  For compatibility with previous releases, this value is a master switch for all of the TLS version 1.x protocols. Each of the individual protocol settings (GSK_PROTOCOL_TLSV13, GSK_PROTOCOL_TLSV12, GSK_PROTOCOL_TLSV11, and GSK_PROTOCOL_TLSV10) will override this setting, but those individual settings get their default value from this setting.
  
  
• GSK_PROTOCOL_SSLV3 (404) - Enables or disables the SSL Version 3 protocol. enumValue must specify one of the following:
  
  
  • GSK_PROTOCOL_SSLV3_ON (512) - Enable SSL Version 3.
  • GSK_PROTOCOL_SSLV3_OFF (513) - Disable SSL Version 3.
  
  
  
• GSK_PROTOCOL_SSLV2 (403) - Enables or disables the SSL Version 2 protocol. enumValue must specify one of the following:
  
  
  • GSK_PROTOCOL_SSLV2_ON (510) - Enable SSL Version 2.
  • GSK_PROTOCOL_SSLV2_OFF (511) - Disable SSL Version 2.
  
  
  
• GSK_SESSION_TYPE (402) - Type of handshake to be used for this secure session or environment. enumValue must specify one of the following operations:
  
  
  • 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 is not asked for a certificate.
  • 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. enumValue must specify one of the following:
  
  
  • GSK_CLIENT_AUTH_FULL (503) - All received certificates are validated. If an invalid certificate 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 through 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.

    NOTE: If Authentication PassThru is set, and the application set the certificate callback to GSK_VALIDATION_REQUIRED, TLS will reject the call with an error code GSK_CONFLICTING_VALIDATION_SETTING. If a certificate validation callback has been set to GSK_VALIDATION_REQUIRED, and application set authentication to PassThru, TLS will also reject the call with an error code GSK_CONFLICTING_VALIDATION_SETTING.

  • 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_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. enumValue must specify one of the following:
  
  
  • 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 TLS 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_SERVER_AUTH_TYPE (410) - Type of server authentication to use for this session. enumValue must specify one of the following:
  
  
  • 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.

    NOTE: If Authentication PassThru is set, and the application set the certificate callback to GSK_VALIDATION_REQUIRED, TLS will reject the call with an error code GSK_CONFLICTING_VALIDATION_SETTING. If a certificate validation callback has been set to GSK_VALIDATION_REQUIRED, and application set authentication to PassThru, TLS will also reject the call with an error code GSK_CONFLICTING_VALIDATION_SETTING.

• 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 secure 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 secure environment. enumValue must specify one of the following:
  
  
  • 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 initial system TLS default is GSK_FALSE however that default can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG. enumValue must specify one of the following:
  
  
  • 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. enumValue must specify one of the following:
  
  
  • 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. enumValue must specify one of the following:
  
  
  • 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. enumValue must specify one of the following:
  
  
  • 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_SSL_EXTN_CERTSTATUSREQ_ENABLE (440) - Enable Certificate Status Request processing. Enabling this option on the server session causes the server to do OCSP stapling if the certificate status request extension is sent by the client. Enabling this option on the client causes the client to send the certificate status request extension to the server. The initial system TLS default is GSK_FALSE however that default can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG. enumValue must specify one of the following values:
  
  
  • GSK_TRUE (1) - Enable Certificate Status Request processing.
  • GSK_FALSE (0) - Disable Certificate Status Request processing on the server session.
  
  
  
  
• GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT (451) - Client session RFC 5746 renegotiation indication requirement level. The initial system TLS default is GSK_FALSE however that default can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. enumValue must specify one of the following:
  
  
  • 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 TLS default is GSK_FALSE however that default can be changed using SSLCONFIG. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. enumValue must specify one of the following:
  
  
  • 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. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - The DN list is sent.
  • GSK_FALSE (0) - The DN list is not sent.
  
  
  
• GSK_STRICT_BASIC_CONSTRAINT (489) - Sets whether non-end entity certificates missing the Basic Constraints extension are permitted to be used in a validation chain. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Certificate authorities without the Basic Constraints extension are not permitted to be used in a validation chain. Warning - This setting may result in interoperability issues with peers the application must communicate with using TLS.
  • GSK_FALSE (0) - No check for Basic Constraints is made.
  
  
  
• GSK_VALIDATE_EXTENDEDKEYUSAGE_ENABLE (430) - Enforcement level for extended key usage (ExtendedKeyUsage) extension checking for end point validation. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable extended key usage extension validation. Warning - This setting may result in interoperability issues with peers the application must communicate with using TLS.
  • GSK_FALSE (0) - Disable extended key usage extension validation.
  
  
  
• GSK_FALLBACK_SCSV_SERVER (495) - Enables support for processing the TLS Fallback Signaling Cipher Suite Value (SCSV) for preventing protocol downgrade attacks on the server. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable support for the TLS Fallback SCSV.
  • GSK_FALSE (0) - Disable support for the TLS Fallback SCSV.
  
  
  
• GSK_SSL_EXTN_ENCRYPTTHENMAC_CLIENT_ENABLE (485) - Enables RFC 7366 Encrypt-Then-MAC (EtM) for TLS support for client sessions. EtM will only be negotiated if the server also supports EtM. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable Encrypt-Then-MAC on the client. The EtM extension will be sent in client hello.
  • GSK_FALSE (0) - Disable Encrypt-Then-MAC on the client. The EtM extension will not be sent in client hello.
  
  
  
• GSK_SSL_EXTN_ENCRYPTTHENMAC_SERVER_ENABLE (484) - Enables RFC 7366 Encrypt-Then-MAC (EtM) for TLS support for server sessions. EtM will only be negotiated if the client also supports EtM. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable Encrypt-Then-MAC on the server. The server will look for the EtM extension in the client hello and if found, agree to use it.
  • GSK_FALSE (0) - Disable Encrypt-Then-MAC on the server. The server will ignore the EtM extension if the client hello contains it.
  
  The default value for GSK_SSL_EXTN_ENCRYPTTHENMAC_SERVER_ENABLE is GSK_TRUE.
  



• GSK_TLS_FEATURES_EXTN_ENABLE (4013) - Require Certificate Status Request processing from a server when the server certificate includes the feature extension defined in RFC 7633. Enabling this option on the client session causes the client to fail the handshake when requesting OCSP stapling if the server's certificate indicates that the server must staple OCSP responses and it does not staple an OCSP response. This value is ignored on server sessions. The initial system TLS default is GSK_FALSE however that default can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG. The enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable features extension.
  • GSK_FALSE (0) - Disable features extension.
  
  
  
• GSK_SSL_EXTN_ENCRYPTTHENMAC_CRITICAL (4014) - Enforces the use of the RFC 7366 Encrypt-Then-MAC (EtM) extension. The Encrypt-Then-MAC extension must be negotiated or the handshake will fail with GSK_ERROR_NO_ENCRYPTTHENMAC_EXTENSION. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. The enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - The Encrypt-Then-MAC extension must be negotiated.
  • GSK_FALSE (0) - The Encrypt-Then-MAC extension is not required to be negotiated.
  
  
  
• GSK_OCSP_CHECK_AIA_FIRST (493) - When both GSK_OCSP_URL and GSK_OCSP_ENABLE are set, the default checking order attempts GSK_OCSP_URL first, then processes the AIA extensions (if revocation status is still undetermined). Setting GSK_OCSP_CHECK_AIA_FIRST to GSK_TRUE reverses that checking order so the AIA extensions are processed before GSK_OCSP_URL is attempted (if revocation status is still undetermined). enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Do OCSP AIA extension checking first.
  • GSK_FALSE (0) - Do OCSP URL checking first.
  
  The default ordering of OCSP responder checking reflects the likelihood that a locally configured OCSP responder (configured via the GSK_OCSP_URL) is more likely to succeed and cache responses, and therefore is quicker than waiting for an AIA-specified OCSP responder to timeout if it fails.
  
  
• GSK_STRICT_SIGALG (466) - Enables signature algorithm checking on all certificates in a chain as required by RFC 5246, instead of only checking the end-entity certificate. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable signature algorithm checking on the full chain.
  • GSK_FALSE (0) - Disable signature algorithm checking on the full chain.
  
  
  
• GSK_STRICT_CLIENT_VERSION_CHECK (468) - Verifies the client set the client version indicator field in the premaster secret on the client hello for strict compliance with RFC 5246. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable checking for strict compliance with RFC 5246.
  • GSK_FALSE (0) - Disable checking for strict compliance with RFC 5246.
  
  This setting is only applicable to a server environment.
  
  
• GSK_SSL_EXTN_SIGALG_SELECT_ALL (483) - Sets the TLS extension signature algorithms to a secure default list of signature algorithms. See the usage notes for the default list of signature algorithms. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Set the signature algorithms to the default secure signature algorithm list.
  • GSK_FALSE (0) - Do not set the signature algorithms to the default secure signature algorithm list.
  
  
  
• GSK_SSL_FIPS_MODE_PROCESSING (420) - Enables all of the necessary GSKit secure operation settings so GSKit SSL/TLS will operate in FIPS-compliant mode. See the usage notes for further use of this attribute. enumValue must specify one of the following:
  
  
  • GSK_SSL_FIPS_MODE_PROCESSING_ON (573) - Enable GSKit SSL/TLS FIPS mode. The setting will restrict GSKit SSL/TLS session negotiation to only use FIPS-approved cipher suites.
  • GSK_SSL_FIPS_MODE_PROCESSING_OFF (574) - Disable GSKit SSL/TLS FIPS mode.
  
  Other settings related to cipher suites, protocol and signature algorithms SHOULD NOT be made after this setting is enabled as it will override the settings made by this call and could cause GSKit to operate in a mode that is not FIPS-compliant.
  
  
• GSK_SSL_SUITEB_MODE_PROCESSING (454) - Enables all of the necessary GSKit secure operation settings so GSKit SSL/TLS will operate in TLS Suite B Profile mode as per RFC 6460. Refer to RFC 6460 for Suite B settings. This setting tracks relevant standards and may change if the relevant standards change. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable TLS Suite B Profile mode. The setting will restrict GSKit SSL/TLS session negotiation to only use TLS Suite B Profile mode.
  • GSK_FALSE (0) - Disable TLS Suite B Profile mode.
  
  Other settings related to cipher suites, protocol and signature algorithms SHOULD NOT be made after this setting is enabled as it will override the settings made by this call and could cause GSKit to operate in a mode that is not compliant with TLS Suite B Profile mode. This setting will enable the TLSv1.2 protocol and disable all others. This setting is currently identical to GSK_SSL_SUITEB_128BIT_MODE_PROCESSING.
  
  
• GSK_SSL_SUITEB_128BIT_MODE_PROCESSING (455) - Enables all of the necessary GSKit secure operation settings so GSKit SSL/TLS will operate in the 128-bit security level of TLS Suite B Profile mode as per RFC 6460. Refer to RFC 6460 for Suite B settings. This setting tracks relevant standards and may change if the relevant standards change. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable the 128-bit security level of TLS Suite B Profile mode. The setting will restrict GSKit SSL/TLS session negotiation to only use the 128-bit security level of TLS Suite B Profile mode.
  • GSK_FALSE (0) - Disable the 128-bit security level of TLS Suite B Profile mode.
  
  Other settings related to cipher suites, protocol and signature algorithms SHOULD NOT be made after this setting is enabled as it will override the settings made by this call and could cause GSKit to operate in a mode that is not compliant with TLS Suite B Profile mode. This setting will enable the TLSv1.2 protocol and disable all others.
  
  
• GSK_SSL_SUITEB_192BIT_MODE_PROCESSING (456) - Enables all of the necessary GSKit secure operation settings so GSKit SSL/TLS will operate in the 192-bit security level of TLS Suite B Profile mode as per RFC 6460. Refer to RFC 6460 for Suite B settings. This setting tracks relevant standards and may change if the relevant standards change. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable the 192-bit security level of TLS Suite B Profile mode. The setting will restrict GSKit SSL/TLS session negotiation to only use the 192-bit security level of TLS Suite B Profile mode.
  • GSK_FALSE (0) - Disable the 192-bit security level of TLS Suite B Profile mode.
  
  Other settings related to cipher suites, protocol and signature algorithms SHOULD NOT be made after this setting is enabled as it will override the settings made by this call and could cause GSKit to operate in a mode that is not compliant with TLS Suite B Profile mode. This setting will enable the TLSv1.2 protocol and disable all others.
  
  
• GSK_NIST_SP800_131A_MODE (477) - Enables all of the necessary GSKit secure operation settings so GSKit SSL/TLS will operate in SP800-131a mode. See the usage notes for further use of this attribute. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable GSKit SSL/TLS SP800-131a mode.
  • GSK_FALSE (0) - Disable GSKit SSL/TLS SP800-131a mode.
  
  
  
• GSK_VACCINATE (497) - Enables all of the recommended GSKit secure operation settings. See the usage notes for further use of this attribute. enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable all of the recommended GSKit settings.
  • GSK_FALSE (0) - Do not enable all of the recommended GSKit settings.
  
  
  
• GSK_SSL_EXTN_EXTENDEDMASTERSECRET_SERVER_ENABLE (4002) - Enables the server to use the RFC 7627 Extended Master Secret (EMS) extension. If the client does not send the Extended Master Secret extension in the client hello, the handshake will continue without using the Extended Master Secret. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. The enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable the EMS extension on the server.
  • GSK_FALSE (0) - Do not enable the EMS extension on the server.
  
  
  
• GSK_SSL_EXTN_EXTENDEDMASTERSECRET_CLIENT_ENABLE (4003) - Enables the client to use the RFC 7627 Extended Master Secret (EMS) extension. If the server does not reply with the Extended Master Secret extension in the server hello, the handshake will continue without using the Extended Master Secret. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. The enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - Enable the EMS extension on the client.
  • GSK_FALSE (0) - Do not enable the EMS extension on the client.
  
  
  
• GSK_SSL_EXTN_EXTENDEDMASTERSECRET_CRITICAL (4004) - Enforces the use of the RFC 7627 Extended Master Secret (EMS) extension. The Extended Master Secret extension must be negotiated or the handshake will fail with GSK_ERROR_NO_EXTENDEDMASTERSECRET_EXTENSION. This attribute has meaning for TLSv1.2 and prior versions; it does not apply to TLSv1.3 and newer versions. The enumValue must specify one of the following:
  
  
  • GSK_TRUE (1) - The EMS extension must be negotiated.
  • GSK_FALSE (0) - The EMS extension is not required to be negotiated.
  
  
  
• GSK_TLS_EXTN_SEND_EMPTY_KEY_SHARE (4031) - Enables the TLS client to send an empty key share extension. This attribute has meaning for TLSv1.3 and newer versions; it does not apply to TLSv1.2 and prior versions. enumValue must specify one of the following:
  • GSK_TRUE (1) - The TLS client will send an empty key share extension.
  • GSK_FALSE (0) - The TLS client will send a valid key share extension.
  
  
  
• GSK_TLSV13_MIDDLEBOXMODE (4034) - Enables TLS middlebox compatibility mode. TLSv1.3 RFC 8446 Appendix D defines an optional Middlebox Compatibility Mode applications can use to mitigate middlebox issues in the network. Middlebox Compatibility Mode makes the TLSv1.3 handshake flow look more like a TLSv1.2 handshake. This is accomplished by filling in legacy fields in handshake messages and by sending a TLSv1.2 handshake message eliminated from the pure TLSv1.3 implementation. These changes make the TLSv1.3 handshake appear similar to a TLSv1.2 session resumption which misbehaving middleboxes understand and generally allow through. This attribute has meaning for TLSv1.3 and newer versions; it does not apply to TLSv1.2 and prior versions. enumValue must specify one of the following:
  • GSK_TRUE (1) - Enable TLS middlebox compatibility mode.
  • GSK_FALSE (0) - Disable TLS middlebox compatibility mode.
  
  
  
• GSK_SSL_EXTN_SESSIONTICKET_RESUMEFORWARDSECRECY (4037) - Ensures forward secrecy by generating a new key share for each resumed session. This attribute has meaning for TLSv1.3 and newer versions; it does not apply to TLSv1.2 and prior versions. enumValue must specify one of the following:
  • GSK_TRUE (1) - Require a key share for resumed sessions.
  • GSK_FALSE (0) - Do not require a key share for resumed sessions.
  
  
  

enumValue  (Input) 

An enumerated type appropriate to the enumID.

Authorities

No authorization is required.

Return Value

gsk_attribute_set_enum() returns an integer. Possible values are:

[GSK_OK]

gsk_attribute_set_enum() was successful.

[GSK_ATTRIBUTE_INVALID_ENUMERATION]

The enumeration specified for the enumValue was not valid.

[GSK_ATTRIBUTE_INVALID_ID]

The enumID specified was not valid.

[GSK_CONFLICTING_VALIDATION_SETTING]

The value for GSK_SERVER_AUTH_TYPE or GSK_CLIENT_AUTH_TYPE conflicts with the setting for the validationCallBack.validateRequired field for GSK_CERT_VALIDATION_CALLBACK set by gsk_attribute_set_callback().

[GSK_INVALID_STATE]

One of the following occurred:

• The enumID cannot be set after a gsk_environment_init() has been issued.
• The enumID cannot be set after a gsk_secure_soc_init() has been issued.

[GSK_INVALID_HANDLE]

The handle specified was not valid.

[GSK_ERROR_UNSUPPORTED]

The enumID is currently not supported.

[GSK_ERROR_IO]

An error occurred in TLS processing, check the errno value.

Error Conditions

When the gsk_attribute_set_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

1. The following GSK_ENUM_ID values may be set in the secure environment after gsk_environment_open() and before gsk_environment_init(). They are used as defaults for subsequent secure sessions:
   
   
   • GSK_PROTOCOL_TLSV13
   • 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_SSL_EXTN_CERTSTATUSREQ_ENABLE
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER
   • GSK_ALLOW_UNAUTHENTICATED_RESUME
   • GSK_CERTREQ_DNLIST_ENABLE
     
   • GSK_STRICT_BASIC_CONSTRAINT
   • GSK_VALIDATE_EXTENDEDKEYUSAGE_ENABLE
   • GSK_FALLBACK_SCSV_SERVER
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_CLIENT_ENABLE
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_SERVER_ENABLE
   • GSK_TLS_FEATURES_EXTN_ENABLE
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_CRITICAL
   • GSK_OCSP_CHECK_AIA_FIRST
   • GSK_STRICT_SIGALG
   • GSK_STRICT_CLIENT_VERSION_CHECK
   • GSK_SSL_FIPS_MODE_PROCESSING
   • GSK_SSL_SUITEB_MODE_PROCESSING
   • GSK_SSL_SUITEB_128BIT_MODE_PROCESSING
   • GSK_SSL_SUITEB_192BIT_MODE_PROCESSING
   • GSK_NIST_SP800_131A_MODE
   • GSK_SSL_EXTN_SIGALG_SELECT_ALL
   • GSK_VACCINATE
   • GSK_SSL_EXTN_EXTENDEDMASTERSECRET_SERVER_ENABLE
   • GSK_SSL_EXTN_EXTENDEDMASTERSECRET_CLIENT_ENABLE
   • GSK_SSL_EXTN_EXTENDEDMASTERSECRET_CRITICAL
   • GSK_TLS_EXTN_SEND_EMPTY_KEY_SHARE
   • GSK_TLSV13_MIDDLEBOXMODE
   • GSK_SSL_EXTN_SESSIONTICKET_RESUMEFORWARDSECRECY
     
   
   
2. The following GSK_ENUM_ID values may be set for each individual secure session after gsk_secure_soc_open() and before gsk_secure_soc_init(). These values will override values set in the secure environment:
   
   
   • GSK_PROTOCOL_TLSV13
   • 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_SSL_EXTN_ENCRYPTTHENMAC_CLIENT_ENABLE
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_SERVER_ENABLE
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_CRITICAL
   • GSK_SSL_EXTN_EXTENDEDMASTERSECRET_SERVER_ENABLE
   • GSK_SSL_EXTN_EXTENDEDMASTERSECRET_CLIENT_ENABLE
   • GSK_SSL_EXTN_EXTENDEDMASTERSECRET_CRITICAL
     
   
   
3. When GSK_IBMI_APPLICATION_ID is set, the settings of some of the secure 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_TLSV13
   • GSK_PROTOCOL_TLSV12
   • GSK_PROTOCOL_TLSV11
   • GSK_PROTOCOL_TLSV10
   • GSK_PROTOCOL_TLSV1
   • GSK_PROTOCOL_SSLV3
   • GSK_PROTOCOL_SSLV2
   • GSK_OCSP_ENABLE
   • GSK_SSL_EXTN_CERTSTATUSREQ_ENABLE
   • GSK_TLS_FEATURES_EXTN_ENABLE
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT
   • GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER
   
   
4. There are two ways to enable OCSP that can be used either separately or together:
   
   
   • GSK_OCSP_URL is set with gsk_attribute_set_buffer() to the URL of the OCSP responder. OCSP will be used for revocation status checking regardless of whether the certificate has an AIA extension or not, so it will work with existing certificates.
   • GSK_OCSP_ENABLE is set with gsk_attribute_set_enum() to GSK_TRUE. OCSP will be used if the certificate being validated has an AIA extension with a PKIK_AD_OCSP access method containing a URI of the HTTP location of the OCSP responder.
   
   When both attributes are set the GSK_OCSP_ENABLE functionality will only be used if GSK_OCSP_URL functionality results in an undetermined revocation status. The definition of undetermined revocation status is located in the Secure Sockets Layer topic.
   
   Note: Using OCSP results in a performance impact to System TLS.
   
   
   
5. To enable OCSP stapling, GSK_SSL_EXTN_CERTSTATUSREQ_ENABLE must be set with either GSK_OCSP_URL or GSK_OCSP_ENABLE also enabled. OCSP stapling must be enabled on the client in order for GSK_TLS_FEATURES_EXTN_ENABLE to have any meaning.
   
   
6. GSK_SSL_EXTN_SIGALG_SELECT_ALL sets the following list of default signature algorithms:
   • GSK_TLS_SIGALG_ECDSA_WITH_SHA512
   • GSK_TLS_SIGALG_ECDSA_WITH_SHA384
   • GSK_TLS_SIGALG_ECDSA_WITH_SHA256
   • GSK_TLS_SIGALG_ECDSA_WITH_SHA224
   • GSK_TLS_SIGALG_ECDSA_WITH_SHA1
   • GSK_TLS_SIGALG_RSA_WITH_SHA512
   • GSK_TLS_SIGALG_RSA_WITH_SHA384
   • GSK_TLS_SIGALG_RSA_WITH_SHA256
   • GSK_TLS_SIGALG_RSA_WITH_SHA224
   • GSK_TLS_SIGALG_RSA_WITH_SHA1
   
   
7. GSK_SSL_FIPS_MODE_PROCESSING enables all of the necessary GSKit settings to operate in FIPS-compliant mode. This setting tracks relevant standards and may change if the relevant standards change. Enabling GSK_SSL_FIPS_MODE_PROCESSING is equivalent to the following settings being made by the application:
   • GSK_PROTOCOL_SSLV2 = GSK_PROTOCOL_SSLV2_OFF
   • GSK_PROTOCOL_SSLV3 = GSK_PROTOCOL_SSLV3_OFF
   • GSK_TLSV10_CIPHER_SPECS_EX =

             "TLS_RSA_WITH_AES_128_CBC_SHA,
              TLS_RSA_WITH_AES_256_CBC_SHA,
              TLS_RSA_WITH_3DES_EDE_CBC_SHA"
             

   • GSK_TLSV11_CIPHER_SPECS_EX =

             "TLS_RSA_WITH_AES_128_CBC_SHA,
              TLS_RSA_WITH_AES_256_CBC_SHA,
              TLS_RSA_WITH_3DES_EDE_CBC_SHA"
             

   • GSK_TLSV12_CIPHER_SPECS_EX =

             "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
              TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
              TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
              TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
              TLS_RSA_WITH_AES_128_GCM_SHA256,
              TLS_RSA_WITH_AES_256_GCM_SHA384,
              TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
              TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,
              TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
              TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,
              TLS_RSA_WITH_AES_128_CBC_SHA256,
              TLS_RSA_WITH_AES_128_CBC_SHA,
              TLS_RSA_WITH_AES_256_CBC_SHA256,
              TLS_RSA_WITH_AES_256_CBC_SHA,
              TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,
              TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
              TLS_RSA_WITH_3DES_EDE_CBC_SHA"
             

   
   
8. GSK_NIST_SP800_131A_MODE enables all of the necessary GSKit settings to operate in SP800-131a mode. This setting tracks relevant standards and may change if the relevant standards change. Enabling GSK_NIST_SP800_131A_MODE is equivalent to the following settings being made by the application:
   • GSK_PROTOCOL_TLSV12 = GSK_TRUE
   • GSK_SSL_FIPS_MODE_PROCESSING = GSK_SSL_FIPS_MODE_PROCESSING_ON
   • GSK_SSL_EXTN_SIGALG =

             "GSK_TLS_SIGALG_ECDSA_WITH_SHA512,
              GSK_TLS_SIGALG_ECDSA_WITH_SHA384,
              GSK_TLS_SIGALG_ECDSA_WITH_SHA256,
              GSK_TLS_SIGALG_ECDSA_WITH_SHA224,
              GSK_TLS_SIGALG_RSA_WITH_SHA512,
              GSK_TLS_SIGALG_RSA_WITH_SHA384,
              GSK_TLS_SIGALG_RSA_WITH_SHA256,
              GSK_TLS_SIGALG_RSA_WITH_SHA224"
             

   • GSK_STRICT_SIGALG = GSK_TRUE
   • GSK_MIN_RSA_KEY_SIZE = 2048
   
   Warning: Any of the following settings made after GSK_NIST_SP800_131A_MODE is enabled will cause GSKit to operate in a mode that is not compliant with the SP800-131A specifications:
   • GSK_PROTOCOL_TLSV12 = GSK_FALSE
   • GSK_SSL_FIPS_MODE_PROCESSING = GSK_SSL_FIPS_MODE_PROCESSING_OFF
   • GSK_SSL_EXTN_SIGALG = NULL
   • GSK_STRICT_SIGALG = GSK_FALSE
   • GSK_MIN_RSA_KEY_SIZE < 2048
   
   
9. GSK_VACCINATE enables all of the recommended GSKit settings and tracks security vulnerability issues, allowing the application to remain secure. If more secure settings are identified, this macro will be updated to include them. Enabling GSK_VACCINATE is equivalent to the following settings being made by the application:
   • GSK_SSLV2HELLO_ENABLE = GSK_FALSE
   • GSK_PROTOCOL_SSLV2 = GSK_PROTOCOL_SSLV2_OFF
   • GSK_PROTOCOL_SSLV3 = GSK_PROTOCOL_SSLV3_OFF
   • GSK_PROTOCOL_TLSV12 = GSK_TRUE
   • GSK_PROTOCOL_TLSV13 = GSK_TRUE
   • GSK_SSL_FIPS_MODE_PROCESSING = GSK_SSL_FIPS_MODE_PROCESSING_ON
   • GSK_SSL_EXTN_SIGALG =

              "GSK_TLS_SIGALG_ECDSA_WITH_SHA512,
               GSK_TLS_SIGALG_ECDSA_WITH_SHA384,
               GSK_TLS_SIGALG_ECDSA_WITH_SHA256,
               GSK_TLS_SIGALG_RSA_WITH_SHA512,
               GSK_TLS_SIGALG_RSA_WITH_SHA384,
               GSK_TLS_SIGALG_RSA_WITH_SHA256
              

   • GSK_STRICT_SIGALG = GSK_TRUE
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_SERVER_ENABLE = GSK_TRUE
   • GSK_SSL_EXTN_ENCRYPTTHENMAC_CLIENT_ENABLE = GSK_TRUE
   • GSK_SSL_EXTN_PADDING_ENABLE = GSK_TRUE
   • GSK_RENEGOTIATION_PEER_IDENTITY_CHECK = GSK_TRUE
   • GSK_ENFORCE_TDEA_RESTRICTION = GSK_TRUE
   • GSK_TDEA_KEYCHECK = GSK_TRUE
   • GSK_STRICT_EE_KEYUSAGE_CHECK = GSK_TRUE
   • GSK_CRYPTOTEST_ENABLE = GSK_TRUE
   • GSK_PKIX_CERT_VALIDATION_MODE = GSK_PKIX_CERT_VALIDATION_MODE_ON
   • GSK_MIN_RSA_KEY_SIZE = 1024
   
   
   

Related Information

• gsk_attribute_get_enum()--Get enumerated information about a secure session or environment.
  
  
• gsk_attribute_set_buffer()--Set character string information for a secure session or environment.
  
  
• gsk_attribute_set_numeric_value()--Set numeric information for a secure session or environment
  
  
• gsk_environment_init()--Initialize a secure environment
  
  
• gsk_environment_open()--Get a handle for a secure environment
  
  
• 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