Caché allows you to use encrypted databases, as described in the chapter Managed Key Encryption. There are occasions when you may need to perform encryption management operations on a database, such as:

To perform these operations, Caché supplies cvencrypt, a standalone utility for use with 8-KB format databases. Its available operations are described in the following sections.

Note:

cvencrypt is not for use with journal files that belong to a running system.

Converting an Unencrypted Database to be Encrypted

This describes the procedure for making an unencrypted database encrypted.

Back up the data in the database to be encrypted.

The cvencrypt utility encrypts data in place. This means that it uses on-disk space for its operations (not copying the database elsewhere and restoring it to its current disk location after successful completion). If the utility is interrupted before completion, the database will be partly encrypted and partly unencrypted, rendering it unusable.

Caution:

It is critical that you back up the database before encrypting it. Failure to do so can result in data being lost.

In the directory containing the CACHE.DAT file for the database to encrypt, run the cvencrypt utility, providing a path to it. For example, if your database is in the C:\MyDBs directory and is called test1 and Caché is installed in the C:\InterSystems\MyCache directory, then you would run the utility as follows:

C:\MyDBs\test1>..\..\InterSystems\MyCache\bin\cvencrypt CACHE.DAT

The utility then provides an informational display message about itself, and then information on the database passed to it.

This displays a prompt to activate an already-existing encryption key:

Access database encryption key.
Keyfile:

At this prompt, enter the full path of the key for encrypting the database. For example, suppose that you have stored the database-encryption keyfile, dek1, in the C:\InterSystems\MyCache\Mgr directory.

Keyfile: C:\InterSystems\MyCache\Mgr\dek1

The utility then prompts for the username and password of a keyfile administrator:

Username: dek-admin1
Password: <characters shielded during entry>

When it receives these, the utility then reminds you that it modifies data in place, so that you should be sure that your data is adequately backed up before continuing:

This utility will modify your database in place.
Be sure that your data is adequately backed up before proceeding.
Continue? [Y/N]:

it encrypts the database, stating the key that it is using for encryption:

Using database encryption key (ID = 5DBC532D-4D1F-A3A4-30CDA34BB66B).

During encryption, the utility displays a progress indicator, as well as a reminder not to interrupt the process.

Caution:

If you interrupt the process while it is incomplete, the database may be in a state in which some of its data is encrypted and some of it is unencrypted. It is impossible for Caché to read such a database, and all the data will be lost.

When finished, the utility announces this, such as:

Processed:
118400 blocks (done!)

Converting an Encrypted Database to be Unencrypted

This describes the procedure for making an encrypted database unencrypted.

Back up the database to be unencrypted.

The cvencrypt utility unencrypts data in place. This means that it uses on-disk space for its operations (not copying the database elsewhere and restoring it to its current disk location after successful completion). If the utility is interrupted before completion, the database will be partly encrypted and partly unencrypted, rendering it unusable.

Caution:

It is critical that you back up the database before decrypting it. Failure to do so can result in data being lost.

In the directory containing the CACHE.DAT file for the database to decrypt, run the cvencrypt utility, providing a path to it. For example, if your database is in the C:\MyDBs directory and is called test1 and Caché is installed in the C:\InterSystems\MyCache directory, then you would run the utility as follows:

C:\MyDBs\test1>..\..\InterSystems\MyCache\bin\cvencrypt CACHE.DAT

The utility then provides an informational display message about itself, and then information on the database passed to it.

If the database is encrypted, the utility displays information about this:

If you interrupt the process while it is incomplete, the database may be in a state in which some of its data is encrypted and some of it is unencrypted. It is impossible for Caché to read such a database, and all the data will be lost.

When the process is complete, the progress indicator changes to a completion message:

Processed:
153600 blocks (done!)

Converting an Encrypted Database to Use a New Key

This describes the procedure for re-encrypting an encrypted database using a new key.

Back up the data in the database to be re-encrypted.

The cvencrypt utility re-encrypts data in place, that is, using the on-disk space for its operations (not copying the database elsewhere and restoring it to its current disk location after successfully completing the decryption). If the utility is interrupted before completion, the database will be partly encrypted with two different keys, rendering it unusable.

Caution:

It is critical that you back up the database before decrypting it. Failure to do so can result in data being lost.

In the directory containing the CACHE.DAT file for the database to decrypt, run the cvencrypt utility, providing a path to it. For example, if your database is in the C:\MyDBs directory and is called test1 and Caché is installed in the C:\InterSystems\MyCache directory, then you would run the utility as follows:

C:\MyDBs\test1>..\..\InterSystems\MyCache\bin\cvencrypt CACHE.DAT

When it first starts, the utility displays an information message about itself and the database passed to it.

The utility displays information about the encryption in use for the database:

To re-encrypt the database with a new database-encryption key, enter 2 and press Enter.

To begin the process of re-encrypting the database, you must have access to the key in which the database is currently encrypted. The utility prompts for the absolute path for this keyfile, and, receiving that, the username of an administrator and that administrator's password:

