Keystore best practices

Employ security best practices to keep your keystores and master keys secure.

Keystore credentials

Most keystore configurations require that credentials be passed to the keystore before access to the stored keys is allowed. Since Db2® needs to have access to the keystore, Db2 also needs to have access to the keystore credentials. This information is required when the db2start command is run. There are a number of ways to securely provide Db2 the keystone credentials:
  • A prompt for operator input of the credentials
  • Access through a provided file argument
  • Use of a “stash” file
A stash file is an obfuscated file that contains the credentials that are needed to access the keystore. Set this file to be readable by only the Db2 instance owner. Details on how to create a stash file is provided in the detailed keystore configuration information.
Note: Ensure that you back up your passwords, in addition to using a stash file. This applies particularly to the password used for a local keystore file. Should your stash file ever become corrupted, you will need to manually supply the password. If you forget the password, and do not created a backup, access to your keys and data is lost.

When creating or changing passwords for local keystone files, ensure that the passwords are strong, by using the –strong parameter of the gsk8capicmd_64 command. For more information about the full syntax of the gsk8capicmd_64 command, see: GSKCapiCmd Users Guide.

Keystore backups

The contents of your keystore are critical and it is important that you back up the keystore at regular intervals. Backups should be done whenever the contents of the keystore changes, such as when a key or certificate is added, a master key (MK) is rotated, or the password is changed.
Note: Backing up when there is a password change applies only to stash files, and not to all keystores. It also applies to the local keystore files.

The keystore configuration files are not included as part of a Db2 database backup and must be backed up manually. Keystore credentials, if stored on disk, must also be backed up manually.

For local keystore files, the configuration file is not included as part of a Db2 database backup and must be backed up manually.

For a centralized keystore, consult the documentation for your keystore product to understand their recommendations for keystore backups.

MK label uniqueness

Db2 uses the MK label to uniquely identify each MK, and stores the label value in each encrypted object, be it a database, transaction log, or backup file. This stored label value identifies the MK that is used to decrypt the data encryption key (DEK), which is used to encrypt the data in the object. It is critical to use unique MK labels to avoid duplication. If unique labels are not used, access to encrypted data can be lost. Access to encrypted data is lost when the MK that is retrieved from the keystore for a label is different from the MK that is used to encrypt the DEK in the object.

Master key retention

MKs are needed to access the DEKs that are stored in encrypted databases, transaction logs, and backup images. Since multiple MKs can exist over the life time of these objects, it is necessary to retain them while the encrypted data is retained. Therefore, do not delete MKs from the keystore.

Keystore configuration changes

Thoughtful planning needs to precede any changes to the Db2 database managed keystore configuration parameters or the contents of a keystore configuration, as not all changes can be completed online. Each new key request reads these values when it is accessing the keystore. With some exceptions, changes to these configuration values are reflected in the Db2 processing on the next key request. Although the Db2 database manager configuration parameters keystore_type and keystore_location are configurable online, you should set them in the a single db2 update dbm cfg command. Otherwise, Db2 might attempt to access the keystore between the updates and report an access error. Changes to the SSL_KEYDB, SSL_KEYDB_STASH, and SSL_KMIP_CLIENT_CERTIFICATE_LABEL keystore configuration values require an instance restart to take effect. Changes to the LIBRARY keystore configuration value do not take effect until Db2 is restarted. Similarly, if the configuration value is not changed, changes to the physical copy of the library do not take effect until Db2 is restarted. As Db2 can access the keystore periodically, it is highly recommended that you stop Db2 when making configuration changes, to avoid potential errors. If a mixture of encrypted and unencrypted databases exists under the same instance, it is sufficient to quiesce those databases that are encrypted.

Key rotation

Key rotation refers to the process of changing encryption keys and is often required for compliance purposes. Key rotation is done to reduce the risk that can come from exposure of the key, while it exists. Since the DEK used by Db2 for encryption is never outside of the encrypted database, backup, or transaction log, there is little risk of exposure. The same is not true for the MK, which lives outside of the database. Db2 provides a simple way to rotate the MK by using the SYSPROC.ADMIN_ROTATE_MASTER_KEY procedure. This procedure decrypts the embedded DEK, using the old MK, and then re-encrypts it with the new one. The rotation of the MK does not affect the encryption of the DEK within existing backups or archived transaction logs, but it does affect future DEK entries. A key rotation on the primary database in an HADR environment drives a key rotation automatically on the standby. The change, however, does not occur until other log records are sent to the standby database. If you want to force the rotated key to the standby, the archive log command can be used to generate the log records that are needed to replay the rotation on the standby. When the MK is rotated, the database begins to use the new key immediately, but access to the old MK value is still needed in the following scenarios:
  • Transaction log files that have not been reused since the key rotation
  • Archived encrypted transaction log files that used the previous MK value
  • Encrypted backup images that used the previous MK value
Do not delete an MK from the keystore unless you are certain it is no longer referenced by any encrypted object.