Secure sockets layer protocol

Digital certificates that exchange keys in SSL connections

SSL uses digital certificates, which are electronic ID cards issued by a trusted party, to exchange keys for encryption and server authentication.

The trusted entity that issues a digital certificate is known as a Certificate Authority (CA).

The CA issues a digital certificate for only a limited time. When the expiration date passes, you must acquire another digital certificate.

With SSL, the data that moves between a client and server is encrypted by a symmetric key algorithm. With a symmetric key algorithm, the same encryption key is used to encrypt and decrypt the data. In an SSL communication, both communication partners (SSL client and SSL server) use the same encryption key. As this key can be used to decrypt the data, it must be kept a secret and shared only between the two SSL communication partners. Therefore, at the beginning of an SSL connection, an asymmetric key (private-public key) algorithm is used for the exchange of the secret symmetric key.

When a client attempts to connect to a secure server, an SSL handshake occurs. The handshake involves the following events:

1. The server sends its digital certificate to the client.
2. The client verifies the validity of the server digital certificate. For this to occur, the client must possess the digital certificate of the CA that issued the server digital certificate.

If the handshake succeeds, these events occur:

1. The client generates a random symmetric key and sends it encrypted to the server. For this encryption, the client uses the public part of the asymmetric key. This public key is contained in the server digital certificate.
2. The server receives the encrypted symmetric key and decrypts it with its private key.

Data encrypted with the public key can be decrypted only with the corresponding private key, which is only in the possession of the server. With that, it is guaranteed, that the symmetric key remains a secret, shared only between the client and the server.

As both the server and client now know the symmetric key, they can use it to encrypt the data transferred between server and client for the duration of the session. Data encryption and decryption with a symmetric key algorithm is much more efficient than with an asymmetric key algorithm. Therefore, the asymmetric key algorithm is only used to exchange the symmetric key at the beginning of an SSL connection. Then the symmetric key algorithm is used for the bulk of the data moved during the connection.

In a most simplistic setup for SSL communication, the SSL server only uses a single self-signed certificate. Therefore no involvement of a CA is needed. To authenticate the SSL server, an SSL client needs a copy of the server’s self-signed certificate in its own client keystore. During the SSL handshake, the server sends its self-signed certificate to the client. The client looks for the copy of this certificate in its own keystore and compares the two certificates. An exact match is expected for the SSL handshake to succeed.

Keystores that store SSL keys and digital certificates

A keystore is a protected database that stores SSL keys and digital certificates. Both the client and server must have a keystore that stores the digital certificates used in SSL communication.

The keystore has the PKCS#12 standard format with encrypted content and a password is needed in order to access it. Therefore, both, the database server as well as the database client, need the respective password for their individual keystore in order to access it. To allow keystore access without providing the password interactively or upon startup of the database server or the database client, the keystore password can be stored in a password stash file in an encrypted format.

To stash the keystore password, use the utility "onkstash" and specify the file path name of the keystore and the cleartext password on the command line. The stash file is created with the same file path name but a different filename extension, "*.stl".

To get the password when accessing their respective keystore, both, the database server as well as the database client, can use the password stash file if it exists at the expected location and has the correct filename extension.

For information about tools for creating the client and server keystores, also see the OpenSSL documentation at www.openssl.org.

The server keystore and its configuration

The keystore stores the server’s own digital certificate and corresponding private key, as well as CA certificates for authenticating all other servers that HCL OneDB is connecting to. The server keystore must be located in the ONEDB_HOME/ssl directory. The name of the keystore file must be server_name.p12, where server_name is the value specified in the DBSERVERNAME configuration parameter.

Each HCL OneDB instance must have its own keystore.

Each certificate in the keystore must have a unique "friendly name" to be used as identifier for the certificate. When you set up HCL OneDB to use SSL, you must specify this "friendly name" of the server’s own digital certificate with the SSL_KEYSTORE_LABEL configuration parameter in the server configuration file.

The keystore is protected by a password that HCL OneDB must know so that it can access the digital certificates in the keystore for SSL communications. HCL OneDB stores its keystore password in an encrypted form in a stash (.stl) file in the ONEDB_HOME/ssl directory. The name of the keystore stash file must be server_name.stl.

The password for the keystore is mandatory, because this password protects the server’s private key in the keystore.

The permissions on the ONEDB_HOME/ssl/server_name.p12 and $ONEDB_HOME/ssl/server_name.stl files must be 600, with onedb set as both the owner and the group, even though HCL OneDB does not enforce these permissions.

The client keystore and its configuration

The keystore on the HCL OneDB client stores the CA certificates needed for the authentication of all servers to which the client is connecting. A database client can retrieve its keystore password from a stash file. This stash file can be created with the utility onkstash to contain the keystore password in an encrypted form.

For HCL OneDB SQLI clients (ESQL/C, ODBC, DB-Access, and the dbexport, dbimport, dbschema, and dbload utilities), the location of the keystore and its stash file is not fixed. Instead, the conssl.cfg file in the $ONEDB_HOME/etc directory specifies the keystore file and (optionally the stash file) for HCL OneDB clients.

The following table shows the client configuration parameters that are in the conssl.cfg file.

If a conssl.cfg file does not exist or the SSL_KEYSTORE_FILE and SSL_KEYSTORE_STH configuration parameters are not set, the client uses $ONEDB_HOME/etc/client.p12 and $ONEDB_HOME/etc/client.stl as the default keystore and keystore stash file names for the client.