gsk_attribute_get_buffer()--Get character information about a secure session or environment


  Syntax 
 #include <gskssl.h>

 int gsk_attribute_get_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_get_buffer() function is used to obtain specific character string information about a secure session or a environment. It can be used to obtain values such as certificate store file, certificate store password, application ID, and ciphers.


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)
The following values can be used to retrieve information about the secure session or environment that is either defaulted or explicitly set:

  • GSK_KEYRING_FILE (201) - buffer points to the name of the certificate store file being used for the secure environment.

  • GSK_KEYRING_PW (202) - buffer points to the password for the certificate store file being used for the secure environment.

  • GSK_KEYRING_LABEL (203) - buffer points to the certificate label associated with the certificate in the certificate store identified by GSK_KEYRING_FILE 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 being used for the secure environment.

  • Start of V7R3 changes 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. End of V7R3 changes

  • 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 in gsk_attribute_set_buffer() API for the format of the ciphers.

  • 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 in gsk_attribute_set_buffer() API for the format of the ciphers.

  • 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 in gsk_attribute_set_buffer() API for the format of the ciphers.

  • 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 in gsk_attribute_set_buffer() API for the format of the ciphers.

  • GSK_V2_CIPHER_SPECS (205) - buffer points to the list of available SSL Version 2 ciphers to be used for the secure session or environment. See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.

  • GSK_CONNECT_SEC_TYPE (208) - buffer points to a string containing "SSLV2", "SSLV3", "TLSV1", "TLSV11", "TLSV12," Start of V7R3 changes or "TLSV13" End of V7R3 changes depending on what was actually negotiated for use by the secure session. For compatibility with previous releases, "TLSV1" is returned for TLS Version 1.0 instead of "TLSV10".

  • GSK_CONNECT_CIPHER_SPEC_EX (244) - buffer is a string describing the cipher specification negotiated for use by the secure session.

    GSK_CONNECT_CIPHER_SPEC (207) (Deprecated) - buffer points to a one- or two-character string describing the cipher specification negotiated for use by the secure session.
    Replaced by GSK_CONNECT_CIPHER_SPEC_EX as some new ciphers can be not represented by two characters.

  • GSK_SID_VALUE (212) - buffer points to a string containing the session ID (SID) used for the secure session.

  • 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 in gsk_attribute_set_buffer() API for the format of the 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 in gsk_attribute_set_buffer() API for further use of this attribute in conjunction with GSK_OCSP_ENABLE.

  • 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_UNKNOWNREVOCATIONSTATUS_SUBJECT (224) - When a non-zero buffer length is returned, buffer points to a list of subject names in the form [SubjectName=]xxxxx for which revocation status was unknown during certificate validation when OCSP was enabled. A buffer length of zero indicates that there were no subjects for which revocation was unknown. This call should be issued immediately after gsk_secure_soc_init() if using OCSP.

  • GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT_NO_AIA (252) - When a non-zero buffer length is returned, buffer points to a list of subject names in the form [SubjectName=]xxxxx for which revocation status was unknown during certificate validation when OCSP Authority Information Access (AIA) checking was enabled and an AIA extension was not available. A buffer length of zero indicates that there were no subjects for which revocation was unknown when an AIA extension was not available. This call should be issued immediately after gsk_secure_soc_init() if using OCSP.

  • GSK_VALIDATIONFAIL_SUBJECT (235) - When a non-zero buffer length is returned, buffer points to a list of subject names in the form [SubjectName=]xxxxx for which revocation status was revoked during certificate validation when OCSP was enabled. A buffer length of zero indicates that there were no subjects for which revocation was revoked. This call should be issued immediately after gsk_secure_soc_init() if using OCSP.

  • 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 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 called multiple times to retrieve an array of FQDN and certificate label pairs previously set. NULL is returned when all array entries have been returned. The next call would repeat the process starting at the beginning of the array.

  • GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST (233) - buffer points to both a null-terminated FQDN and certificate label 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 called multiple times to retrieve an array of FQDN and certificate label pairs previously set. NULL is returned when all array entries have been returned. The next call would repeat the process starting at the beginning of the array.

  • GSK_SSL_EXTN_SERVERNAME (234) - buffer points to the FQDN that was negotiated using the SNI extension. This is one way a server would determine which of its certificates was used for the secure session.

  • GSK_CONNECT_COMPRESSION (247) - buffer points to a string describing the compression specification used for the secure session. *NONE is the only supported value.

  • Start of V7R3 changes 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_SSL_EXTN_SELECTED_ALPN_PROTOCOL (277) - buffer points to a string describing the ALPN protocol negotiated for the secure session.
    End of V7R3 changes

  • Start of V7R3 changes 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 in gsk_attribute_set_buffer() API for the format of the 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 in gsk_attribute_set_buffer() API for the format of the 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 in gsk_attribute_set_buffer() API for the format of the algorithms.End of V7R3 changes


