Application-managed encryption

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® Tivoli® Storage Manager server level. To set up this method, the application needs to follow these steps:

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.
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
```
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 Tivoli Storage Manager on the local machine but then only one key can be valid for all Tivoli Storage Manager 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. The TSM.PWD file must exist to perform the following authorized-user and non-authorized-user operations. The authorized user creates the TSM.PWD file and 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.