Application-managed encryption

Edit online

With application-managed encryption, the application provides the key password to the API (using key DSM_ENCRYPT_USER) and it is the application's responsibility to manage the key password.

Attention: If the encryption key is not saved, and you forgot the key, your data is unrecoverable.

The application provides the key password in the dsmInitEx call and must provide the proper key password at restore time.

Attention: If the key password is lost, there is no way to restore the data.

The same key password must be used for backup and restore (or archive and retrieve) operations for the same object. This method does not have a dependency on the IBM® Storage Protect server level. To set up this method, the application needs to follow these steps:

  1. Set the bEncryptKeyEnabled variable to bTrue in the call to dsmInitEx, and set the encryptionPasswordP variable to point to a string with the encrypt key password.
  2. Set the include.encrypt for the objects to encrypt. For example, to encrypt all data, set: 
      include.encrypt /.../* (UNIX)
    and 
      include.encrypt *\...\* (Windows)

    To encrypt the object /FS1/DB2/FULL, set:

      include.encrypt /FS1/DB2/FULL
  3. Set ENCRYPTKEY=PROMPT|SAVE in the option string that is passed to the API in the dsmInitEx call on Windows. This option can also be set in dsm.opt (Windows) or dsm.sys (UNIX or Linux®).

By default, the encryptkey option is set to prompt. This setting ensures that the key does not get stored automatically. If encryptkey save is specified, the key is stored by IBM Storage Protect on the local machine but then only one key can be valid for all IBM Storage Protect operations with the same node name.

After a send of an object, the dsmEndSendObjEx specifies whether an object was encrypted and which method was used. Possible values in the encryptionType field:

  • DSM_ENCRYPT_NO
  • DSM_ENCRYPT_USER
  • DSM_ENCRYPT_CLIENTENCRKEY

The following table lists the API encryption types, prerequisites, and the functions that are available.

Table 1. API encryption types, prerequisites, and functions available
Type Prerequisite Function available
ENCRYPTIONTYPE None Set the ENCRYPTIONTYPE in the option string that is passed to the API in the dsmInitEx call on Windows. ENCRYPTIONTYPE=AES128 by default.
EncryptKey=save None API and backup-archive
EncryptKey=prompt None API and backup-archive
EncryptKey=generate None API and backup-archive
EnableClientEncryptKey None API only
Note: It is advised that the server has authentication turned ON. If authentication is turned OFF, the key is not encrypted, but the data is still encrypted. However, this is not recommended.
Table 2 shows how both Authorized Users and non-Authorized Users can encrypt or decrypt data during a backup or restore operation, depending on the value that is specified for the passwordaccess option. To perform the following authorized-user and non-authorized-user operations, the TSM.KDB, TSM.sth, and TSM.IDX files must exist. The authorized user sets the encryptkey option to save and the passwordaccess option to generate.
Table 2. Encrypting or decrypting data with application managed key on UNIX or Linux
Operation passwordaccess option encryptkey option Result
Authorized user backup generate save Data encrypted.
generate prompt Data encrypted if encryptionPasswordP contains an encryption password.
prompt save Data encrypted if encryptionPasswordP contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP contains an encryption password.
Authorized user restore generate save Data encrypted.
generate prompt Data encrypted if encryptionPasswordP contains an encryption password.
prompt save Data encrypted if encryptionPasswordP contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP contains an encryption password.
Non-authorized user backup generate save Data encrypted.
generate prompt Data encrypted if encryptionPasswordP contains an encryption password.
prompt save Data encrypted if encryptionPasswordP contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP contains an encryption password.
Non-authorized user restore generate save Data encrypted.
generate prompt Data encrypted if encryptionPasswordP contains an encryption password.
prompt save data encrypted if encryptionPasswordP contains an encryption password.
prompt prompt Data encrypted if encryptionPasswordP contains an encryption password.