gsk_attribute_get_numeric_value()--Get numeric information about a secure session or environment

 #include <gskssl.h>

 int gsk_attribute_get_numeric_value(gsk_handle my_gsk_handle,
                                     GSK_NUM_ID numID,
                                     int *numValue);

The gsk_attribute_get_numeric_value() function is used to obtain specific numeric information about a 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)

numID  (Input) 

The following values can be used to retrieve information about the secure session or environment that is either defaulted or explicitly set:

• GSK_FD (300) - numValue is a socket descriptor to be used for this secure session.
  
  
• GSK_V2_SESSION_TIMEOUT (301) - SSL Version 2 session time-out for the environment. numValue must be in the range 0-100 seconds.
  
  
• GSK_V3_SESSION_TIMEOUT (302) - SSL Version 3 and TLS version 1.x session time-out for the environment. numValue must be in the range 0-86400 seconds.
  
  
• GSK_IBMI_READ_TIMEOUT (6993) - The receive time-out for the secure session or environment.
  
  
• GSK_CERTIFICATE_VALIDATION_CODE (6996) - The certificate validation return code for the local or peer certificate.
  
  
• GSK_HANDSHAKE_TIMEOUT (6998) - TLS handshake time-out for the secure session or environment.
  
  
• GSK_OCSP_MAX_RESPONSE_SIZE (315) - numValue is the maximum response size in bytes that will be accepted from the Online Certificate Status Protocol (OCSP) responder. When the response size is greater, the response is rejected.
  
  
• GSK_OCSP_TIMEOUT (318) - numValue is the receive timeout in seconds to wait for a response from the OCSP responder. This value should be less than or equal to the value for GSK_HANDSHAKE_TIMEOUT as that setting applies to the entire handshake wait time. (Note: GSK_HANDSHAKE_TIMEOUT default is to wait forever)
  
  
• GSK_OCSP_NONCE_SIZE (324) - numValue is the size in bytes that will be generated as an OCSP nonce if nonce is to be generated. Setting this value greater than 512 will result in the value being set to 512.
  
  
• GSK_OCSP_CLIENT_CACHE_SIZE (326) - numValue indicates if OCSP response caching is enabled for the secure environment. The default value is 1, indicating this secure environment will both create cache entries and use cache entries in the System TLS system level OCSP response cache. A value of 0 disables both cache creates and cache lookups for the secure environment. The System TLS system level cache size is unlimited.
  
  
• GSK_OCSP_PROXY_SERVER_PORT (312) - numValue is the port of the proxy server to which OCSP requests will be sent if GSK_OCSP_PROXY_SERVER_NAME is set.
  
  
• GSK_LAST_VALIDATION_ERROR (311) - Additional information about the last certificate validation error on the current secure session. If gsk_secure_soc_init() or gsk_secure_soc_startInit() returned an error, this attribute may provide additional error information. While not an exhaustive list, most possible error code values are listed in "gskssl.h".
  
  
• GSK_SSL_EXTN_MAXFRAGMENT_SIZE (321) - numValue is the client secure session's preferred TLS fragment size. The fragment size is negotiated with the server using an optional TLS extension. System TLS will send the maximum fragmentation length extension in the extended client hello when not set to the default value of 16384. If the server agrees to the smaller fragment size both sides of the secure session will immediately start fragmenting the data to that size. The typical System TLS application should not change this setting. Note: This attribute is not applicable to System TLS server sessions as they always support all valid sizes for this extension. Valid values are 512, 1024, 2048, 4096, and 16384.
  
  
• GSK_TLS_CBCPROTECTION_METHOD (329) - Sets an optional SSL Version 3 or TLS Version 1.0 CBC IV Protection method. numValue must specify one of the following:
  
  • GSK_TLS_CBCPROTECTION_METHOD_NONE (0) - No method is employed.
  • GSK_TLS_CBCPROTECTION_METHOD_ZEROBYTEFRAGMENT(1) - A zero byte fragment is prepended to each data record sent.
  • GSK_TLS_CBCPROTECTION_METHOD_ONEBYTEFRAGMENT(2) - The data record is sent in multiple records with the first record containing one byte.
  • GSK_TLS_CBCPROTECTION_METHOD_DELAYEDONEBYTEFRAGMENT(3) - The first write operation is unaffected. After the first write operation, the data record is sent in multiple records with the first record containing one byte.
  
  
• GSK_MIN_RSA_KEY_SIZE (335)- numValue is the minimum RSA key size allowed for a RSA certificate being received or sent. The default value for System TLS is determined using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
  
  
  
