Using the cvencrypt Utility

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.
Have an existing database-encryption key for your Caché instance.
If the database is mounted, dismount it. You can do this from the Management Portal Databases page (System Operation > Databases).
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.
The utility then prompts for what action you wish to take:
```
1) Encrypt
2) Quit
```
To encrypt the database, enter “1” and press Enter.
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]:
```
If you wish to continue, enter “Y”.
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.
If the database is mounted, dismount it. You can do this from the Management Portal Databases page (System Operation > Databases).
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:

Database is encrypted
(Key ID = E1D00BC2-07F4-4495-9562-394B26A2B05B).

It then prompts for an action:

1) Decrypt
2) Re-encrypt with a different key
3) Quit

To decrypt the database, enter “1” and press Enter. This displays a prompt to activate the database’s encryption key:
```
Access original database encryption key
(key ID = E1D00BC2-07F4-4495-9562-394B26A2B05B)
Keyfile:
```
Enter the keyfile including its full path, such as C:\encdb\dek; relative pathnames are not valid.
The utility then prompts for the username and password of a keyfile administrator:
```
Username: dek-admin1
Password: <characters shielded during entry>
```
The utility next states that it is ready to perform the decryption:
```
Prepared to decrypt database
(key ID = E1D00BC2-07F4-4495-9562-394B26A2B05B).
```
Before decrypting the data, the utility 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]:
```
If you wish to continue, enter “Y”. Once you confirm your decision, the utility decrypts the database.
During decryption, the utility displays a progress indicator, as well as a reminder not to interrupt the process, such as:
```
Decrypting database
(key ID = E1D00BC2-07F4-4495-9562-394B26A2B05B).
Do not interrupt this process!
Processed:
25000 blocks (16%)
```
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 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.
If the database is mounted, dismount it. You can do this from the Management Portal Databases page (System Operation > Databases).
Make sure that the key with which the database is being re-encrypted already exists. You can create this key using the Management Portal Database Encryption page (System Administration > Encryption > Database Encryption).
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:

Database is encrypted
(Key ID = E1D00BC2-07F4-4495-9562-394B26A2B05B).

It then prompts for an action:

1) Decrypt
2) Re-encrypt with a different key
3) Quit

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:
```
Access original database encryption key.
(key ID = E1D00BC2-07F4-4495-9562-394B26A2B05B)
Keyfile: C:\encdb\dek1
Username: dek-admin1
Password: <characters shielded during entry> 
```
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:
```
Access new database encryption key.
Keyfile (full path): C:\encdb\dek2
Username: dek-admin2
Password: <characters shielded during entry> 
```
When it receives information on this second key, the utility reminds you that it modifies data in place, so that you should be sure that your data is adequately backed up before continuing.
If you wish to continue, enter “Y”.
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 or more databases or journal files with a single command. You must specify one of the following options: -dbfile, -dbfilelist, -jrnfile, or -jrnfilelist.

Note:

You can also specify the path of a journal or database file as the only argument to cvencrypt, which directs the program to decrypt or encrypt the file in interactive mode. In this situation, cvencrypt determines whether it is operating on a journal file or database file. It provides a confirmation prompt before modifying the file.

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 available command-line options are:

-dbfile argument

The database file to encrypt, decrypt, or re-encrypt. argument can be a simple file name, a file name containing a relative path, or a file name containing an absolute path.

-dbfilelist argument

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, each entry is 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.

-inkeyfile argument

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.

-inpass argument

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.

-jrnfile argument

The journal file to encrypt, decrypt, or re-encrypt. argument can be a simple file name, a file name containing a relative path, or a file name containing an absolute path.

The output journal file preserves the endianness of the input file, which may differ from the native endianness.

-jrnfilelist argument

The name of a file containing a list of journal files 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, each entry is the name of a journal 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 journal file on its own line without any additional punctuation or delimiting characters.

The output journal files preserve the endianness of the input files, which may differ from the native endianness.

-inuser argument

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.

-outkeyfile argument

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.

-outpass argument

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.

-outuser argument

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.