buffer (Output)
The address of the location to place the pointer that will point to the buffer containing the requested information. The storage for this information was allocated by the system from user heap storage and will be freed by the gsk_secure_soc_close() API or the gsk_environment_close() API.

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 (Output)
The address of the location to store the length of the requested information pointed to by buffer.

Authorities

No authorization is required.


Return Value

gsk_attribute_get_buffer()

returns an integer. Possible values are:

[GSK_OK]
gsk_attribute_get_buffer() was successful.

[GSK_ATTRIBUTE_INVALID_ID]
The specified bufID was not valid.

[GSK_INVALID_HANDLE]
The specified handle was not valid.

[GSK_IBMI_ERROR_INVALID_POINTER]
The buffer or bufSize pointer is not valid.

[GSK_ERROR_UNSUPPORTED]
The bufID currently is not supported.

[GSK_ERROR_IO]
An error occurred in TLS processing. Check the errno value.

Error Conditions

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

  1. The following GSK_BUF_ID values may be retrieved from the secure environment after gsk_environment_open().

    • GSK_KEYRING_FILE
    • GSK_KEYRING_PW
    • GSK_KEYRING_LABEL
    • GSK_KEYRING_LABEL_EX
    • GSK_IBMI_APPLICATION_ID
    • Start of V7R3 changesGSK_TLSV13_CIPHER_SPECS_EX End of V7R3 changes
    • 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
    • Start of V7R3 changesGSK_SSL_EXTN_ALPNEnd of V7R3 changes
    • Start of V7R3 changesGSK_TLS_EXTN_SIG_SCHEME
    • GSK_TLS_EXTN_SIG_SCHEME_CERT
    • GSK_TLS_EXTN_SUPPORTED_GROUPSEnd of V7R3 changes

  2. The following GSK_BUF_ID values may be retrieved from the secure session after gsk_secure_soc_open().

    • GSK_KEYRING_LABEL
    • GSK_KEYRING_LABEL_EX
    • Start of V7R3 changesGSK_TLSV13_CIPHER_SPECS_EX End of V7R3 changes
    • 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_CONNECT_COMPRESSION
    • Start of V7R3 changesGSK_SSL_EXTN_ALPN
      End of V7R3 changes

  3. The following GSK_BUF_ID values are defaulted after gsk_secure_soc_open() and will be set for the secure session after gsk_secure_soc_init().
    • GSK_SSL_EXTN_SERVERNAME
    • GSK_CONNECT_CIPHER_SPEC_EX
    • GSK_CONNECT_CIPHER_SPEC
    • GSK_CONNECT_SEC_TYPE
    • GSK_SID_VALUE
    • GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT
    • GSK_UNKNOWNREVOCATIONSTATUS_SUBJECT_NO_AIA
    • GSK_VALIDATIONFAIL_SUBJECT
    • Start of V7R3 changesGSK_SSL_EXTN_SELECTED_ALPN_PROTOCOL
      End of V7R3 changes

  4. The following GSK_BUF_ID values may be changed for the secure session after gsk_secure_soc_misc(), gsk_secure_soc_read() or gsk_secure_soc_startRecv() if a TLS handshake happened under the context of those calls for the secure session.
    • GSK_CONNECT_CIPHER_SPEC_EX
    • GSK_CONNECT_CIPHER_SPEC
    • GSK_SID_VALUE

  5. The buffer pointer can be referenced as long as the handle for the secure session or environment is still open.

  6. 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():
    • Start of V7R3 changesGSK_TLSV13_CIPHER_SPECS_EX End of V7R3 changes
    • 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
    • Start of V7R3 changesGSK_TLS_EXTN_SIG_SCHEME
    • GSK_TLS_EXTN_SIG_SCHEME_CERTEnd of V7R3 changes

  7. 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

  8. Start of V7R3 changesThe default cipher suite list in preference order as shipped is as follows:
    • GSK_TLSV13_CIPHER_SPECS_EX set to: 
         "TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256"
    • GSK_TLSV12_CIPHER_SPECS_EX set to: 
         '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.

    • GSK_TLSV11_CIPHER_SPECS_EX set to: 
         'TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA'
      The GSK_TLSV11_CIPHER_SPECS equivalent list is '2F35'.

    • GSK_TLSV10_CIPHER_SPECS_EX set to: 
         '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 resulting in GSK_V3_CIPHER_SPECS_EX and GSK_V3_CIPHER_SPECS set to the null character (\0).
    • SSL Version 2 support is disabled when the operating system is installed resulting in GSK_V2_CIPHER_SPECS set to the null character (\0).

      • 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 list 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.

      See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers.

      End of V7R3 changes

Related Information


API introduced: V5R1