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.
- 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.
- 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.
- 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.
- 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:
- Create a keystore.
- Add a database master key to the keystore (or have the CREATE
DATABASE command automatically create a master key).
- Configure the DB2 instance
with the new keystore.
- If the password is not stashed, open the keystore
by using the db2start command with
the OPEN KEYSTORE option.
- Specify encryption parameters on the CREATE DATABASE command.
- 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.
- 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
- Encrypting data "in place" is not supported. To encrypt an
existing database, create a database backup image and then restore
that image into a new database with encryption enabled.
Procedure
To encrypt a new database by using only default settings:
- 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:
- 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.
- Create the keystore. For example:
gsk8capicmd -keydb -create -db /home/db2/ccardskeystore.p12
-pw Str0ngPassw0rd –strong -type pkcs12 –stash;
- Configure the DB2 instance
with the new keystore. For example:
db2 update dbm cfg using keystore_type pkcs12
keystore_location /home/db2/ccardskeystore.p12
- 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.
- 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.
- 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
- 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.
- Update the value of the keystore_location database
manager configuration parameter to point to the copied keystore on
system B.
- 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.- Add a new master key to the keystore. For example:
gsk8capicmd –secretkey –add –db /home/db2/ccardskeystore.p12
–stashed –label label4Alice
–file secretkeyfile4Alice;
- Generate an encrypted backup on system A. For example:
db2 backup database ccards
encrypt encrlib 'db2encr.dll'
encropts 'Master Key Label=label4Alice'
- Send the secret key file to the system B administrator (Alice)
by using an encrypted email.
- (System B administrator) Add the key to the keystore on system
B.
- (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.
- Create the keystore. For example:
gsk8capicmd -keydb -create -db /home/db2/pdesignkeystore.p12
-pw Str0ngPassw0rd –strong -type pkcs12 –stash;
- Configure the DB2 instance
with the new keystore. For example:
db2 update dbm cfg using keystore_type pkcs12
keystore_location /home/db2/pdesignkeystore.p12
- Generate a backup image of the PDESIGN database. For example:
db2 backup database pdesign
- Drop the PDESIGN database. For example:
db2 drop database pdesign
- 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.
- To check the encryption status of a particular database, use the
ADMIN_GET_ENCRYPTION_INFO table function, which returns the current
encryption settings for a database. For example:
SELECT * FROM TABLE (SYSPROC.ADMIN_GET_ENCRYPTION_INFO());
Backup strategy for your keystore: Your keystore contains master keys. If these master keys
are lost, your data cannot be recovered. It is critical that you implement
a process for backing up your keystore regularly. At a minimum, your
keystore must be backed up whenever you add a new master key. A new
master key is added whenever you perform the following tasks:
- Create an encrypted database without specifying the MASTER
KEY LABEL option on the CREATE DATABASE command.
- Restore to a new database by using the ENCRYPT option
but without specifying the MASTER KEY LABEL option
on the RESTORE DATABASE command or the RECOVER
DATABASE command.
- Rotate the database master key without specifying an explicit
master key label in the ADMIN_ROTATE_MASTER_KEY procedure.
- Add an encryption key to the keystore explicitly by using the gsk8capicmd GSKit
command.
When you stash the password that is protecting your keystore,
the password is obfuscated and stored in a stash file next to the
keystore. However, if you choose not to stash that password, you must
manage it properly. If you lose the password, the keystore cannot
be opened, master keys cannot be retrieved, and the encrypted data
becomes inaccessible.
- Use only GSKit interfaces to manipulate the keystore.
- If you cannot remember what master key label was used to protect
a backup image, run the RESTORE DATABASE command
with the SHOW MASTER KEY DETAILS encryption option.
The command returns the label for each master key that was used to
protect the backup image, as well as the path to the keystore and
the server name and server IP address where the master key was located
at the time that the backup was taken. This information is available
in the db2dump directory in a file whose name
has the following format:
db-name.inst-type.inst-name.
db-partition.timestamp.masterKeyDetails
Support considerations when using DB2 native encryption: When DB2 native
encryption is available for your database, both transaction logs and
any dump files are encrypted. Sometimes IBM Support
requests your transaction logs or your dump files to help service
a DB2 problem. If your database
is encrypted, IBM Support provides
you with tools and instructions to prepare the requested data for
analysis by IBM Support.