Caché Security Administration Guide
Using the cvencrypt Utility
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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.
  1. 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.
  2. Have an existing database-encryption key for your Caché instance.
  3. If the database is mounted, dismount it. You can do this from the Management Portal Databases page (System Operation > Databases).
  4. 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.
  5. The utility then prompts for what action you wish to take:
    1) Encrypt
    2) Quit
    To encrypt the database, enter “1” and press Enter.
  6. 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
  7. 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.
  8. 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.
  1. 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.
  2. If the database is mounted, dismount it. You can do this from the Management Portal Databases page (System Operation > Databases).
  3. 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.
  4. 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
  5. 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.
  6. The utility then prompts for the username and password of a keyfile administrator:
    Username: dek-admin1
    Password: <characters shielded during entry>
  7. 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.
  8. 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.
  1. 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.
  2. If the database is mounted, dismount it. You can do this from the Management Portal Databases page (System Operation > Databases).
  3. 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).
  4. 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.
  5. 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
  6. 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> 
  7. 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.
  8. 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 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 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.
-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.
-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.