Existing keystores for SSL/TLS database connections

OneDB supports PKCS#12 format keystores for use with the OpenSSL encryption library. If you have used SSL/TLS connections before installing OneDB, you will have keystores and stash files with the keystore password. This topic describes, how such keystores can be migrated for use with SSL/TLS connections of OneDB. The steps are applicable to keystores for OneDB database server as well as for OneDB database clients.

For more information on SSL/TLS keystores, see Secure sockets layer protocol.

When migration of a keystore file is necessary:

If your keystore has the PKCS#12 standard format, then this keystore need not be migrated. PKCS#12 format keystore files usually have “.p12” as file name extension.
If your keystore has the IBM GSKit (Global Security Kit) proprietary CMS format, then this keystore needs to be converted to the PKCS#12 standard format. Keystore files in the CMS format usually have “.kdb” as file name extension.
To convert the keystore:
As the CMS format is GSKit-specific, you need the GSKit command "gsk8capicmd" (or "gsk7capicmd") in order to convert the keystore. Use a command like:
```
    gsk8capicmd -keydb -convert -db KEYSTOREFILE.kdb -pw PASSWORD \ 
      -old_format cms -new_db KEYSTOREFILE.p12 -new_pw PASSWORD \
      -new_format pkcs12
```

If you used a password stash file for your keystore:

Check if a password stash file exists for your keystore. Generally, the stash file is located in the same directory and has the same file name as the keystore file with the only difference being the file name extension. A password stash file created for use with GSKit usually has file name extension “.sth”. A password stash file created for use with OneDB and OpenSSL has the file name extension “.stl”.
If, for your keystore you already have a password stash file with file name extension “.stl”, then this should be sufficient.
If you only have a “*.sth” file, or if you are in doubt, create a new password stash file using the utility onkstash. Use a command like the following:
```
onkstash KEYSTOREFILE.p12 PASSWORD
```

If you do not know the password for your already existing keystore:

If you have a “*.sth” password stash file for your keystore, then you may no longer know the password and for all keystore access rely solely on this stash file. But you need to know the password in order to run the above onkstash command.

If you need to convert your keystore from the CMS to the PKCS#12 format, then use the option “-stashed” instead of “-pw PASSWORD” in the conversion command. Run the command like:
```
gsk8capicmd -keydb -convert -db KEYSTOREFILE.kdb -stashed \ 
      -old_format cms -new_db KEYSTOREFILE.p12 -new_pw PASSWORD \
      -new_format pkcs12
```
By specifying the new password for the converted keystore file with “-new_pw PASSWORD”, the password for the converted PKCS#12 keystore is known and can then be used in the subsequent onkstash command.
If you do not need to convert your keystore because it already has the PKCS#12 format, then you need to use the GSKit utility to change the password. Instead of requiring the old password, with option “-stashed” the GSKit utility can change the password using the stash file, so that you only need to specify the new password. Run a command like:
```
gsk8capicmd -keydb -changepw -db KEYSTOREFILE.p12 -stashed \
  -new_pw PASSWORD
```