Using server multiple key label support

When creating a server environment in System SSL, you have the option of specifying a single label of a key to be used for each connection utilizing attribute GSK_KEYRING_LABEL,

rc = gsk_attribute_set_buffer(env_handle, GSK_KEYRING_LABEL,
     "ServerCertLabel",0);

or specifying multiple key labels utilizing attribute GSK_SERVER_KEYRING_LABEL_LIST,

rc = gsk_attribute_set_buffer(env_handle,  GSK_SERVER_KEYRING_LABEL_LIST,
     "ServerCertLabel1,ServerCertLabel2,ServerCertLabel3",0);

Utilizing multiple key label support allows for a single server to support a range of certificates and key exchange types and thereby allowing secure connections with a larger range of clients. For example, specifying:

rc = gsk_attribute_set_buffer(env_handle, GSK_SERVER_KEYRING_LABEL_LIST, 
     "rsa1024Cert,ecc256Cert",0);

could allow connections to two different clients using completely different keys and key exchange types as long as the GSK_V3_CIPHER_SPECS or GSK_V3_CIPHER_SPECS_EXPANDED attribute contains an appropriate cipher for the protocol.

Utilizing multiple key label support also allows an administrator to specify certificates that will soon expire along with certificates that are not valid yet in order to avoid interruption of service by having to restart a server by specifying a new GSK_KEYRING_LABEL.

rc = gsk_attribute_set_buffer(env_handle, GSK_SERVER_KEYRING_LABEL_LIST, 
     "rsaCertExpiresApril_1_2016,rsaCertValidApril_1_2016",0);

Selection of an appropriate certificate is based upon the following criteria:

• The highest protocol the client and server both support. The supported protocols are SSL Version 3.0, TLS Version 1.0, TLS Version 1.1, TLS Version 1.2, and TLS Version 1.3. Note that SSL Version 2.0 is not supported within multiple key label support.
• When the negotiated protocol is TLS V1.2 or earlier:
  • The server's supported cipher list based upon that protocol.
  • The client's supported cipher list.
  
• When the negotiated protocol is TLS V1.3:
  • Basic certificate validity checking.
  

This selection criteria identifies the first certificate in the list that matches the above parameters that both the server and client support.

When utilizing server multiple key label support, it is important to consider the following:

• Protocol SSL V2 is not supported with multiple key label support. If the selected protocol between a client the server is SSL Version 2.0, attribute GSK_KEYRING_LABEL must be set in order to provide the server with the key label to be used for the connection.
• Certificates should be placed in the list in order of preference.
• Each key label specified for GSK_SERVER_KEYRING_LABEL_LIST should be contained within the keystore pointed to by GSK_KEYRING_FILE. Otherwise, that key label is ignored for possible usage with a connection.
• Using multiple certificates of the same key type is not advantageous unless a certificate early in the preference order is expected to expire soon and a certificate later in the order is expected to be the replacement certificate.
• A certificate selected from the list is the first certificate that fulfills the previously stated criteria. Handshake processing may fail later due to an additional requirement placed upon the certificate during connection creation.

GSK_SERVER_KEYRING_LABEL_LIST can be set at either the environment level or for an individual connection. When set at the environment level, the provided list is used for all subsequent connections unless a new list is defined for an individual connection.

/* create the SSL environment */
rc = gsk_environment_open(&env_handle);

/* set environment attributes */
rc = gsk_attribute_set_buffer(env_handle, GSK_SERVER_KEYRING_LABEL_LIST,
 "ServerCertLabel1,ServerCertLabel2,ServerCertLabel3",0);

/* initialize environment */
rc = gsk_environment_init(env_handle);

rc = gsk_secure_socket_open(env_handle, &soc1_handle);

gsk_secure_socket_init() will attempt to select a certificate from ServerCertLabel1 through ServerCertLabel3.

rc = gsk_secure_socket_open(env_handle, &soc2_handle);

rc = gsk_attribute_set_buffer(soc2_handle, GSK_SERVER_KEYRING_LABEL_LIST,
 "ServerCertLabel4,ServerCertLabel5,ServerCertLabel6,ServerCetLabel7",0);

Once a connection is made, use the gsk_attribute_get_buffer() routine to find out which certificate was selected to complete the connection.

rc = gsk_attribute_get_buffer(soc1_handle, GSK_KEYRING_LABEL, userBuffer,
     userBufferLength);

rc = gsk_attribute_get_buffer(soc2_handle, GSK_KEYRING_LABEL, userBuffer,
     userBufferLength);