• GSK_HTTP_CONNECT_TIMEOUT (336) - numValue is the timeout in seconds to wait for an OCSP connect.
  
  
• GSK_SSL_EXTN_SESSIONTICKET_KEY_LIFETIME (337)- numValue is the session ticket key lifetime on a server. An environment has a key used to encrypt/decrypt session tickets generated by the environment. The key lifetime determines how often the key is refreshed with a new value. 0 means to not refresh the key however System TLS refreshes after approximately six months. A session ticket encrypted by an expired key is not used for session resumption when received from a client.
  
  
• GSK_SSL_EXTN_SESSIONTICKET_MAX_SIZE (341)- numValue is the maximum session ticket size in bytes supported by the client application. Session tickets received from a server that are larger than the maximum size are discarded. This attribute has no meaning for server applications.
  
  
• GSK_SSL_EXTN_SESSIONTICKET_NUMBER (352)- numValue is the number of secure session tickets requested or sent.
  

numValue  (Output) 

A pointer to an integer containing the value of the requested information.

Authorities

No authorization is required.

Return Value

gsk_attribute_get_numeric_value() returns an integer. Possible values are:

[GSK_OK]

gsk_attribute_get_numeric_value() was successful.

[GSK_ATTRIBUTE_INVALID_ID]

The specified numID was not valid.

[GSK_INVALID_HANDLE]

The handle specified was not valid.

[GSK_IBMI_ERROR_INVALID_POINTER]

The numValue pointer is not valid.

[GSK_ERROR_UNSUPPORTED]

The numID is currently not supported.

[GSK_ERROR_IO]

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

Error Conditions

When the gsk_attribute_get_numeric_value() 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_NUM_ID values may be retrieved from the secure environment after gsk_environment_open():
   • GSK_V2_SESSION_TIMEOUT
   • GSK_V3_SESSION_TIMEOUT
   • GSK_HANDSHAKE_TIMEOUT
   • GSK_IBMI_READ_TIMEOUT
   • GSK_OCSP_PROXY_SERVER_PORT
   • GSK_OCSP_MAX_RESPONSE_SIZE
   • GSK_OCSP_TIMEOUT
   • GSK_OCSP_NONCE_SIZE
   • GSK_OCSP_CLIENT_CACHE_SIZE
   • GSK_SSL_EXTN_MAXFRAGMENT_SIZE
   • GSK_TLS_CBCPROTECTION_METHOD
     
   • GSK_MIN_RSA_KEY_SIZE
   • GSK_HTTP_CONNECT_TIMEOUT
   • GSK_SSL_EXTN_SESSIONTICKET_NUMBER
   • GSK_SSL_EXTN_SESSIONTICKET_MAX_SIZE
   • GSK_SSL_EXTN_SESSIONTICKET_KEY_LIFETIME
     
   
   
2. The following GSK_NUM_ID value may be retrieved from the secure environment after gsk_environment_init()
   • GSK_CERTIFICATE_VALIDATION_CODE - Will return the certificate validation return code for the local certificate.
   
   
3. The following GSK_NUM_ID value may be retrieved from each individual secure session after gsk_secure_soc_init().
   • GSK_CERTIFICATE_VALIDATION_CODE - Will return the certificate validation return code for the peer's certificate.
   • GSK_LAST_VALIDATION_ERROR
     
   
   
4. The following GSK_NUM_ID values may be retrieved from each individual secure session after gsk_secure_soc_open().
   • GSK_FD
   • GSK_HANDSHAKE_TIMEOUT
   • GSK_IBMI_READ_TIMEOUT
   
   
5. The following information should be considered when using GSK_TLS_CBCPROTECTION_METHOD:
   
   
   • These methods only apply to SSL Version 3 and TLS Version 1.0 when using CBC cipher suites.
   • Setting GSK_TLS_CBCPROTECTION_METHOD_ONEBYTEFRAGMENT may generally interfere with application protocols that expect complete records.
   • It is recommended that TLS Version 1.1 or higher is used instead of the above mitigation methods.
   • Stream ciphers are not subject to attack and may be used as a mitigation method.
   
   
   

Related Information

• gsk_attribute_get_buffer()--Get character information about a secure session or environment
  
  
• gsk_attribute_get_enum()--Get enumerated information about a secure session or environment.
  
  
• gsk_attribute_get_cert_info()--Get information about a local or partner certificate
  
  
• 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