Once this information has been successfully entered, the utility prompts for the absolute path of the keyfile for re-encrypting the database. Receiving that, it prompts for the username of an administrator and that administrator's password:

Once you confirm that you want to perform this process, the utility encrypts the database. During encryption, the utility displays a progress indicator, as well as a reminder not to interrupt the process, such as:

Do not interrupt this process!
Processed:
16000 blocks (10%)

Caution:

If you interrupt the process while it is incomplete, the database may be in a state in which some of its data is encrypted with one key and some of it is encrypted with another. It is impossible for Caché to read such a database, and all the data will be lost.

When the process is complete, the progress indicator changes to a completion message:

Processed:
153600 blocks (done!)

Using Command-line Options with cvencrypt

You can invoke cvencrypt with various command-line options. These allow you to encrypt, decrypt, or re-encrypt one database or multiple databases with a single command; to operate on a single database, use the -dbfile option; to operate on multiple databases with a single command, use the -dbfilelist option. The behavior of the -inkeyfile and -outkeyfile options depends on whether an encrypted or unencrypted database is being processed, and, if an encrypted database is present, if one or both of the options is present. For details, see the description of each option.

The name of a file containing a list of databases to process. argument can be a simple file name, a file name containing a relative path, or a file name containing an absolute path. In the file containing the list of databases, each database is listed as the name of a database file, which can also be a simple file name, a file name containing a relative path, or a file name containing an absolute path; place the name of each database file on its own line without any additional punctuation or delimiting characters.

The input key file, which contains the database key for decrypting any encrypted input to cvencrypt. When processing an unencrypted database, the -inkeyfile option has no effect. When processing an encrypted database, cvencrypt uses the input key file to decrypt the database. If the input key file and the output key file are both present, then, when processing an encrypted database, cvencrypt uses the input key file to decrypt the database and the output key file to re-encrypt it; if input key file and output key file hold the same database encryption key, cvencrypt does not run.

The password to use (along with the -inuser username ) to extract the database encryption key from the input key file. If you do not use the -inpass option with cvencrypt, it prompts you for a password.

Important:

If you use the -inpass option, then this password may be visible to operating system tools as part of the data associated with the cvencrypt process. For example, on certain versions of UNIX®, the ps command displays the value of the -inpass password. If you have any concerns about exposing this information to those who should not have it, do not use the -inpass option; when you invoke cvencrypt, you will be prompted for the password, which will then not appear as part of the data associated with the process.

The administrator name to use (along with the -inpass password) to extract the database encryption key from the input key file. If you do not use the -inuser option with cvencrypt, it prompts you for a username.

The output key file, which contains the database key for encrypting the output from cvencrypt. When processing an unencrypted database, cvencrypt uses the output key file to encrypt it. When processing an encrypted database where there is a value for the -outkeyfile option but no value provided for the -inkeyfile option, cvencrypt does nothing. When processing an encrypted database, if there are values for both the input and output key files, then cvencrypt uses the input key file to decrypt the database and the output key file to re-encrypt it; if the input and output key files hold the same database encryption key, cvencrypt does not run.

The password to use (along with the -outuser administrator name) to extract the database encryption key from the output key file. If you do not use the -outpass option with cvencrypt, it prompts you for a password.

Important:

If you use the -outpass option, then this password may be visible to operating system tools as part of the data associated with the cvencrypt process. For example, on UNIX®, the ps command displays the value of the -outpass password. If you have any concerns about exposing this information to those who should not have it, do not use the -outpass option; when you invoke cvencrypt, you will be prompted for the password, which will then not appear as part of the data associated with the process.

The administrator name to use (along with the -outpass password) to extract the database encryption key from the output key file. If you do not use the -outuser option with cvencrypt, it prompts you for a username.

Using cvencrypt in Batch Mode on OpenVMS

On OpenVMS, you can run cvencrypt as a batch job that is driven by a command procedure.

Important:

When running cvencrypt as a batch job, the username and password of the database encryption administrator is visible as part of the operating system process. To avoid exposing sensitive information, the procedure described here includes creating a temporary database encryption administrator immediately before invoking cvencrypt and removing that administrator from the database encryption key file immediately after invoking cvencrypt (which can even occur while the utility is running).

Run cvencrypt interactively and answer "N" to the final "Continue? {Y/N}:" prompt. This captures the input that you wish to provide to cvencrypt but does not run it. The operating system displays a message such as:

A command procedure "cvencrypt.com" has been created that you can SUBMIT as a batch job.

Issue the OpenVMS SUBMIT command to run the command procedure as a batch job.

Once the job is running, remove the temporary administrator from the key file (using either the Management Portal or ^DATABASE).

InterSystems recommends that you create a new command procedure for each batch job, as the input parameters may differ.

Note:

Batch mode is only available for OpenVMS. It is not supported for UNIX® or Windows.