DB2 10.5 for Linux, UNIX, and Windows

Implementing DB2 native database encryption

Use DB2® native encryption to protect the data in your DB2 database.

Before you begin

To use DB2 native encryption, perform the following setup and configuration steps.

  1. Ensure that the path to the IBM® Global Security Kit (GSKit) libraries appears in the PATH environment variable on Windows platforms and the LIBPATH, SHLIB_PATH, or LD_LIBRARY_PATH environment variable on Linux or UNIX-based platforms. GSKit is automatically included when you install the DB2 database system, and when you install the 64-bit version of the DB2 server, the 32-bit GSKit libraries are automatically included in the installation. Ensure that the appropriate environment variable is correctly set, as shown in the following table.
    Operating system Location of GSKit libraries Environment variable setting
    Linux and UNIX 32-bit $INSTHOME/sqllib/lib32/gskit Include $INSTHOME/sqllib/lib32/gskit in the LD_LIBRARY_PATH, LIBPATH, or SHLIB_PATH environment variable.
    Linux and UNIX 64-bit $INSTHOME/sqllib/lib64/gskit Include $INSTHOME/sqllib/lib64/gskit in the LD_LIBRARY_PATH, LIBPATH, or SHLIB_PATH environment variable.
    Windows 32-bit C:\Program Files (x86)\IBM\gsk8\lib Include C:\Program Files (x86)\IBM\gsk8\lib in the PATH environment variable.
    Windows 64-bit

    64-bit GSKit libraries:
    C:\Program Files\IBM\gsk8\lib64

    32-bit GSKit libraries:
    C:\Program Files (x86)\IBM\gsk8\lib

    Include C:\Program Files\IBM\gsk8\lib64 or C:\Program Files (x86)\IBM\gsk8\lib in the PATH environment variable.
    To set the LD_LIBRARY_PATH environment variable, run the export command, as shown in the following example:
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/sqllib/lib64/gskit
    Important: On non-Windows platforms, the DB2 database manager installs GSKit locally, and for a given instance, the GSKit libraries are located in sqllib/lib32/gskit or sqllib/lib64/gskit. If a global copy of GSKit exists (in /usr/lib), keep the local and global copies at the same version level.
  2. Create a PKCS#12-compliant keystore (a storage object for encryption keys) by using the gsk8capicmd (or gsk8capicmd_64) GSKit command. The path for this command is sqllib/gskit/bin on Linux or UNIX-based platforms, and C:\Program Files\IBM\gsk8\bin on both 32-bit and 64-bit Windows platforms. (On 64-bit platforms, the 32-bit GSKit executable files are also present; in this case, the path for the command is C:\Program Files (x86)\IBM\gsk8\bin.) Include the appropriate path to the executable file in the PATH environment variable. For information about the gsk8capicmd command, see the GSKCapiCmd User's Guide, which is available at http://www-01.ibm.com/support/docview.wss?uid=swg27038855. To run the gsk8capicmd command, you must be logged on as the instance owner. In partitioned database environments or DB2 pureScale® environments, the keystore location must be accessible to all members. There is at most one keystore per DB2 instance. For example:
    gsk8capicmd -keydb -create -db ccardskeystore.p12
      -pw Str0ngPassw0rd –strong -type pkcs12 –stash;
    The keystore password can be stashed to a file that automatically provides the password when required. If you specify the stash option when you create the keystore, the password is stashed into a file named keystore_name.sth. The stash file can be read by only the file owner. Not stashing the password enhances security if the instance owner account becomes compromised. However, this additional security must be weighed against any requirements that the DB2 instance can start without human intervention. If the password is not stashed, you cannot access an encrypted database until you provide the keystore password.
  3. Add a master key to the keystore. A new master key is automatically added when you create an encrypted database without specifying the MASTER KEY LABEL option on the CREATE DATABASE command. The database manager uses this master key by default, but you can optionally add a different master key. If your database is not encrypted, but you want to encrypt a backup image, perform one of the following actions:
    • Add a master key to the keystore and specify the label for that master key on the BACKUP DATABASE command.
    • Set the encrlib and encropts database configuration parameters to valid non-null values. In this case, you do not have to specify the master key label on the BACKUP DATABASE command, because it is implicitly specified by the value of the encropts configuration parameter.

    In the following example, the master key is located in a file named mysecretkeyfile. This file should be populated from a secure random source. Consult your operating system documentation to determine whether a secure random source, such as /dev/random for example, is available. The file must be a binary file whose size must be exactly the size of the key that will be used to encrypt the database, otherwise an error is returned. For example, if AES 256 will be used to encrypt the database, mysecretkeyfile must be 256 bits (32 bytes) long.

    gsk8capicmd –secretkey –add –db ccardskeystore.p12
      –stashed –label mylabel.mydb.myinstance.myserver
      –file mysecretkeyfile;
    The CREATE DATABASE command can automatically create a master key. Alternatively, you can add your own master key to the keystore and specify that key in the CREATE DATABASE command.
  4. Configure the DB2 instance with the new keystore by setting the keystore_type and keystore_location database manager configuration parameters. For example:
    db2 update dbm cfg using keystore_type pkcs12
      keystore_location /home/db2/ccardskeystore.p12

