gsk_attribute_set_buffer()--Set character information for a secure session or an SSL environment

 #include <gskssl.h>

 int gsk_attribute_set_buffer(gsk_handle my_gsk_handle,
                              GSK_BUF_ID bufID,
                              const char *buffer,
                              int bufSize);

The gsk_attribute_set_buffer() function is used to set a specified buffer attribute to a value inside the specified secure session or SSL 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 SSL 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 SSL 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 SSL 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 SSL environment.
  
  
• GSK_OS400_APPLICATION_ID (6999) - buffer points to the application identifier to be used for the SSL 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 the SSL 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 the SSL environment. Setting this to NULL will result in the System SSL 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 the SSL 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 the SSL environment. Setting this to NULL will result in the System SSL 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 the SSL 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 the SSL environment. Setting this to NULL will result in the System SSL 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 the SSL 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 the SSL 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 the SSL environment.
  
  
• GSK_SSL_EXTN_SIGALG (245) - buffer points to the list of comma delimited string values of signature algorithms to be supported by the SSL environment when using TLS version 1.2. See the usage notes for the format of the signature algoritms.
  
  
• 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 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 SSL Environment. This would be *SYSTEM if GSK_OS400_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 acknowledgement. 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.
  
  
  

buffer  (Input) 

A pointer to the information to be used for the secure session or the SSL 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_AS400_ERROR_INVALID_POINTER]

The buffer pointer is not valid.

[GSK_INVALID_STATE]

One of the following occurred:

• bufID cannot be set for a SSL 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 SSL 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

1. The following GSK_BUF_ID values may be set in the SSL 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_OS400_APPLICATION_ID
   • 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
     
   
   
2. 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 SSL environment:
   
   
   • GSK_KEYRING_LABEL
   • 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
   
   
3. 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 when the operating system is installed are indicated by the "X" in the appropriate column.
   
   

   GSK_XX_CIPHER_SPECS Representation	GSK_XX_CIPHER_SPECS_EX Representation	QSSLCSL System Value Representation	TLSV12	TLSV11	TLSV10	SSLV3
   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

   
   
4. TLS Version 1.2 is disabled when the operating system is installed. If TLS Version 1.2 is enabled, 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_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 '3C2F3D35'.
   
   
5. TLS Version 1.1 is disabled when the operating system is installed. If TLS Version 1.1 is 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'.
   
   
6. 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'.
   
   
7. The following GSK_V3_CIPHER_SPECS_EX string is the default SSL Version 3 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_V3_CIPHER_SPECS equivalent list is '2F35'.
   
   
8. 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.
   

9. The following GSK_SSL_EXTN_SIGALG strings represent the signature algorithms supported when the operating system is installed:
   
   • GSK_TLS_SIGALG_RSA_WITH_MD5
   • 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
   
   The following GSK_SSL_EXTN_SIGALG string is the default ordered list used when the operating system is installed:

     '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,GSK_TLS_SIGALG_RSA_WITH_MD5'
   

   The default string used by System SSL can be changed using System Service Tools (SST) Advanced Analysis Command SSLCONFIG.
   
   
   
10. 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 SSL.
    
    
11. The following are the possible scenerios for the use of GSK_KEYRING_LABEL:
    
    
    • GSK_KEYRING_LABEL can be set after gsk_environment_open() and before gsk_environment_init() to indicate which certificate in the GSK_KEYRING_FILE to use for the secure environment.
    • GSK_KEYRING_LABEL can be set after gsk_secure_soc_open() and before gsk_secure_soc_init() to indicate which certificate in the GSK_KEYRING_FILE to use for the secure session.
    • If GSK_KEYRING_LABEL is not set, the default certificate label in the GSK_KEYRING_FILE is used for the SSL environment.
    
    
12. If GSK_OS400_APPLICATION_ID is set, the GSK_KEYRING_FILE, the GSK_KEYRING_LABEL, and the GSK_KEYRING_PASSWORD values are ignored.
    
    
13. When GSK_OS400_APPLICATION_ID is set, the settings of some of the SSL 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_TLSV12_CIPHER_SPECS_EX
    • GSK_TLSV11_CIPHER_SPECS_EX
    • GSK_TLSV10_CIPHER_SPECS_EX
    • GSK_V3_CIPHER_SPECS_EX
    • GSK_TLSV12_CIPHER_SPECS
    • GSK_TLSV11_CIPHER_SPECS
    • GSK_TLSV10_CIPHER_SPECS
    • GSK_V3_CIPHER_SPECS
    • GSK_SSL_EXTN_SIGALG
    • GSK_OCSP_URL
    
    
14. When GSK_OS400_APPLICATION_ID is set, the settings of some of the SSL 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 SSL environment buffer attributes during the call to gsk_environment_init():
    • GSK_SSL_EXTN_SERVERNAME_LIST
    • GSK_SSL_EXTN_SERVERNAME_CRITICAL_LIST
    
    
15. 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 SSL.
    
    
16. 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.
    
    
17. 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.
    
    
    
18. The following GSK_BUF_ID values currently are not supported in the IBM^® i implementation:
    
    
    • GSK_KEYRING_STASH_FILE
    • GSK_LDAP_SERVER
    • GSK_LDAP_USER
    • GSK_LDAP_USER_PW
    • GSK_USER_DATA
    • GSK_SID_VALUE
    • GSK_PKCS11_DRIVER_PATH
    • GSK_PKCS11_TOKEN_LABEL
    • GSK_PKCS11_TOKEN_PWD
    • GSK_CSP_NAME
    
    

Related Information

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