gsk_attribute_set_numeric_value()--Set numeric information for a secure session or environment
Syntax
#include <gskssl.h> int gsk_attribute_set_numeric_value(gsk_handle my_gsk_handle, GSK_NUM_ID numID, int numValue);Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The gsk_attribute_set_numeric_value() function is used to set specific numeric information for a secure session or environment.
Parameters
- my_gsk_handle (Input)
- 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)
- One of the following operations:
- GSK_FD (300) - numValue is a socket descriptor to
be used for this secure session.
- GSK_V2_SESSION_TIMEOUT (301) - numValue is the
SSL Version 2 session time-out for the TLS environment. numValue must
be in the range 0-100 seconds.
- GSK_V3_SESSION_TIMEOUT (302) - numValue is the
SSL Version 3 and TLS Version 1.x session time-out for the secure environment.
numValue must be in the range 0-86400 seconds (24 hours).
- GSK_IBMI_READ_TIMEOUT (6993) - numValue is the
receive time-out for the secure session or environment.
numValue must be in milliseconds. A numValue of 0 is the
default which means to wait forever.
- GSK_HANDSHAKE_TIMEOUT (6998) - numValue is the
TLS handshake time-out for the secure session or environment.
numValue must be in seconds. A numValue of 0 is the default
which means to wait forever.
-
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. Default is 20480.
- 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. Default is 10.
(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. The default is 0 which is a special value meaning use the System
TLS default size of 8. 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. A value of 0 indicates the default proxy
server port (80) will be used.
- 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, and 4096.
- GSK_TLS_CBCPROTECTION_METHOD (329) -
Sets an optional SSL Version 3 or TLS Version 1.0 CBC IV Protection method. The default value is GSK_TLS_CBCPROTECTION_METHOD_NONE (0). 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.
A numValue of 0 is the default. A numValue greater than 0 will prevent any RSA certificates
with a smaller RSA key size than the minimum key size set from being used during the handshake. A system level
minimum key size for System TLS can be set using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
The SSLCONFIG value is used for this attribute internally if it is larger than numValue.
-
GSK_HTTP_CONNECT_TIMEOUT (336) -
numValue is the timeout in seconds to wait for an OCSP connect.
Default is 0 (off).
- 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.
numValue must be in the range 0-86400 seconds (24 hours). Default is 86400.
- 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.
numValue must be in the range 1024-16384 bytes. Default is 8192 bytes.
- GSK_SSL_EXTN_SESSIONTICKET_NUMBER (352)-
numValue is the number of secure session tickets requested or sent.
numValue must be in the range 0-16 session tickets. Default is 1.
- GSK_FD (300) - numValue is a socket descriptor to
be used for this secure session.
- numValue (Input)
- An integer value to be updated for the specified numID.
Authorities
No authorization is required.
Return Value
gsk_attribute_set_numeric_value() returns an integer. Possible values are:
- [GSK_OK]
gsk_attribute_set_numeric_value() was successful.
- [GSK_INVALID_STATE]
One of the following occurred:
- numID cannot be set in the secure environment after a gsk_environment_init() has been issued.
- numID cannot be set for a secure session after a gsk_secure_soc_init() has been issued.
- [GSK_ATTRIBUTE_INVALID_ID]
The numID specified was not valid.
- [GSK_ATTRIBUTE_INVALID_NUMERIC_VALUE]
The numValue specified was not valid.
- [GSK_INVALID_HANDLE]
A handle was specified that was 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_set_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
- The following GSK_NUM_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_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
- The following GSK_NUM_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_FD
- GSK_HANDSHAKE_TIMEOUT
- GSK_IBMI_READ_TIMEOUT
- The GSK_FD value is a socket descriptor that must have an
address family of AF_INET or AF_INET6 and a socket type of
SOCK_STREAM.
- 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_numeric_value()--Get
numeric information about a secure session or environment
- gsk_attribute_set_buffer()--Set
character string information for a secure session or environment.
- gsk_attribute_set_enum()--Set
enumerated 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
API introduced: V5R1
Top | UNIX-Type APIs | APIs by category |