About this task

Implementing DB2 native encryption includes the following steps:
  1. Create a keystore.
  2. Add a database master key to the keystore (or have the CREATE DATABASE command automatically create a master key).
  3. Configure the DB2 instance with the new keystore.
  4. If the password is not stashed, open the keystore by using the db2start command with the OPEN KEYSTORE option.
  5. Specify encryption parameters on the CREATE DATABASE command.
  6. Specify encryption parameters on the BACKUP DATABASE and RESTORE DATABASE or RECOVER DATABASE commands. For both encrypted and non-encrypted databases, database backup images are automatically encrypted if the encrlib and encropts database configuration parameters are set to a non-null value. For encrypted databases, these parameters are set to the values that are specified when the databases are created.
  7. Rotate the database master key by calling the ADMIN_ROTATE_MASTER_KEY procedure. Like user passwords, encryption keys should be changed regularly to minimize risk if a key is compromised.

Restrictions

Procedure

To encrypt a new database by using only default settings:

  1. Specify the ENCRYPT option on the CREATE DATABASE command. For example:
    db2 create db mydb encrypt

To encrypt a new database by using custom settings:

  1. Specify other options on the CREATE DATABASE command.
    • CIPHER cipher-name specifies the encryption algorithm that is to be used for encrypting the database.
    • KEY LENGTH key-length specifies the length of the key that is to be used for encrypting the database.
    • MASTER KEY LABEL label-name specifies a label for the master key that is used to encrypt the database.
    For more information, see CREATE DATABASE command. For example:
    db2 create db mydb encrypt
      cipher aes key length 128
      master key label mylabel.mydb.myinstance.myserver

Examples

Encrypt a new database
A client is working on a project for which compliance with PCI DSS is mandatory. A new database named CCARDS is to contain customer credit card information. The DB2 instance administrator is tasked with setting up encryption for the CCARDS database. The data must be encrypted with AES 192. It is decided that stashing the keystore password is acceptable, because the database server is highly secure. The administrator plans to regularly back up the keystore and its stash file.
  1. Create the keystore. For example:
    gsk8capicmd -keydb -create -db /home/db2/ccardskeystore.p12
      -pw Str0ngPassw0rd –strong -type pkcs12 –stash;
  2. Configure the DB2 instance with the new keystore. For example:
    db2 update dbm cfg using keystore_type pkcs12
      keystore_location /home/db2/ccardskeystore.p12
  3. Create the CCARDS database with the encryption option. For example:
    db2 create db ccards encrypt cipher AES KEY LENGTH 192
    A master key for the database is automatically generated and added to the keystore.
  4. Back up the keystore and its related stash file, and store the backup copy in a safe location.
Encrypt a database backup image
When you create an encrypted database, the encrlib and encropts database configuration parameters are set such that subsequent database backup operations use the native DB2 encryption library with options that were specified at database creation time. In the following example, a database backup image is encrypted by using the current (non-null) values of the encrlib and encropts configuration parameters.
db2 backup database ccards
The DB2 library that implements native backup encryption support is named db2encr.dll on Windows operating systems. On other platforms, the library name is libdb2encr, and the library file name extension is operating system-dependent. To specify a different library, or to specify the DB2 library when automatic encryption of backup images is not enabled (that is, when the encrlib database configuration parameter is set to the null value), use the ENCRLIB option on the BACKUP DATABASE command, as shown in the following example:
db2 backup database ccards encrypt encrlib 'db2encr.dll'
To both compress and encrypt a database backup image, specify the db2compr_encr library (or the libdb2compr_encr library on non-Windows platforms) in place of db2encr (or libdb2encr).
In the following example, a database backup image is encrypted by using the specified master key to protect the data encryption key. The encryption algorithm that is to be used for encrypting the database is the Advanced Encryption Standard (AES) algorithm, and the length of the key that is to be used for encrypting the database is 128 bits.
db2 backup database ccards encrypt encrlib 'db2encr.dll'
  encropts 'Cipher=AES:Key LENGTH=128:
    Master Key Label=mylabel.mydb.myinstance.myserver'
