gsk_attribute_set_buffer()--Set character information for a secure session or environment
Syntax
#include <gskssl.h> int gsk_attribute_set_buffer(gsk_handle my_gsk_handle, GSK_BUF_ID bufID, const char *buffer, int bufSize);Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The gsk_attribute_set_buffer() function is used to set a specified buffer attribute to a value inside the specified 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)
- bufID (Input)
- Indicates one of the following operations:
- GSK_KEYRING_FILE (201) - buffer points to the
name of the certificate store file to be used for the secure session or
environment. Authority to the certificate store file will be checked on the
gsk_environment_init() API or the
gsk_secure_soc_init() API.
- GSK_KEYRING_PW (202) - buffer points to the
password for the certificate store file to be used for the secure session or
environment.
- GSK_KEYRING_LABEL (203) - buffer points to the
certificate label associated with the certificate in the certificate store to
be used for the secure session or environment.
-
GSK_KEYRING_LABEL_EX (254) - buffer points to a list of
up to four comma delimited string values of the certificate labels associated with the
certificates in the certificate store to be used for the secure session or
environment.
- GSK_IBMI_APPLICATION_ID (6999) - buffer points
to the application identifier to be used for the secure environment.
-
GSK_TLSV13_CIPHER_SPECS_EX (2008) - buffer points to a
list of comma delimited string values of the TLS Version 1.3 ciphers to be used
for the secure session or environment.
-
GSK_TLSV12_CIPHER_SPECS_EX (243) - buffer points to a
list of comma delimited string values of the TLS Version 1.2 ciphers to be used
for the secure session or environment.
GSK_TLSV12_CIPHER_SPECS (238) (Deprecated) - buffer points to a list of two-character string codes of the TLS Version 1.2 ciphers to be used for the secure session or environment. Setting this to NULL will result in the System TLS default list of ciphers being used as indicated in the usage notes.
Replaced by GSK_TLSV12_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters. The ciphers that can not be represented will be used for this session/environment where appropriate based on other settings however those ciphers will not appear for this attribute.
See the usage notes for the format of the ciphers for either of the attributes.
- GSK_TLSV11_CIPHER_SPECS_EX (242) - buffer points to
a list of comma delimited string values of the TLS Version 1.1 ciphers to be
used for the secure session or environment.
GSK_TLSV11_CIPHER_SPECS (237) (Deprecated) - buffer points to a list of two-character string codes of the TLS Version 1.1 ciphers to be used for the secure session or environment. Setting this to NULL will result in the System TLS default list of ciphers being used as indicated in the usage notes.
Replaced by GSK_TLSV11_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters. The ciphers that can not be represented will be used for this session/environment where appropriate based on other settings however those ciphers will not appear for this attribute.
See the usage notes for the format of the ciphers for either of the attributes.
- GSK_TLSV10_CIPHER_SPECS_EX (241) - buffer points to
a list of comma delimited string values of the TLS Version 1.0 ciphers to be
used for the secure session or environment.
GSK_TLSV10_CIPHER_SPECS (236) (Deprecated) - buffer points to a list of two-character string codes of the TLS Version 1.0 ciphers to be used for the secure session or environment. Setting this to NULL will result in the System TLS default list of ciphers being used as indicated in the usage notes.
Replaced by GSK_TLSV10_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters. The ciphers that can not be represented will be used for this session/environment where appropriate based on other settings however those ciphers will not appear for this attribute.
See the usage notes for the format of the ciphers for either of the attributes.
- GSK_V3_CIPHER_SPECS_EX (240) - buffer points to a
list of comma delimited string values of the SSL Version 3 ciphers to be used
for the secure session or environment.
GSK_V3_CIPHER_SPECS (206) (Deprecated) - buffer points to a list of two-character string codes of the SSL Version 3 ciphers to be used for the secure session or environment. For compatibility with previous releases, if this value is set, its value will be duplicated into the GSK_TLSV10_CIPHER_SPECS and GSK_TLSV10_CIPHER_SPECS_EX values if the default value has not been changed by an explicit set call for either of those attributes.
Replaced by GSK_V3_CIPHER_SPECS_EX as some new ciphers can be not represented by two characters.
See the usage notes for the format of the ciphers for either of the attributes.
- GSK_V2_CIPHER_SPECS (205) - buffer points to the
list of SSL Version 2 ciphers to be used for the secure session or
environment.
-
GSK_SSL_EXTN_SIGALG (245) - buffer points to the list
of comma delimited string values of signature algorithms to be supported by the
secure environment when using TLS version 1.2. See the usage notes for the format
of the signature algorithms.
- GSK_OCSP_URL (221) - buffer points to the URL of
the Online Certificate Status Protocol (OCSP) responder to query during
certificate validation. HTTP is the only supported protocol; therefore, the
URL must begin with "http://". This attribute has precedence over
GSK_OSCP_ENABLE. See the usage notes for additional information on the
interaction of OCSP attributes.
- GSK_OCSP_PROXY_SERVER_NAME (223) - buffer points
to the name of the proxy server to which OCSP requests should be sent. For
example, myocspproxy.com. If set, all OCSP requests will be sent to the
proxy HTTP server for processing.
- GSK_SSL_EXTN_SERVERNAME_REQUEST (230) - buffer
points to a string that represents the Fully Qualified
Domain Name (FQDN) of the server the client intends to communicate with. The
value is used in the TLS Server Name Indication (SNI) extension request as
defined by RFC 6066.
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUEST (231) -
buffer points to a string that represents the
FQDN of the server the client intends to communicate with. The value is
used in the TLS SNI extension request as defined by RFC 6066.
This attribute should be used instead of GSK_SSL_EXTN_SERVERNAME_REQUEST if the server must respond affirmatively to the FQDN in the SNI request. The secure connection will fail when the server does not provide that affirmation.
NOTE - The use of this attribute will result in interoperability issues with servers that do not support the SNI extension.
- GSK_SSL_EXTN_SERVERNAME_LIST (232) - buffer
points to both a null-terminated FQDN and certificate label to be set for
the server. The FQDN and certificate label strings are separated by a NULL
character (i.e., "www.gskit.org\0my_label\0"). The label must be
from the certificate store file specified for the secure environment. This
would be *SYSTEM if GSK_IBMI_APPLICATION_ID is set. The
server will use the certificate and private key for any secure connections
with a matching client SNI FQDN request. If the client SNI request is not
matched, the server session will use the configured default certificate with
no SNI acknowledgment. This attribute can be set multiple times to create
an array of FQDN and certificate label pairs.
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST (233) -
buffer points to both a null-terminated FQDN and certificate label
to be set for the server. Use this attribute instead of
GSK_SSL_EXTN_SERVERNAME_LIST if the client SNI request must
match an entry in this list and result in an error if it is not matched.
This critical condition only applies when a client sends the SNI extension
and does not apply when the client does not send the extension. This
attribute can be set multiple times to create an array of FQDN and
certificate label pairs.
-
GSK_SSL_EXTN_ALPN (276) - buffer points to a list of
comma delimited string values of the Application-Layer Protocol Negotiation (ALPN)
protocols IDs to be used for the secure session or environment.
-
GSK_TLS_EXTN_SIG_SCHEME (2001) - buffer points to the list
of comma delimited string values of signature scheme algorithms to be supported by the
secure environment when using TLS version 1.3. See the usage notes for the format
of the signature algorithms.
-
GSK_TLS_EXTN_SIG_SCHEME_CERT (2003) - buffer points to the list
of comma delimited string values of signature scheme certificate algorithms to be supported by the
secure environment when using TLS version 1.3. See the usage notes for the format
of the signature algorithms.
-
GSK_TLS_EXTN_SUPPORTED_GROUPS (2005) - buffer points to the list
of comma delimited string values of groups to be supported by the
secure environment when using TLS version 1.2 and newer versions.
See the usage notes for the format of the supported groups.
- GSK_KEYRING_FILE (201) - buffer points to the
name of the certificate store file to be used for the secure session or
environment. Authority to the certificate store file will be checked on the
gsk_environment_init() API or the
gsk_secure_soc_init() API.
- buffer (Input)
- A pointer to the information to be used for the secure session or the TLS
environment.
The data in the buffer is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this buffer is assumed to be represented in the default CCSID of the job.
- bufSize (Input)
- The length of the buffer information. If bufSize is specified as 0, the length of bufSize will be calculated.
Authorities
No authorization is required.
Return Value
gsk_attribute_set_buffer() returns an integer. Possible values are:
- [GSK_OK]
- gsk_attribute_set_buffer() was successful.
- [GSK_ATTRIBUTE_INVALID_ID]
- The bufID value is not a valid identifier.
- [GSK_ATTRIBUTE_INVALID_LENGTH]
- The bufSize specified or the length of buffer is not
valid.
- [GSK_INVALID_HANDLE]
- my_gsk_handle is not a valid handle that was received from issuing
gsk_environment_open() or
gsk_secure_soc_open().
- [GSK_IBMI_ERROR_INVALID_POINTER]
- The buffer pointer is not valid.
- [GSK_INVALID_STATE]
- One of the following occurred:
- bufID cannot be set for a TLS environment after a gsk_environment_init() has been issued.
- bufID cannot be set for a secure session after a gsk_secure_soc_init() has been issued.
- [GSK_INVALID_PARAMETER]
- The buffer value contains an invalid value for the bufID
being set. For example an invalid cipher suite was specified.
- [GSK_ERROR_BAD_V3_CIPHER]
- An SSLV3 cipher suite was specified that is not valid.
- [GSK_ERROR_BAD_V2_CIPHER]
- An SSLV2 cipher suite was specified that is not valid.
- [GSK_ERROR_UNSUPPORTED]
- The bufID value is currently not supported.
- [GSK_INSUFFICIENT_STORAGE]
- Not able to allocate storage for the requested operation.
- [GSK_ERROR_IO]
- An error occurred in TLS processing, check the errno value.
Error Conditions
When the gsk_attribute_set_buffer() 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_BUF_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_KEYRING_FILE
- GSK_KEYRING_PW
- GSK_KEYRING_LABEL
- GSK_KEYRING_LABEL_EX
- GSK_IBMI_APPLICATION_ID
- GSK_TLSV13_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS
- GSK_TLSV11_CIPHER_SPECS_EX
- GSK_TLSV11_CIPHER_SPECS
- GSK_TLSV10_CIPHER_SPECS_EX
- GSK_TLSV10_CIPHER_SPECS
- GSK_V3_CIPHER_SPECS_EX
- GSK_V3_CIPHER_SPECS
- GSK_V2_CIPHER_SPECS
- GSK_SSL_EXTN_SIGALG
- GSK_OCSP_URL
- GSK_OCSP_PROXY_SERVER_NAME
- GSK_SSL_EXTN_SERVERNAME_REQUEST
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUEST
- GSK_SSL_EXTN_SERVERNAME_LIST
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST
- GSK_SSL_EXTN_ALPN
- GSK_TLS_EXTN_SIG_SCHEME
- GSK_TLS_EXTN_SIG_SCHEME_CERT
- GSK_TLS_EXTN_SUPPORTED_GROUPS
- The following GSK_BUF_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_KEYRING_LABEL
- GSK_KEYRING_LABEL_EX
- GSK_TLSV13_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS
- GSK_TLSV11_CIPHER_SPECS_EX
- GSK_TLSV11_CIPHER_SPECS
- GSK_TLSV10_CIPHER_SPECS_EX
- GSK_TLSV10_CIPHER_SPECS
- GSK_V3_CIPHER_SPECS_EX
- GSK_V3_CIPHER_SPECS
- GSK_V2_CIPHER_SPECS
- GSK_SSL_EXTN_ALPN
-
This table shows the
mapping between the three different representations of a cipher
specification on the system. For each protocol version the cipher
specifications that are supported are
indicated by the "X" in the appropriate column.
GSK_XX_CIPHER_SPECS RepresentationGSK_XX_CIPHER_SPECS_EX RepresentationQSSLCSL System Value RepresentationTLSV13 TLSV12 TLSV11 TLSV10 SSLV3 Not Applicable TLS_AES_128_GCM_SHA256 *AES_128_GCM_SHA256 X Not Applicable TLS_AES_256_GCM_SHA384 *AES_256_GCM_SHA384 X Not Applicable TLS_CHACHA20_POLY1305_SHA256 *CHACHA20_POLY1305_SHA256 X 9C TLS_RSA_WITH_AES_128_GCM_SHA256 *RSA_AES_128_GCM_SHA256 X 9D TLS_RSA_WITH_AES_256_GCM_SHA384 *RSA_AES_256_GCM_SHA384 X Not Applicable TLS_ECDHE_ECDSA_WITH_NULL_SHA *ECDHE_ECDSA_NULL_SHA X Not Applicable TLS_ECDHE_ECDSA_WITH_RC4_128_SHA *ECDHE_ECDSA_RC4_128_SHA X Not Applicable TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA *ECDHE_ECDSA_3DES_EDE_CBC_SHA X Not Applicable TLS_ECDHE_RSA_WITH_NULL_SHA *ECDHE_RSA_NULL_SHA X Not Applicable TLS_ECDHE_RSA_WITH_RC4_128_SHA *ECDHE_RSA_RC4_128_SHA X Not Applicable TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA *ECDHE_RSA_3DES_EDE_CBC_SHA X Not Applicable TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 *ECDHE_ECDSA_AES_128_CBC_SHA256 X Not Applicable TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 *ECDHE_ECDSA_AES_256_CBC_SHA384 X Not Applicable TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 *ECDHE_RSA_AES_128_CBC_SHA256 X Not Applicable TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 *ECDHE_RSA_AES_256_CBC_SHA384 X Not Applicable TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 *ECDHE_ECDSA_AES_128_GCM_SHA256 X Not Applicable TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 *ECDHE_ECDSA_AES_256_GCM_SHA384 X Not Applicable TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 *ECDHE_RSA_AES_128_GCM_SHA256 X Not Applicable TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 *ECDHE_RSA_AES_256_GCM_SHA384 X Not Applicable TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 *ECDHE_ECDSA_CHACHA20_POLY1305_SHA256 X Not Applicable TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 *ECDHE_RSA_CHACHA20_POLY1305_SHA256 X 3D TLS_RSA_WITH_AES_256_CBC_SHA256 *RSA_AES_256_CBC_SHA256 X 3C TLS_RSA_WITH_AES_128_CBC_SHA256 *RSA_AES_128_CBC_SHA256 X 35 TLS_RSA_WITH_AES_256_CBC_SHA *RSA_AES_256_CBC_SHA X X X 2F TLS_RSA_WITH_AES_128_CBC_SHA *RSA_AES_128_CBC_SHA X X X 0A TLS_RSA_WITH_3DES_EDE_CBC_SHA *RSA_3DES_EDE_CBC_SHA X X X X 05 TLS_RSA_WITH_RC4_128_SHA *RSA_RC4_128_SHA X X X X 04 TLS_RSA_WITH_RC4_128_MD5 *RSA_RC4_128_MD5 X X X X 09 TLS_RSA_WITH_DES_CBC_SHA *RSA_DES_CBC_SHA X X X 03 TLS_RSA_EXPORT_WITH_RC4_40_MD5 *RSA_EXPORT_RC4_40_MD5 X X 06 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 *RSA_EXPORT_RC2_CBC_40_MD5 X X 3B TLS_RSA_WITH_NULL_SHA256 *RSA_NULL_SHA256 X 02 TLS_RSA_WITH_NULL_SHA *RSA_NULL_SHA X X X X 01 TLS_RSA_WITH_NULL_MD5 *RSA_NULL_MD5 X X X X
-
The following GSK_TLSV13_CIPHER_SPECS_EX string is the default TLS
Version 1.3 cipher list used when the operating system is installed:
"TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256"
- The following GSK_TLSV12_CIPHER_SPECS_EX string is the default TLS
Version 1.2 cipher list used when the operating system is installed:
'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_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, 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'
The GSK_TLSV12_CIPHER_SPECS equivalent list is '9C9D3C2F3D35'.
Note: The GSK_TLSV12_CIPHER_SPECS list may not reflect all of the ciphers in use by the environment or session if ciphers that do not have a GSK_TLSV12_CIPHER_SPECS equivalent representation are enabled.
-
The following GSK_TLSV11_CIPHER_SPECS_EX string is the default TLS
Version 1.1 cipher list used when the operating system is installed:
'TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA'
The GSK_TLSV11_CIPHER_SPECS equivalent list is '2F35'.
-
The following GSK_TLSV10_CIPHER_SPECS_EX string is the default TLS
Version 1.0 cipher list used when the operating system is installed:
'TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA'
The GSK_TLSV10_CIPHER_SPECS equivalent list is '2F35'.
-
SSL Version 3 support is disabled when the operating system is installed. If SSL
Version 3 is enabled (not recommended), the following GSK_V3_CIPHER_SPECS_EX string is
the default SSL Version 3 cipher list used when the operating system is
installed:
''
The GSK_V3_CIPHER_SPECS equivalent list is ''.
-
SSL Version 2 support is disabled when the operating system is installed resulting
in no SSL Version 2 ciphers being supported. If SSL Version 2 is
enabled (not recommended), the following GSK_V2_CIPHER_SPECS values are the SSL
Version 2 ciphers that would be supported if the shipped supported cipher list
has not been altered.
1 = *RSA_RC4_128_MD5 2 = *RSA_EXPORT_RC4_40_MD5 4 = *RSA_EXPORT_RC2_CBC_40_MD5 NULL = Default cipher specs are used, however no SSLv2 ciphers are eligible to be default cipher specs. Thus, the default list contains no ciphers.
The following GSK_V2_CIPHER_SPECS values are the SSL Version 2 ciphers potentially supported if an administrator later enables SSL Version 2:1 = *RSA_RC4_128_MD5 2 = *RSA_EXPORT_RC4_40_MD5 3 = *RSA_RC2_CBC_128_MD5 4 = *RSA_EXPORT_RC2_CBC_40_MD5 6 = *RSA_DES_CBC_MD5 7 = *RSA_3DES_EDE_CBC_MD5 NULL = Default cipher specs are used, however no SSLv2 ciphers are eligible to be default cipher specs. Thus, the default list contains no ciphers.
-
The current default cipher suite list can be different from the install time
list due to changes made to the QSSLCSL (TLS cipher specification list) system
value via the Change System Value
(CHGSYSVAL) command. A cipher
suite removed from the TLS cipher specification list will also be removed
from the default cipher suite lists shown here. A cipher suite removed from the
eligible default cipher specification list using System Service Tools (SST)
Advanced Analysis Command SSLCONFIG will also be removed from the default cipher
suite list shown here. For additional information see the help text for
SSLCONFIG. The order of the cipher suites
in QSSLCSL will be used to order the cipher suites in the default list.
gsk_attribute_get_buffer() for
GSK_TLSV13_CIPHER_SPECS_EX,
GSK_TLSV12_CIPHER_SPECS_EX,
GSK_TLSV11_CIPHER_SPECS_EX,
GSK_TLSV10_CIPHER_SPECS_EX, and
GSK_V3_CIPHER_SPECS_EX can be used to determine the current
default cipher suite list configuration for the appropriate protocol version.
The default list might be empty based on system configuration resulting in
the null character (\0) being returned by
gsk_attribute_get_buffer().
-
The following GSK_SSL_EXTN_SIGALG strings represent the
signature algorithms supported:
- GSK_TLS_SIGALG_RSA_WITH_MD5 (not supported as shipped)
- GSK_TLS_SIGALG_RSA_WITH_SHA1
- GSK_TLS_SIGALG_RSA_WITH_SHA224
- GSK_TLS_SIGALG_RSA_WITH_SHA256
- GSK_TLS_SIGALG_RSA_WITH_SHA384
- GSK_TLS_SIGALG_RSA_WITH_SHA512
- GSK_TLS_SIGALG_ECDSA_WITH_SHA1
- GSK_TLS_SIGALG_ECDSA_WITH_SHA224
- GSK_TLS_SIGALG_ECDSA_WITH_SHA256
- GSK_TLS_SIGALG_ECDSA_WITH_SHA384
- GSK_TLS_SIGALG_ECDSA_WITH_SHA512
The supported signature algorithms that can be used by System TLS can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
The following GSK_SSL_EXTN_SIGALG string is the default ordered list supported when the operating system is installed:"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_SHA225, GSK_TLS_SIGALG_RSA_WITH_SHA1"
The default string used by System TLS can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
-
The list of supported cipher suites and the ordered list of default cipher suites
are configurable from the Change System Value (CHGSYSVAL) command.
The Display System Value (DSPSYSVAL) command or the Retrieve System Values
(QWCRSVAL) API can be used to determine the current settings of the
supported ciphers (QSSLCSL) and protocols (QSSLPCL) for system TLS.
- The following are the possible scenarios for the use of GSK_KEYRING_LABEL and
GSK_KEYRING_LABEL_EX:
- GSK_KEYRING_LABEL or GSK_KEYRING_LABEL_EX can be set after gsk_environment_open() and before gsk_environment_init() to indicate which certificate(s) in the GSK_KEYRING_FILE to use for the secure environment.
- GSK_KEYRING_LABEL or GSK_KEYRING_LABEL_EX can be set after gsk_secure_soc_open() and before gsk_secure_soc_init() to indicate which certificate(s) in the GSK_KEYRING_FILE to use for the secure session.
-
If both GSK_KEYRING_LABEL and GSK_KEYRING_LABEL_EX are set, the GSK_KEYRING_LABEL_EX
value will indicate which certificate(s) in the GSK_KEYRING_FILE to use for the
secure session or environment.
- If GSK_KEYRING_LABEL and GSK_KEYRING_LABEL_EX are not set, the default certificate label in the GSK_KEYRING_FILE is used for the secure environment.
- If GSK_IBMI_APPLICATION_ID is set, the GSK_KEYRING_FILE, the
GSK_KEYRING_LABEL, the GSK_KEYRING_LABEL_EX,
and the GSK_KEYRING_PASSWORD values are ignored.
- 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 buffer
attributes that can be overwritten by DCM during the call to gsk_environment_init():
- GSK_TLSV13_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS_EX
- GSK_TLSV11_CIPHER_SPECS_EX
- GSK_TLSV10_CIPHER_SPECS_EX
- GSK_TLSV12_CIPHER_SPECS
- GSK_TLSV11_CIPHER_SPECS
- GSK_TLSV10_CIPHER_SPECS
- GSK_SSL_EXTN_SIGALG
- GSK_OCSP_URL
- GSK_TLS_EXTN_SIG_SCHEME
- GSK_TLS_EXTN_SIG_SCHEME_CERT
- When
GSK_IBMI_APPLICATION_ID is set, the settings of some of the secure environment
attributes will be affected by the corresponding value in the Application ID
definition in Digital Certificate Manager (DCM). These are the buffer
attributes that can be appended by DCM to the end of the existing secure environment
buffer attributes during the call to
gsk_environment_init():
- GSK_SSL_EXTN_SERVERNAME_LIST
- GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST
-
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 Authority Information Access (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.
- Per RFC 6066 Transport Layer
Security (TLS) Extensions: Extension Definitions , the main purpose of
Server Name Indication (SNI) support is to allow TLS clients to provide to the
TLS server the name of the server they are contacting. This functionality is
desirable in order to facilitate secure connections to servers that host
multiple 'virtual' servers at a single underlying network address.
TLS servers that do not host multiple 'virtual' servers may find that configuring GSK_SSL_EXTN_SERVERNAME_LIST allows for improved interoperability with TLS clients that are using the equivalent of GSK_SSL_EXTN_SERVERNAME_CRITICAL_REQUEST on their platform. - The following is a possible scenario for the use of
GSK_TLSV12_CIPHER_SPECS_EX:
gsk_attribute_set_buffer(GSK_TLSV12_CIPHER_SPECS_EX) gsk_attribute_get_buffer(GSK_TLSV12_CIPHER_SPECS_EX) gsk_attribute_set_buffer(GSK_TLSV12_CIPHER_SPECS)
In the example above, the two calls to gsk_attribute_set_buffer() using GSK_TLSV12_CIPHER_SPECS_EX and GSK_TLSV12_CIPHER_SPECS will modify the same cipher list. The buffer returned to gsk_attribute_get_buffer() will no longer be accurate after the second set call. The cipher spec list was modified by the second set, so another get call would be necessary to retrieve the current cipher list. This also applies to GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, and GSK_V3_CIPHER_SPECS_EX.
-
The following GSK_TLS_EXTN_SIG_SCHEME strings represent the
signature scheme algorithms supported:
- GSK_TLS_SIG_SCHEME_ECDSA_SECP256R1_SHA256
- GSK_TLS_SIG_SCHEME_ECDSA_SECP384R1_SHA384
- GSK_TLS_SIG_SCHEME_ECDSA_SECP521R1_SHA512
- GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA256
- GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA384
- GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA512
The supported signature scheme algorithms that can be used by System TLS can be changed using SSLCONFIG.
The following GSK_TLS_EXTN_SIG_SCHEME string is the default ordered list supported when the operating system is installed:"GSK_TLS_SIG_SCHEME_ECDSA_SECP521R1_SHA512,GSK_TLS_SIG_SCHEME_ECDSA_SECP384R1_SHA384, GSK_TLS_SIG_SCHEME_ECDSA_SECP256R1_SHA256,GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA512, GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA384,GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA256"
The default string used by System TLS can be changed using SSLCONFIG. -
The following GSK_TLS_EXTN_SIG_SCHEME_CERT strings represent the
signature scheme certificate algorithms supported:
- GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA1
- GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA256
- GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA384
- GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA512
- GSK_TLS_SIG_SCHEME_ECDSA_SHA1
- GSK_TLS_SIG_SCHEME_ECDSA_SECP256R1_SHA256
- GSK_TLS_SIG_SCHEME_ECDSA_SECP384R1_SHA384
- GSK_TLS_SIG_SCHEME_ECDSA_SECP521R1_SHA512
- GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA256
- GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA384
- GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA512
The supported signature scheme certificate algorithms that can be used by System TLS can be changed using SSLCONFIG.
The following GSK_TLS_EXTN_SIG_SCHEME_CERT string is the default ordered list supported when the operating system is installed:"GSK_TLS_SIG_SCHEME_ECDSA_SECP521R1_SHA512,GSK_TLS_SIG_SCHEME_ECDSA_SECP384R1_SHA384, GSK_TLS_SIG_SCHEME_ECDSA_SECP256R1_SHA256,GSK_TLS_SIG_SCHEME_ECDSA_SHA1, GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA512,GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA384, GSK_TLS_SIG_SCHEME_RSA_PSS_RSAE_SHA256,GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA512, GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA384,GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA256, GSK_TLS_SIG_SCHEME_RSA_PKCS1_SHA1"
The default string used by System TLS can be changed using SSLCONFIG. -
The following GSK_TLS_EXTN_SUPPORTED_GROUPS strings represent the
groups supported:
- GSK_TLS_SUPPORTED_GROUP_ECDHE_X25519
- GSK_TLS_SUPPORTED_GROUP_ECDHE_X448
- GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP256R1
- GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP384R1
- GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP521R1
- GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP224R1
- GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP192R1
The supported groups that can be used by System TLS can be changed using SSLCONFIG.
The following GSK_TLS_EXTN_SUPPORTED_GROUPS string is the default ordered list supported when the operating system is installed:"GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP256R1,GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP384R1, GSK_TLS_SUPPORTED_GROUP_ECDHE_X25519,GSK_TLS_SUPPORTED_GROUP_ECDHE_SECP521R1, GSK_TLS_SUPPORTED_GROUP_ECDHE_X448"
The default string used by System TLS can be changed using SSLCONFIG.
Related Information
- gsk_attribute_get_buffer()--Get
character information about a secure session or environment
- gsk_attribute_set_enum()--Set
enumerated 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
API introduced: V5R1
Top | UNIX-Type APIs | APIs by category |