Existing Keystores for Encrypting Data at Rest

OneDB server allows you to encrypt your data that is at rest. The term “data at rest” refers to data that resides on a persistent medium, like a disk or a backup medium. Data that is in main memory, on the other hand, is not considered being data at rest, even if it stays in memory for a long time.

For the encryption of data at rest, OneDB offers two different encryption methods, Storage Space Encryption for database data on disk, and Integrated Backup Encryption for data written to a backup medium. If you have used either of these two methods with a system from which you are migrating to OneDB, you may have to perform a conversion task for the keystores used with the encryption. This is because OneDB uses OpenSSL as encryption library and OpenSSL only supports the standard PKCS#12 format for keystores. In addition, OneDB uses its own format for keystore password stash files, and this format cannot be compatible with other formats, e.g. of stash files created with GSKit.

Follow these steps:

Check, what type of encryption at rest you are using, and what the associated keystore files are. In your server configuration file, check for the settings of parameters DISK_ENCRYPTION, BAR_ENCRYPTION and BAR_DECRYPTION. For parameters that are active, check the value for keystore. The keystore value contains the name of the keystore file. By default, i.e. when no absolute path name is specified, these keystore files are in the $ONEDB_HOME/etc directory.
The keystore value in the parameters only specifies the file name, without the file name extension. Find the keystore files in the file system and check their file name extension. Keystore files with file name extension “.p12” should be in the standard PKCS#12 format. Keystores in this format can be used with OneDB without conversion.
If you find a keystore file that has “.kdb” as file name extension, then this is a keystore in the GSKit proprietary CMS format. If you dont’ find a corresponding file with the same name, but the “.p12” file name extension, then the CMS keystore file (“*.kdb”) must be converted to a PKCS#12 format keystore. As the CMS format is GSKit proprietary, you need a GSKit utility like “gsk8capicmd” or “gsk7capicmd” to perform this conversion. Use a command like the following:
```
gsk8capicmd -keydb -convert -db KEYSTOREFILE.kdb -pw PASSWORD \ 
      -old_format cms -new_db KEYSTOREFILE.p12 -new_pw PASSWORD \
      -new_format pkcs12
```
With the “-pw” option, you have to provide the password for the CMS keystore file (“*.kdb”) and with the “-new_pw” option, you have to provide a password for the new PKCS#12 keystore. The two passwords can be same.
- If you do not know the password for the “*.kdb” keystore file, then check if you have a password stash file. The password stash file has same name as the keystore file, but file name extension will be “.sth”. If you have the “*.sth” file for your keystore file, then you can perform the conversion without specifying the password for the “*.kdb” file. The GSKit utility can instead use the stash file to retrieve the needed password. Use a command like the following:
```
 gsk8capicmd -keydb –convert –db KEYSTOREFILE.kdb -stashed \ 
      -old_format cms -new_db KEYSTOREFILE.p12 -new_pw PASSWORD \
      -new_format pkcs12
```
Check, if you have a password stash file for your PKCS#12 keystore (original “*.p12” file or converted from a “*.kdb” file). The password stash file has the same file name as the keystore file, but a different file name extension, either “.stl” or “.sth”.
- A password stash file with file name extension “.stl” should be usable by OneDB as-is.
- A password file with file name extension “.sth” was created with GSKit and is in a GSKit proprietary format. In this case, you have to create a new password stash file (“*.stl”) for use with OneDB. Use the onkstore utility with a command like the following:
```
onkstore -stash -file KEYSTOREFILE
```
  The command prompts you for the password of the KEYSTOREFILE.p12 file. Alternatively, you can store the password in a file and provide the name of this file on the command line by adding the option “-pw <password file>” to the above command.
  - To run the “onkstore -stash” command, you need to know the password for the PKCS#12 keystore file. If you already had the “*.p12” file, but you do not know the password for it, then check if you have a corresponding “*.sth” password stash file. If you have such a “*.sth” file, then you first need to change the password of your existing PKCS#12 keystore to a new known password. You need to use a GSKit utility to change the password, as the GSKit utility can retrieve the needed password from the “*.sth” stash file. Use a command like the following:
```
gsk8capicmd -keydb -changepw -db KEYSTOREFILE.p12 -stashed \
  -new_pw PASSWORD
```
    After changing the password, you know the new password for the “*.p12” keystore file and can run the above onkstore -stash command to create the new password stash file for OneDB.