Restore an encrypted database backup image
The client wants to restore an encrypted backup image. By default, the encryption library is stored within the backup image itself, but the client decides to specify an encryption library by using the ENCRLIB option on the RESTORE DATABASE command. And also by default, the RESTORE DATABASE command tries to decrypt the data encryption key by using the master key that was used to encrypt the data encryption key in the backup image. In the following example, an encrypted database backup image is restored by using a specific master key label.
db2 restore database ccards encrlib 'db2encr.dll'
  encropts 'Master Key Label=mylabel.mydb.myinstance.myserver'
Recover an encrypted database backup image into a new database
The client wants to recover an encrypted backup image. In the following example, an encrypted database backup image is recovered into a new encrypted database. The client has been making periodic backup copies of the history, so the USING HISTORY FILE option is used to point to a specific version of the history file.
db2 recover database ccards
  using history file (/home/user/myfiles/)
  encrypt
  cipher aes
  key length 128
  master key label mylabel.mydb.myinstance.myserver
Restore an encrypted backup image from System A on System B
The client wants to restore an encrypted backup image of the CCARDS database on a different system. Because both systems A and B implement the same security requirements, the keystore can be copied from system A to system B.
  1. Generate an encrypted backup image on system A. Because the database is encrypted, its backup images are also encrypted. For example:
    db2 backup database ccards
  2. Use a secure copy protocol (SCP) to copy the keystore and its associated stash file from system A to system B. An SCP is available with most secure shell (SSH) implementations.
  3. Update the value of the keystore_location database manager configuration parameter to point to the copied keystore on system B.
  4. Restore the backup image on system B. Ensure that the target database is also encrypted: Restore the image into a new database and specify the ENCRYPT option on the RESTORE DATABASE command. For example:
    db2 restore database ccards
      encrypt cipher aes key length 192
If systems A and B do not implement the same security requirements, the keystore cannot be copied from system A to system B. In this case, use a new master key for the backup image and securely send that key to the administrator for system B.
  1. Add a new master key to the keystore. For example:
    gsk8capicmd –secretkey –add –db /home/db2/ccardskeystore.p12
      –stashed –label label4Alice
      –file secretkeyfile4Alice;
  2. Generate an encrypted backup on system A. For example:
    db2 backup database ccards
      encrypt encrlib 'db2encr.dll'
      encropts 'Master Key Label=label4Alice'
  3. Send the secret key file to the system B administrator (Alice) by using an encrypted email.
  4. (System B administrator) Add the key to the keystore on system B.
  5. (System B administrator) Restore the backup image on system B. Ensure that the target database is also encrypted by restoring the image into a new database and specify the ENCRYPT option on the RESTORE DATABASE command. For example:
    db2 restore database ccards encropts 'Master Key Label=label4Alice'
      encrypt cipher aes key length 192
Rotate the database master key
It has been almost three months since the CCARDS database was set up, and it is time to rotate the master key for that database. The following example shows how to rotate the master key:
CALL SYSPROC.ADMIN_ROTATE_MASTER_KEY('newlabel');
Encrypt an existing database
The client wants to encrypt an internal database named PDESIGN that contains designs for some key products. The client is concerned about this information leaking out to competitors, particularly after some disk drives went missing recently. Encryption solutions do not generally allow the mixing of encrypted and non-encrypted data in the same containers. The only available option is to use the following backup and restore approach.
  1. Create the keystore. For example:
    gsk8capicmd -keydb -create -db /home/db2/pdesignkeystore.p12
      -pw Str0ngPassw0rd –strong -type pkcs12 –stash;
  2. Configure the DB2 instance with the new keystore. For example:
    db2 update dbm cfg using keystore_type pkcs12
      keystore_location /home/db2/pdesignkeystore.p12
  3. Generate a backup image of the PDESIGN database. For example:
    db2 backup database pdesign
  4. Drop the PDESIGN database. For example:
    db2 drop database pdesign
  5. Restore the backup image into a new encrypted PDESIGN database. For example:
    db2 restore database pdesign encrypt
Encrypt a database in an HADR environment
There is an encrypted standby for the CCARDS database. IPSec was implemented between the primary server and the database so that transaction logs are protected in transit, and file-level synchronization between the primary server's keystore and the standby's keystore was implemented so that whenever a new master key is added to the primary server, it is reflected automatically on the standby. The company was asked to comply with a new mandate that requires upgrading the encryption algorithm and key length for the CCARDS database, and wants to do so without any down time. The administrator performs a failover to the standby database, then generates a backup of the primary database. The administrator then restores the backup image into a new database, specifying encryption options on the RESTORE DATABASE command. After synchronization, the system fails back to the primary database.

What to do next

The encrypted database is ready to use.