Caché Security Administration Guide
Performing Encryption Management Operations
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter describes how to perform encryption management operations. Its topics include:

About Encryption Management Operations
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é provides a set of encryption management tools for performing such actions. Alternatively, you can perform these actions using a standalone utility, called cvencrypt. InterSystems recommends using its encryption management tools:
Note:
Neither the encryption management tools nor cvencrypt are for use with journal files that belong to a running system.
Using the Encryption Management Tools
Important:
When the encryption management tools perform a conversion on a mounted database, that database is dismounted and then remounted. Plan accordingly, so that this does not cause any problems.
Converting an Unencrypted Database to be Encrypted
To convert an unencrypted database to an encrypted database:
  1. Back up the data in the database to be encrypted.
    Caché 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 converting it. Failure to do so can result in data being lost.
  2. Activate the key with which you wish to encrypt the database, either from a key file or a KMIP server.
  3. Start the Terminal.
  4. In the %SYS namespace, run the ^EncryptionKey utility.
  5. In ^EncryptionKey, select option 3, Database encryption.
  6. In the database encryption submenu, select option 7, Modify encrypted status of existing database.
  7. In the Database directories submenu, select the database that you wish to modify; databases are listed by their directories. When you select a database, the routine announces if the database is encrypted or not.
  8. If the database is unencrypted, the routine allows you to encrypt it; at the Encrypt database? prompt, enter yes or y. This is not case sensitive.
  9. At the Select key for encryption prompt, select the key that the routine will use to encrypt the database. If the database is currently mounted, the routine then displays this information.
  10. If the database is currently mounted, the routine states this. At the Dismount database prompt, enter yes or y. This is not case sensitive.
    Important:
    Because dismounting and then remounting a database interrupts its operations, take the appropriate precautions to ensure that this does cause problems.
The routine then encrypts the database. As part of this process, if the database was mounted, the routine displays messages that it has dismounted and mounted the database. When the database is mounted again, encryption is complete.
Converting an Encrypted Database to be Unencrypted
To convert an encrypted database to an unencrypted database:
  1. Back up the data in the database to be unencrypted.
    Caché 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 converting it. Failure to do so can result in data being lost.
  2. Activate the key with which you wish to encrypt the database, either from a key file or a KMIP server.
  3. Start the Terminal.
  4. In the %SYS namespace, run the ^EncryptionKey utility.
  5. In ^EncryptionKey, select option 3, Database encryption.
  6. In the database encryption submenu, select option 7, Modify encrypted status of existing database.
  7. In the Database directories submenu, select the database that you wish to modify; databases are listed by their directories. When you select a database, the routine announces if the database is encrypted or not. If the database is encrypted and its encryption key has not been activated, the routine announces this as well.
  8. If the database is encrypted, the routine allows you to decrypt it; at the Decrypt database? prompt, enter yes or y. This is not case sensitive.
  9. After reporting the encryption key for the database, the routine prompts if you wish to encrypt the database with a different key. Press Enter to simply convert it to a decrypted database and use a new key to encrypt it.
  10. If the database is currently mounted, the routine states this. At the Dismount database prompt, enter yes or y. This is not case sensitive.
    Important:
    Because dismounting and then remounting a database interrupts its operations, take the appropriate precautions to ensure that this does cause problems.
The routine then decrypts the database. As part of this process, if the database was mounted, the routine displays messages that it has dismounted and mounted the database. When the database is mounted again, decryption is complete.
Converting an Encrypted Database to Use a New Key
To convert an encrypted database to use a new key:
  1. Back up the data in the database to be re-encrypted.
    Caché 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 converting it. Failure to do so can result in data being lost.
  2. Activate the keys with which the database is encrypted and with which you wish to re-encrypt the database, either from a key file or a KMIP server.
  3. Start the Terminal.
  4. In the %SYS namespace, run the ^EncryptionKey utility.
  5. In ^EncryptionKey, select option 3, Database encryption.
  6. In the database encryption submenu, select option 7, Modify encrypted status of existing database.
  7. In the Database directories submenu, select the database that you wish to modify; databases are listed by their directories. When you select a database, the routine announces if the database is encrypted or not.
  8. If the database is encrypted, the routine allows you to decrypt it; at the Decrypt database? prompt, enter yes or y. This is not case sensitive.
  9. At the next prompt, which is the Re-encrypt database? prompt, enter yes or y. This is not case sensitive.
  10. At the Select key for encryption prompt, select the key that the routine will use to encrypt the database.
  11. If the database is currently mounted, the routine states this. At the Dismount database prompt, enter yes or y. This is not case sensitive.
    Important:
    Because dismounting and then remounting a database interrupts its operations, take the appropriate precautions to ensure that this does cause problems.
The routine then re-encrypts the database. As part of this process, if the database was mounted, the routine displays messages that it has dismounted and mounted the database. When the database is mounted again, encryption is complete.
Using the Standalone cvencrypt Utility
To perform database conversion activities, Caché also supports a standalone utility, cvencrypt, which supports:
Note:
Regarding cvencrypt:
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 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.