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

Topics in this chapter include:

Note:
In this chapter, the term administrator refers to a key administrator rather than an administrator for the system as a whole.
About Managed Key Encryption
Caché includes support for managed key encryption, a suite of technologies that protects data at rest. These technologies are:
Keys for encrypting either databases or data elements are known as data-encryption keys and may also be known simply as keys (when the context is clear). Each instance can simultaneously have up to four data-encryption keys activated for database encryption and up to four data-encryption keys activated for data-element encryption; activating a key makes it available for encryption and decryption operations.
For database encryption, keys can be stored in two ways:
For data-element encryption, keys are stored in key files.
Note:
You can simultaneously use a key in a key file for database encryption and data-element encryption.
Caché uses AES (the Advanced Encryption Standard) to perform its encryption and decryption when an instance writes to or reads from disk. For databases, Caché writes and reads in fixed-length blocks, and the entire database is encrypted, except for the single label block; this encrypted content includes the data itself, indices, bitmaps, pointers, allocation maps, and incremental backup maps. For data elements, only the specified data is encrypted, and a unique identifier for the encryption key is included with the encrypted data on disk.
Encryption and decryption have been optimized, and their effects are both deterministic and small for any Caché platform. (This chapter also includes a section that addresses how the Caché database encryption facilities affect functionality related to but separate from databases themselves.)
Key Management Tasks
A key, short for data-encryption key, is a 128–, 196–, or 256–bit bit string that is used with a cryptographic algorithm to reversibly encrypt or decrypt data. Each key has a unique identifier (known as a GUID), which Caché displays as part of key management activities.
Key management is the set of activities associated with creating keys, activating keys, deactivating keys, assigning default keys for various activities, and deleting keys. It also includes management activities associated with key storage. You can store keys in either of two ways:
Key management tasks may be particular to key files or to the use of KMIP, or they may be common. This chapter describes:
Managing Keys in Key Files
A key file is a file that holds encrypted copies of one or more data-encryption keys. Key file management is the set of activities associated with key files themselves, such as adding administrators to or removing administrators from key files. Within a particular key file, all administrators have access to all keys. All keys are stored in an encrypted form, along with administrator information; each data-encryption key is individually encrypted using a master key. For each administrator in the key file, there is a unique, encrypted copy of the master key, which is encrypted using a key-encryption key — where each key-encryption key is derived from an individual key administrator’s password. Encryption tasks require an activated data-encryption key, and Caché requires an administrator username and password to decrypt that key so that it can then be activated.
When working with key files, tasks include:
Note:
If you wish to configure encryption for journal files or the CACHETEMP and CACHE databases, this is part of Caché startup configuration. See the section Configuring Encryption Startup Settings for details.
A Note about Encryption Key File Formats
Beginning in version 2015.1, Caché introduced support for encryption files that hold multiple keys (up to four), which are version 2.0 key files. (The original key file format, version 1.0, holds only a single key.) Version 2.0 key files are the preferred format, and are the default when creating a key file. To convert a version 1.0 key file to version 2.0, use the ^EncryptionKey character-based utility.
Note:
If an instance uses multiple keys at startup time (such as with journal files, the audit database, and other databases), then those keys must all be in a single version 2.0 key file. This allows them all to be available when the instance starts.
Creating a Key File
When you create an encryption key file, it contains one key. To create an encryption key file and its initial key:
  1. From the Management Portal home page, go to the Create Encryption Key File page (System Administration > Encryption > Create New Encryption Key File).
  2. On the Create Encryption Key File page, specify the following values:
  3. Click Save at the top of the page to save the key file to disk.
  4. Having just created a key, follow the instructions in the section Protection from Accidental Loss of Access to Encrypted Data to create and store a backup copy of the newly updated key file.
This creates a key file with a single database encryption key in it and with a single administrator. The page displays ID for the key, which is a string such as 9158980E-AE52-4E12-82FD-AA5A2909D029. The key ID is a unique identifier for the key which Caché displays here and on other pages. It provides a means for you to keep track of the key, regardless of its location. This is important because, once you save the key file, you can move it anywhere you choose; this means that Caché cannot track it by its location.
The key is encrypted using the master encryption key, and there is a single copy of master encryption key, which is encrypted using the administrator’s key-encryption key (KEK). You can add additional keys to the key file according to the instructions in the section Adding a Key to a Key File.” You can add administrators to the key file according to the instructions in the section Adding an Administrator to a Key File.”
Warning:
InterSystems strongly recommends that you create and store a backup copy of the key file. Each time you create a database encryption key, it is a unique key that cannot be re-created. Using the same administrator and password for a new key still results in the creation of a different and unique key. If an unactivated key is lost and cannot be recovered, the encrypted database that it protected will be unreadable and its data will be permanently lost.
Adding a Key to a Key File
When using key files, there are two different ways to create a key:
To add a key to an existing key file:
  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
  2. On the Manage Encryption Key File page, in the Key File field, enter the name of the key file to which you want to add and store the key; click OK. This displays information about that key file; at the bottom of the shaded area, the Encryption Keys Defined in Key File table displays a list of the one to four keys in the key file. If there are three or fewer keys in the file, you can create a new key and add it to the file.
  3. Click the Add button below the Encryption Keys Defined in Key File table to add a key to the key file. This displays the Add a New Encryption Key screen.
  4. In the Add a New Encryption Key screen, enter values in the following fields:
  5. Click OK to save the key to the key file. This displays information about it in the Encryption Keys Defined in Key File table, including its ID, which is a string such as 9158980E-AE52-4E12-82FD-AA5A2909D029. (The key ID is a unique identifier for the key which Caché displays here and on other pages. It provides a means for you to keep track of the key, regardless of its location. This is important because, once you save the key file, you can move it anywhere you choose; this means that Caché cannot track it by its location.)
  6. Having just added a new key to the key file, follow the instructions in the section Protection from Accidental Loss of Access to Encrypted Data to create and store a backup copy of the newly updated key file.
Warning:
InterSystems strongly recommends that you create and store a backup copy of the key file. Each time you create a database encryption key, it is a unique key that cannot be re-created. Using the same administrator and password for a new key still results in the creation of a different and unique key. If an unactivated key is lost and cannot be recovered, the encrypted database that it protected will be unreadable and its data will be permanently lost.
Deleting a Key from a Key File
To delete a key from a key file:
  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
  2. On the Manage Encryption Key File page, in the Key File field, enter the name of the key file from which you want to delete the key; click OK. This displays information about that key file; at the bottom of the shaded area, the Encryption Keys Defined in Key File table displays a list of the one to four keys in the key file. If there are two or more keys in the file, you can delete a key from the file.
  3. In the table of keys, click Delete in the row for a key to delete that key. Clicking Delete displays a confirmation page for the action.
    If the key’s Delete button is not available, this is because the key is the default encryption key or the journal encryption key for the file. To delete the key, first specify that another key is the default encryption key or the journal encryption key for the file by clicking Set Default or Set Journal for the other key.
  4. Click OK on the confirmation dialog to delete the key from the file.
Warning:
Before deleting the only existing copy of a key, it is critical that you are absolutely sure that there is no existing encrypted content that uses it. If there is no copy of the key that is required to decrypt data, the encrypted data that it protected will be unreadable and permanently lost.
Adding an Administrator to a Key File
To add an administrator to an existing key file:
  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
  2. In the Key File field, enter the path and filename of the key file to open and click OK; you can also use the Browse button to look for the key. Once the Portal opens the key file, it displays a table with the administrators listed in the file; administrator names appear in all capital letters, regardless of how they were defined.
  3. In the table of administrators, click Add to add a new administrator. This displays a page with the following fields:
    Complete these fields and click OK. You have now added a new administrator to the key file.
Once you have added the new administrator to the key file, you may wish to copy the key file, making sure that each copy is in a secure location. Further, InterSystems strongly recommends that you create multiple administrators for each key, one of which has the name and password written down and stored in a secure location, such as in a fireproof safe. However, if copies of the key file are made and later on, as an administrative function, a new administrator is added, only the copy of the key file with the new administrator will be up to date.
Note:
When you add a new administrator to a key file, that administrator’s password is permanently associated with the entry for the administrator name created in the file. Once assigned, passwords cannot be changed. If you wish to assign a new password, delete the entry in the key file for that administrator name and then create a new entry with the same name and a new password.
Deleting an Administrator from a Key File
To delete an administrator from a key file:
  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
  2. In the Key File field, enter the path and filename of the key and click OK. This displays a table with the administrators listed in the file (as well as a table of encryption keys in the file).
  3. In the table of administrators, click Delete next to an administrator to remove that administrator for the key. Clicking Delete displays a confirmation page for the action. (If there is only one administrator in the file, there is no Delete button, as it is not permitted to delete this administrator.)
  4. Click OK to delete the administrator from the file.
Activating a Database Encryption Key from a Key File
Caché supports up to four simultaneously activated keys for database encryption. To activate a key from a key file for database encryption:
  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption). If there are already any activated keys, the page displays a table listing these.
  2. On this page, click Activate Key, which displays the fields for activating a key.
  3. Enter values for the following fields:
  4. Click the Activate button.
Caché then attempts to activate all the keys in the specified file. If there are not enough slots to activate all the keys in the file, then Caché opens as many keys as it can.
After key activation, the Database Encryption page displays the table of activated keys. For each key that Caché activates, the page adds the key to table of activated keys and displays the key’s identifier. For each activated key, you can also perform various actions:
Note:
The table of keys does not display any file or path information. This is because, once a key file is created, any sufficiently privileged operating system user can move it; hence, Caché may not have accurate information about the operating system location and can only rely on the accuracy of the GUID for the activated key in memory. When activating a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.
Activating a Data-Element Encryption Key from a Key File
Caché supports up to four activated keys at one time for data-element encryption. To activate a key for data-element encryption:
  1. From the Management Portal home page, go to the Data Element Encryption page (System Administration > Encryption > Data Element Encryption). If there are already any activated keys, the page displays a table listing these.
  2. On the Data Element Encryption page, select Activate Key, which displays the fields for activating a key. If key activation is not available, this is because there are already four activated data element keys.
  3. Enter values for the following fields:
  4. Click the Activate button.
Caché then attempts to activate all the keys in the specified file. If there are not enough slots to activate all the keys in the file, then Caché opens as many keys as it can.
After key activation, the Data Element Encryption page displays the table of activated keys. For each key that Caché activates, the page adds the key to table of activated keys and displays the key’s identifier.
Note:
The table of keys does not display any file or path information. This is because, once the key file is activated, any sufficiently privileged operating system user can move the key; hence, Caché may not have accurate information about the operating system location and can only rely on the accuracy of the GUID for the activated key in memory. When activating a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.
Managing Keys and Key Files with Multiple-Instance Technologies
If you are using encrypted databases or journal files within a Caché cluster, the Caché instances on all nodes in the cluster must share a single database encryption key.
Before enabling journal file encryption for any instance that belongs to a Caché mirror, see Activating Journal Encryption in a Mirror in the “Mirroring” chapter of the High Availability Guide for important information. (There are no mirroring-related requirements in regard to database encryption.)
There are two ways to enable sharing of a single key:
Important:
Whether there are single or multiple key files, the database encryption key itself is the same for all instances.
Using a Single Key File
To use a single key file:
  1. Create a database encryption key on one node or member. For more information on this procedure, see the section Creating a Key File.”
  2. Secure this key according to the instructions in the section Protection from Accidental Loss of Access to Encrypted Data.”
    Caution:
    Failure to take these precautions can result in a situation in which the encrypted databases or journal files are unreadable and permanently lost.
  3. Configure each instance of Caché for unattended startup and provide Caché with the path to the key file. For more information on this procedure, see the section Configuring Startup with Unattended Key Activation.”
Since all the Caché instances use the same key, they are able to read data encrypted by each other. Any changes to the key file are visible to all instances.
Using Multiple Key Files
To use multiple copies of a key file:
  1. Create a database encryption key on one node or member. For more information on this procedure, see the section Creating a Key File.”
  2. Secure this key according to the instructions in the section Protection from Accidental Loss of Access to Encrypted Data.”
    Caution:
    Failure to take these precautions can result in a situation in which the encrypted databases or journal files are unreadable and permanently lost.
  3. Make a copy of the key file for each of the remaining nodes or members.
  4. On each node or member:
    1. Get a copy of the key file and put it in a secure and stable location on that machine.
    2. Configure each instance of Caché for unattended startup. For more information on this procedure, see the section Configuring Startup with Unattended Key Activation.”
Since each copy of the key file contains the same key, all the Caché instances are able to read data encrypted by each other. Since each Caché instance has a key file on its machine, the key file should always be available for a Caché restart. If there are any changes to the key file (such as adding or removing administrators), you must propagate new copies of the key file to each machine and reconfigure each instance of Caché for unattended startup using the new copy of the key file (even if that file is in the same location as the old file).
Managing Keys with the Key Management Interoperability Protocol (KMIP)
InterSystems supports the use of a KMIP server to manage database encryption keys. Using KMIP includes the following tasks:
Note:
KMIP activities are not supported on macOS instances of Caché.
Creating a KMIP Server Configuration
When establishing a connection between Caché and a KMIP server, you create a KMIP server configuration, which defines properties of the KMIP server and represents it within the Caché instance. To create a KMIP server configuration:
  1. Set up the KMIP server according to its vendor’s instructions.
    Caution:
    When configuring a KMIP server, follow all proper backup procedures according to your vendor’s instructions. If you do not have backup copies of your keys, you may lose data permanently.
    Once you have set up the server, you can then set up the KMIP server configuration in Caché:
  2. To set up a KMIP server configuration, you must have:
  3. On the Caché instance that will communicate with the KMIP server, create an SSL/TLS configuration that will represent the instance to the KMIP server:
    1. On the SSL/TLS Configurations page, click the Create New Configuration button, which displays the New SSL/TLS Configuration page.
    2. On the New SSL/TLS Configuration page, set up the SSL/TLS configuration. For the fields listed below, specify or select values as follows
      The values for other fields (Server certificate verification, the This client’s credentials fields, and the Cryptographic settings fields) depend on the requirements of the KMIP server. The values for the This client’s credentials fields depend on the client certificate, client private key, and CA certificate that you have received from the vendor that provides the KMIP server.
      For more information on this creating an SSL/TLS configuration, see the Creating or Editing an SSL/TLS Configuration section of the “Using SSL/TLS with Caché” chapter.
  4. Create the configuration to the KMIP server:
    1. Start the Terminal and log in as a sufficiently privileged user.
    2. At the terminal prompt, go to the %SYS namespace:
      >zn "%SYS"
    3. %SYS>do ^SECURITY
    4. In ^SECURITY, select option 14, KMIP server setup.
    5. In the KMIP server setup choices, select option 1, Create KMIP server.
    6. At the Create KMIP server prompts, specify values for the following:
      • KMIP server to create? — The name of the KMIP server configuration.
      • Description? — A text description.
      • Server host DNS name? — The fully-qualified DNS name or IP address of the KMIP server.
      • TCP port number? — The port number on which the KMIP server accepts connections.
      • OASIS KMIP protocol version? — The number associated with your KMIP server’s supported version of the protocol. This is part of the information that you have received from the vendor that provides the KMIP server.
      • SSL/TLS Configuration name? — The name of the SSL/TLS configuration that you created in the previous step.
        Note:
        This case of the value that you enter here must match that of the SSL/TLS configuration name as defined.
      • Non-blocking I/O? — Whether or not connections to the KMIP server require non-blocking I/O. InterSystems recommends that you select No; the connection then uses blocking I/O.
      • Auto-reconnect? — Whether or not Caché reconnects with the KMIP server if the connection drops. InterSystems recommends that you select No; there is then no attempt to automatically reconnect if the connection drops.
      • I/O timeout, in seconds? — The amount of time, in seconds, before a timeout occurs in the connection to the KMIP server. This is only relevant if the configuration is using blocking I/O.
      • Log KMIP messages? — Whether or not Caché logs messages that it sends to the KMIP server. If messages are logged, Caché stores them in the <install-dir>/mgr/kmipcmd.log file.
      • Debug SSL/TLS? — Whether or not Caché logs SSL/TLS debugging information. If information is logged, Caché stores it in the <install-dir>/mgr/kmipssl.log file.
    7. After the prompts for KMIP server properties, confirm that you wish to create the KMIP server at the Confirm creation of KMIP server prompt.
Note:
InterSystems supports the use of multiple KMIP servers and the use of a single KMIP server that has multiple configurations. The most recently activated configuration is the default.
Editing a KMIP Server Configuration
To modify the values of the properties of an existing KMIP server configuration:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. Run ^SECURITY:
    %SYS>do ^SECURITY
  4. In ^SECURITY, select option 14, KMIP server setup.
  5. In the KMIP server setup choices, select option 2, Edit KMIP server.
  6. At the Edit KMIP server prompt, enter the name of the configuration to edit.
  7. ^SECURITY then presents prompts for the same properties as when creating a KMIP server configuration; it uses the existing values for the configuration’s properties as its defaults. Modify these values as required.
  8. After the prompts for KMIP server properties, confirm any edits to the properties of the KMIP server at the Confirm changes to KMIP server <servername> prompt.
Deleting a KMIP Server Configuration
To delete a KMIP server configuration:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^SECURITY
  4. In ^SECURITY, select option 14, KMIP server setup.
  5. In the KMIP server setup choices, select option 5, Delete KMIP server.
  6. At the KMIP server to delete? prompt, enter the name of the configuration to delete.
  7. Confirm the deletion when prompted.
Listing the KMIP Server Configurations
To list a Caché instance’s KMIP server configurations:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^SECURITY
  4. In ^SECURITY, select option 14, KMIP server setup.
  5. In the KMIP server setup choices, select option 3, List KMIP servers.
^SECURITY then displays a list of any existing configurations to KMIP servers by name, whether or not they are currently in use.
Listing Details about a KMIP Server Configuration
To view details about a particular KMIP server configuration:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^SECURITY
  4. In ^SECURITY, select option 14, KMIP server setup
  5. In the KMIP server setup choices, select option 4, Detailed list KMIP server.
  6. Enter the name of a KMIP server configuration at the Display which KMIP configuration? prompt.
^SECURITY then displays a list of the specified configuration’s properties, along with each one’s value.
Creating a Key on the KMIP Server
To create a data-encryption key on a KMIP server:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. In ^EncryptionKey, select option 5, Manage KMIP server.
  5. When prompted, enter the name of the configuration for the KMIP server on which you wish to create a key.
  6. At the next prompt, where you select the action you wish to take, select option 2, for Create new key on KMIP server.
  7. At the next prompt, select a key length.
The ^EncryptionKey routine then creates the key and displays its key ID. Newly created keys are not activated by default; to activate the key, see the Activating a Database Encryption Key from a KMIP Server section.
Important:
InterSystems recommends that you record the key ID, so that you have this information available for future reference.
Deleting a Key on the KMIP Server
To create an encryption key on a KMIP server:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. In ^EncryptionKey, select option 5, Manage KMIP server.
  5. When prompted, enter the name of the configuration for the KMIP server on which you wish to delete the key.
  6. At the next prompt, where you select the action you wish to take, select option 3, for Destroy existing key on KMIP server.
  7. The routine then lists the keys on the KMIP server and prompts for the key to delete. Specify a key at the Select key prompt.
    Warning:
    Before deleting the only existing copy of a key, it is critical that you are absolutely sure that there is no existing encrypted content that uses it. If there is no copy the key required to decrypt data, the encrypted data that it protected will be unreadable and will be permanently lost.
  8. When prompted, confirm that you wish to delete the key.
The routine then deletes the key from the KMIP server.
Listing the Keys on the KMIP Server
To list the encryption keys on a KMIP server:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. In ^EncryptionKey, select option 5, Manage KMIP server.
  5. When prompted, enter the name of the configuration of the KMIP server for which you wish to list the key(s).
  6. At the next prompt, select option 1, for List keys on KMIP server.
The routine then displays a list of all the keys on the KMIP server.
Activating a Database Encryption Key from a KMIP Server
To activate a database encryption key from a KMIP server:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. In ^EncryptionKey, select option 3, Database encryption.
  5. In the Database encryption choices, select option 1, Activate database encryption keys.
  6. In the Activate database encryption keys choices, select option 2, Use KMIP server.
    Note:
    If this prompt does not appear, it is because the instance does not have any KMIP server configurations; see Creating a KMIP Server Configuration for instructions on this process.
  7. When prompted, enter the name of the configuration of the KMIP server from which you wish to activate the key.
  8. The routine then lists the keys on the KMIP server and prompts for which key to activate. Specify a key at the Select key prompt.
The routine then activates the key, displaying its ID.
For each key that Caché activates, the Database Encryption page (System Administration > Encryption > Database Encryption) adds the key to table of activated keys and displays the key’s identifier.
Note:
The table of keys does not display any file or path information. When activating a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.
Activating a Data-Element Encryption Key from a KMIP Server
Caché supports up to four activated keys at one time for data-element encryption. To activate a key for data-element encryption from a KMIP server:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. In the Activate data element encryption key choices, select option 2, Use KMIP server.
    Note:
    If this prompt does not appear, it is because the instance does not have any KMIP server configurations; see Creating a KMIP Server Configuration for instructions on this process.
  5. At the KMIP server prompt, enter the name of the configuration of the KMIP server from which you wish to activate the key.
  6. The routine then lists the keys on the KMIP server and prompts for which key to activate. Specify a key at the Select key prompt.
The routine then activates the key, displaying its ID.
For each key that Caché activates, the Data Element Encryption page (System Administration > Encryption > Data Element Encryption) adds the key to table of activated keys and displays the key’s identifier.
Note:
The table of keys does not display any file or path information. When activating a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.
Copying a Key from a KMIP Server to a Key File
You can copy a database encryption key from a KMIP server to a key file. This allows you to make keys available both for backup and for recovery from a network or KMIP service outage. You can:
Important:
Always store encryption key files on removable devices that are kept in securely locked storage.
Creating a Key File with a Copy of a Key from a KMIP Server
To create a key file and copy a key from a KMIP server to it:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. At the prompts that follow, specify:
  5. At the next prompt, select option 2, Copy key from KMIP server. ^EncryptionKey then prompts for the key to copy to the file.
  6. At the Select key prompt, specify the number of the key to copy.
^EncryptionKey then creates the file with the administrator username and password that you specified, and places the selected key in that file.
Adding a Copy of a Key from a KMIP Server to an Existing Key File
To add a key from a KMIP server to an existing key file:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. At the Encryption key file prompt, enter the path and name of the key file to which you are adding a key. The path is relative to the <install-dir>/mgr/ directory.
  5. At the next prompt, select option 5, Add encryption key. At the prompts that follow:
    1. Under Existing administrator, enter the Username and Password of an administrator for the key file.
    2. Enter a description of the key that you are adding to the key file.
  6. At the next prompt, select option 2, Copy key from KMIP server. At the prompts that follow:
    1. At the KMIP server prompt, enter the name of the KMIP server from which you are copying the key.
    2. At the Select key prompt, specify the number of the key to copy.
^EncryptionKey then adds the selected key to selected key file.
Storage-Independent Key Management Tasks
Some tasks are the same for keys in files and keys on a KMIP server:
Deactivating a Database Encryption Key
To deactivate a database encryption key:
  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption). If a key is currently activated, its identifier appears in the table of keys.
  2. You cannot deactivate a key if it is the default key either for new encrypted databases or for encrypting journal files. If you wish to deactivate a key that is Caché is using for either of these activities, then you must select a different key to be used for them. Do this by clicking Set Default or Set Journal for another key. Once the key is not in use for either of these activities, its Deactivate button will be available.
  3. To deactivate the key, click Deactivate in its row.
    Note:
    If it is not possible to deactivate the key for some other reason, the Portal displays an error message. Caché does not allow you deactivate a key under the following circumstances:
    • The CACHETEMP and CACHE databases are encrypted.
    • There is a currently-mounted encrypted database (other than CACHETEMP and CACHE) that is encrypted with this key.
    • The key is currently in use to encrypt journal files. (Note that if you change the journal file encryption key, until you switch the journal file, Caché continues to use the old key for encryption.)
    See below for information about how to address the underlying condition.
  4. Click OK on the confirmation dialog to deactivate the key.
To deactivate the key, each underlying condition requires a different action:
Deactivating a Data-Element Encryption Key
To deactivate a data-element encryption key:
  1. From the Management Portal home page, go to the Data Element Encryption page (System Administration > Encryption > Data Element Encryption) page. If there are any activated keys, the page displays a table listing them.
  2. In the table of activated keys, for the key you wish to deactivate, click Deactivate. This displays a confirmation dialog.
  3. In the confirmation dialog, click OK.
When the Data Element Encryption page appears again, the row in the table for the deactivated key should no longer be present.
Specifying the Default Database Encryption Key or Journal Encryption Key for an Instance
Each instance has a default database encryption key and a default journal encryption key. The instance sets the initial value for each of these when an administrator first activates a database encryption key; the key that is initially the default depends on the key(s) that are in the activated key file. These values are preserved across Caché shutdowns and restarts.
To specify a new key for either of these purposes:
  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption. This displays a table of currently activated encryption keys for the instance.
  2. In the table of encryption keys:
  3. When prompted to confirm your action, click OK.
Caché then sets the selected key as the default or journal encryption key. If a key is either the default or journal encryption key, then it cannot be deleted (since it is required for operations on the Caché instance). Hence, specifying either of these for a key makes the key’s Delete button unavailable.
Using Encrypted Databases
To protect entire databases that contain sensitive information, Caché supports block-level database encryption (or, for short, database encryption). Database encryption is technology that allows you to create and manage databases that, as entire entities, are encrypted; it employs the Caché key management tools to support its activities.
When you create a database, you can choose to have it be encrypted; this option is available if there is a currently activated key. Once you have created an encrypted database, you can use it in the same way as you would use an unencrypted database. The encryption technology is transparent and has a small and deterministic performance effect.
The database encryption functionality also supports the ability to encrypt the audit log and journal files. Both these features require access to the database encryption key at startup time, as described in the section Configuring Encryption Startup Settings.”
Management tasks for encrypted databases include:
Creating an Encrypted Database
When creating a new database, you can specify that it is encrypted. However, before you can create an encrypted database, Caché must have an activated database encryption key. Hence, the procedure is:
  1. From the Management Portal home page, go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).
  2. On the Local Databases page, select Create New Database. This displays the Create Database wizard.
  3. On the second page of the wizard, in the Encrypt Database? box, select Yes. This causes Caché to create an encrypted database. On all the other pages of the wizard, choose database characteristics as you would when creating any database. (For more information on creating databases, see the Create Local Databases section of the “Configuring Caché” chapter of the Caché System Administration Guide.)
Note:
Caché also provides encryption management tools to encrypt unencrypted databases or decrypt encrypted databases, if this is necessary.
Establishing Access to an Encrypted Database
To perform various operations, such as adding a database to a mirror, the database must be mounted. However, for an encrypted database to be mounted, its key must be activated. Hence, access to the database requires activating the key and mounting the database, and the procedure for this is:
  1. From the Management Portal home page, go to the Databases page (System Operation > Databases).
  2. On this page, for the database that you wish to mount, select the Mount button in the far right column of its row in the table of databases. After selecting OK on the confirmation screen, the database is mounted. If the key is not activated, Caché cannot mount the database and displays an error message.
You can now access the data within the database.
Closing the Connection to an Encrypted Database
To close the connection to an encrypted database, the procedure is:
  1. From the Management Portal home page, go to the Databases page (System Operation > Databases).
  2. On this page, select the Dismount button on the right in the table of databases. After selecting OK on the confirmation screen, the database is dismounted.
Because the activated key is used for each read and write to the database, you cannot deactivate the key without first dismounting the database. If you attempt to deactivate the key prior to dismounting the database, Caché displays an error message.
Moving an Encrypted Database Between Instances
If your organization has multiple Caché instances, you may need to use an encrypted database on one instance that was created on another instance using a different key. To move the data from one instance to another, back up and then re-encrypt the database using the available encryption management tools. For more information on these tools, see the Performing Encryption Management Operations appendix of this book.
Configuring Encryption Startup Settings
This section describes how to set up each of the three database encryption startup options:
Caché has several features that require having a key available at startup time (either interactively or through unattended startup):
Configuring Startup without Key Activation
This is the default behavior for an instance of Caché prior to having any keys activated. If you have set up key activation at startup and choose to turn it off, the procedure is:
  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).
  2. Select Configure Startup Settings. This displays the area with options for configuring Caché startup and other options for encrypted databases.
  3. In this area, from the Startup Options list, select None.
  4. Click Save. Caché may prevent you from performing this action if:
    Address the issue that is preventing the change and then perform this procedure again. Once any issues are corrected, you will be able to successfully change to having startup without key activation.
Required Encrypted Databases and Configuring Startup without Key Activation
If the instance has encrypted databases that are required at startup and you attempt to configure startup not to involve key activation, the Management Portal displays an error message stating this and indicating that the key activation option cannot be changed. (If the error message refers to the CACHEAUDIT database, this is because the audit log is encrypted.)
To configure Caché to start without activating an encryption key, any encrypted databases can only be mounted after startup. To configure a database to be mounted after startup:
  1. Confirm that the database is mounted or mount it:
    1. From the Management Portal home page, go to the Databases page (System Operation > Databases).
    2. Find the database’s row in the table of databases. If it is mounted, there is a Dismount choice in its row; if it is not mounted, there is no Dismount choice and there is a Mount choice.
    3. If it is not mounted, select Mount
    4. On the confirmation screen, select OK. (The database needs to be writable, so do not select the Read Only check box.)
  2. Edit the database’s properties so that it is not mounted at startup:
    1. Find the database’s row in the table of databases.
    2. Select the database by clicking on its name. This displays the page for editing the database.
    3. On this Edit page, clear the Mount Required at Startup check box.
    4. Click Save.
The database will no longer be mounted at startup. This means that it will no longer require key activation at startup (though it may be required for other reasons.)
Encrypted Journal Files and Configuring Startup without Key Activation
If the instance uses journaling and you attempt to configure startup not to involve key activation, you may be unable to turn off key activation at startup. These conditions are:
If this occurs, you need to suspend the use of encrypted journal files before you change the startup key activation settings. To do this, the procedure is:
  1. Switch journal files. To do this, click Switch Journal on the Journals page (System Operation > Journals).
Once all open transactions within the encrypted journal files have either been committed or rolled back, you can then change the Caché startup configuration.
Caution:
Even after there are no open transactions, you may need the encrypted journal files to restore a database. For this reason, it is very important that you maintain copies of the key file containing the key used to encrypt these files.
For more information on journal files generally, see the Journaling chapter of the Caché Data Integrity Guide.
The Audit Log and Configuring Startup without Key Activation
If the instance has an encrypted audit log and you attempt to configure startup not to involve key activation, Caché displays an error message that an encrypted database is required at startup, such as:
ERROR #1217: Can not disable database encryption key activation at startup. 
Encrypted databases are required at startup: 
C:\InterSystems\Cache\Mgr\CacheAudit\
The error message refers to encrypted databases because the audit log is stored in the Caché database CACHEAUDIT.
The audit log cannot be encrypted if Caché starts without activating an encryption key. To configure startup not to involve key activation, you must change the Caché setting to specify that the instance uses an unencrypted audit log. The procedure is:
  1. Back up the instance’s audit data.
  2. Select Configure Startup Settings, which displays the area with options for configuring Caché startup and other options for encrypted databases.
  3. Under Optionally Encrypted Data, in the Encrypt Audit Log list, click No.
Changing this setting causes Caché to erase any existing audit data, to start using unencrypted auditing immediately, and to write an AuditChange event to the audit log.
Caution:
If you have not backed up audit data, changing the encryption setting for the audit log results in the loss of that existing audit data.
Configuring Startup with Interactive Key Activation
This is the default behavior for an instance of Caché if a key has been activated. With interactive key activation, the Caché instance prompts for the location of a key and its associated information during its startup.
Important:
On Windows, interactive key activation is incompatible with configuring Caché as a service that starts automatically as part of system startup.
To configure Caché for interactive key activation:
  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).
  2. Select Configure Startup Settings. This displays the Startup Options area, which includes the Key Activation at Startup list.
  3. In the Key Activation at Startup list, select Interactive. If the previous value for the field was None, then this displays the page’s Optionally Encrypted Data area.
  4. The fields in this area are:
  5. Click Save to save the selected settings.
Important:
If Caché is configured to
then failure to activate the required encryption key causes a Caché startup failure. If this occurs, use Caché emergency startup mode to configure Caché not to require any encrypted facilities at startup.
Configuring Startup with Unattended Key Activation
Startup with unattended key activation, also known as unattended startup, activates a key and potentially mounts encrypted databases at startup time without any human intervention. Successful unattended startup requires that the instance have access to:
This section includes the following topics:
Caution:
By making all these items available, the security of the data in Caché becomes entirely dependent on the physical security of the machine(s) holding these elements. If your site cannot ensure this physical security, your data will then be subject to the same level of risk as if it were not encrypted; to avoid this situation, either use interactive startup (which prevents the simultaneous exposure of these elements) or ensure the physical security of the relevant machine(s).
Configuring Unattended Startup Using a Key on a KMIP Server
To configure a Caché instance for unattended startup using a key on a KMIP server:
  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.
  2. At the terminal prompt, go to the %SYS namespace:
    >zn "%SYS"
  3. %SYS>do ^EncryptionKey
  4. In ^EncryptionKey, select option 3, Database encryption.
  5. At the next prompt, select option 4, Configure startup options.
  6. At the next prompt, select option 4, Unattended key activation with a KMIP server.
  7. At the KMIP server instance name prompt, enter the name of a KMIP server configuration.
  8. At the prompts that follow, specify what items to encrypt (all of which require an activated key at startup time):
  9. The routine then displays the current list of KMIP keys to activate at startup, and then prompts for the next action:
  10. When the list contains the desired list of KMIP keys to activate at startup, select option 3, which saves the list.
Configuring Unattended Startup Using a Key in a Key File
Caution:
When you configure Caché for unattended startup, the instance adds another administrator to the database encryption key file; that administrator has a system-generated name and password. Once Caché has modified the key file to add this username and password, InterSystems strongly recommends that you place any copies of the key file only on hardware that can be physically locked in place, such as a lockable CD-ROM or DVD drive in a rack. Further, you should lock and monitor the data center facility where this hardware is stored. Do not store the database encryption key on the same drive as any databases that it is used to encrypt.
To configure a Caché instance for unattended startup with a key in a key file:
  1. You need to have a key currently activated. To activate a key, see the section Activating a Key.”
  2. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).
  3. Select Configure Startup Settings. This displays the Startup Options list.
  4. In Startup Options, select Unattended (NOT RECOMMENDED). This changes the fields that the page displays.
  5. The Startup Options area expands to display three fields. Complete these:
  6. Complete the fields in the Optionally Encrypted Data area:
  7. Click Save to save the selected settings.
Temporarily Addressing Issues with Unattended Startup
If Caché is configured to
then failure to activate the encryption key causes a Caché startup failure. If this occurs, use Caché emergency startup mode to configure Caché not to require any encrypted facilities at startup.
About Encrypting the Databases that Ship with Caché
Each instance of Caché ships with a number of databases. The ability to encrypt and the value of encryption depends on the database:
Using Data-Element Encryption
Data-element encryption provides a means of encrypting application data at a finer level of granularity than the database as a whole; it is for sensitive data elements whose exposure must be prevented. For example, customer records can exclusively encrypt the credit card field; patient records can exclusively encrypt fields that display test results (such as for HIV testing); or a record that includes a social security number can exclusively encrypt that field.
Data-element encryption is available programmatically (via an API), rather than through the Management Portal. Because it is accessible through an API, you can use it in your application code. You have the option of using data-element encryption with database encryption (though there is no requirement to use both).
For an application to use data-element encryption, the required keys must be available when the application is running. To make a key available, activate it; for details, either see the following section Programmatically Managing Keys or, if using the Portal, see Activating a Key for Data-Element Encryption. When a key is activated, Caché displays its unique identifier in the table of activated keys; the application then uses this identifier to refer to the key so that it can be loaded from memory for encryption operations. Since there can be up to four keys simultaneously activated, data-element encryption provides the infrastructure for tasks that require multiple keys.
When encrypting data for data-element encryption, Caché stores the encryption key’s unique identifier with the resulting ciphertext. The unique identifier enables the system to identify the key at decryption time using only the ciphertext itself.
This section describes:
Programmatically Managing Keys
Since data-element encryption is available through an API, there are also a set of calls for managing keys:
These are all methods of the %SYSTEM.Encryption class.
Data-Element Encryption Calls
The system methods available for data-element encryption are all methods of the %SYSTEM.Encryption class and are:
These method names all begin with “AESCBCManagedKey” because the methods use AES (the Advanced Encryption Standard) in cipher block chaining (CBC) mode and are part of the suite of tools for managed key encryption.
Important:
The AESCBC methods that do not include “ManagedKey” in their names are older methods and cannot be used for these purposes.
$SYSTEM.Encryption.AESCBCManagedKeyEncrypt
The signature of this method as it is usually called is:
$SYSTEM.Encryption.AESCBCManagedKeyEncrypt
        (
        plaintext As %String, 
        keyID As %String, 
        ) 
    As %String
where:
If the method fails, it throws either the <FUNCTION> or <ILLEGAL VALUE> error. Place calls to this method in a Try-Catch loop; for more information on Try-Catch, see the section The TRY-CATCH Mechanism in the “Error Processing” chapter of Using ObjectScript.
For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyEncrypt class reference content.
$SYSTEM.Encryption.AESCBCManagedKeyDecrypt
The signature of this method as it is usually called is:
$SYSTEM.Encryption.AESCBCManagedKeyDecrypt
        (
        ciphertext As %String
        ) 
    As %String
where:
If the method fails, it throws either the <FUNCTION> or <ILLEGAL VALUE> error. Place calls to this method in a Try-Catch loop; for more information on Try-Catch, see the section The TRY-CATCH Mechanism in the “Error Processing” chapter of Using ObjectScript.
You do not need to include the key ID with this call, as the key ID is associated with the ciphertext to be decrypted.
For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyDecrypt class reference content.
$SYSTEM.Encryption.AESCBCManagedKeyEncryptStream
The signature of this method as it is usually called is:
$SYSTEM.Encryption.AESCBCManagedKeyEncryptStream
        (
        plaintext As %Stream.Object, 
        ciphertext As %Stream.Object, 
        keyID As %String, 
        ) 
    As %Status
where:
For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyEncryptStream class reference content.
$SYSTEM.Encryption.AESCBCManagedKeyDecryptStream
The signature of this method as it is usually called is:
$SYSTEM.Encryption.AESCBCManagedKeyDecryptStream
        (
        ciphertext As %Stream.Object, 
        plaintext As %Stream.Object
        ) 
    As %Status
where:
You do not need to include the key ID with this call, as the key ID is associated with the ciphertext to be decrypted.
For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyDecryptStream class reference content.
Support for Re-Encrypting Data in Real Time
Data-element encryption allows Caché applications to support re-encrypting an encrypted data element with a new key.
Because an encrypted data element has its encrypting key identifier stored with it, this simplifies the process of re-encrypting data. Given merely the handle to ciphertext and an activated key, an application can perform re-encryption. For example, data-element encryption supports the ability to re-encrypt sensitive data without any downtime; this is particularly useful for users required to perform this action for legal reasons, such as those fulfilling PCI DSS (Payment Card Industry Data Security Standard) requirements.
If you need to re-encrypt data, create a new key and specify to your application that this is the new encryption key. You can then perform an action such as running a background application to decrypt the elements and encrypt them with the new key. This uses the specified key for encryption and always uses the correct key for decryption, since it is stored with the encrypted data.
Protecting against Data Loss and Handling Emergency Situations
Protection from Accidental Loss of Access to Encrypted Data
To ensure that encrypted data is always available, InterSystems strongly suggests that you take the following preventative actions:
Caution:
Failure to take these precautions can result in a situation where the encrypted data will be permanently inaccessible — there will be no way to read it.
Handling Emergency Situations When Using Key Files
This section describes what to do under certain circumstances when you are in danger of losing data. These situations include:
If the File Containing an Activated Key is Damaged or Missing
In this situation, the following circumstances have occurred:
If There Is a Backup Copy of the Key File with a Known Administrator Username and Password
Caution:
This procedure is for an emergency situation, where encrypted data in Caché databases is in danger of being lost.
If the file containing an activated key becomes inaccessible or damaged, immediately perform the following procedure:
  1. Get the backup copy of the key file. This is the copy that you stored as described in the section Protection from Accidental Loss of Access to Encrypted Data.”
  2. Make a new backup copy of the key file and store it in a safe place.
  3. Set up Caché to use the new copy of the key:
If There Is No Backup Copy of the Key File or the Key has No Known Administrator Username and Password
Warning:
THIS PROCEDURE IS FOR AN EMERGENCY SITUATION, WHERE ENCRYPTED DATA IN CACHÉ DATABASES IS IN DANGER OF BEING LOST.
If the file containing the activated key becomes inaccessible or damaged while Caché is running, immediately perform the following procedure for each database encrypted with that key:
  1. Warning:
    Shutting down Caché or deactivating the active key will cause the permanent loss of your data.
  2. Contact the InterSystems Worldwide Response Center. Engineers there can help guide you through the following procedure and answer any questions that may arise.
  3. Dismount the database. This prevents all users from making any changes to the database with encrypted content while copying its data to an unencrypted database:
    1. From the Management Portal home page, go to the Databases page (System Operation > Databases).
    2. On the Databases page, if the encrypted database is mounted, select the Dismount option in the next-to-last column in that database’s row. Then select OK in the confirmation dialog.
    3. When the Databases page appears again, select the Mount option in the last column in the database’s row.
    4. On the Mount database confirmation screen, check the Read Only box and select OK.
    It is critical that no one makes any changes to the database during this procedure. Mounting the database read-only prevents any user from changing any data.
  4. Copy all data in unencrypted form to another database. The procedure for copying the data is:
    1. In the Terminal, go to the %SYS namespace:
      REGULARNAMESPACE> zn "%SYS"
    2. From that namespace, run the ^GBLOCKCOPY command:
      %SYS>d ^GBLOCKCOPY
      
      This routine will do a fast global copy from a database to another database or
      to a namespace. If a namespace is the destination, the global will follow any
      mappings set up for the namespace.
       
      1) Interactive copy
      2) Batch copy
      3) Exit
       
      Option?1
    3. At the ^GBLOCKCOPY prompt, specify 1, for an interactive copy:
      Option? 1
       
      1) Copy from Database to Database
      2) Copy from Database to Namespace
      3) Exit
       
      Option?
    4. When ^GBLOCKCOPY prompts for a copy type, select 1, for copying from database to database
      Option? 1
      Source Directory for Copy (? for List)?
      Here, either specify the name of the encrypted database or enter ? to see a numbered list of databases, which includes the encrypted database. If you enter ?, ^GBLOCKCOPY displays a list such as this one:
      Source Directory for Copy (? for List)? ?
       
      1) C:\InterSystems\MyCache\mgr\
      2) C:\InterSystems\MyCache\mgr\cache\
      3) C:\InterSystems\MyCache\mgr\cacheaudit\
      4) C:\InterSystems\MyCache\mgr\cachelib\
      5) C:\InterSystems\MyCache\mgr\cachetemp\
      6) C:\InterSystems\MyCache\mgr\docbook\
      7) C:\InterSystems\MyCache\mgr\encrypted1\
      8) C:\InterSystems\MyCache\mgr\encrypted2\
      9) C:\InterSystems\MyCache\mgr\samples\
      10) C:\InterSystems\MyCache\mgr\unencrypted\
      11) C:\InterSystems\MyCache\mgr\user\
       
      Source Directory for Copy (? for List)?
      Enter the number of the encrypted database, such as 7 here.
    5. When ^GBLOCKCOPY prompts for a destination directory for copying the data, enter the name of an unencrypted database or ? for a list similar to the one for the source directory.
    6. When ^GBLOCKCOPY asks if you wish to copy all globals, enter Yes (can be Yes, Y, y, and so on):
      All Globals? No => y
    7. If there is an empty global in the database, ^GBLOCKCOPY will now ask if you wish to copy it. This will appear something like the following:
      All Globals? No => y
       
      ^oddBIND     contains no data
      Include it anyway? No =>
      Enter No (can be No, N, n, and so on), which is the default.
    8. ^GBLOCKCOPY then asks if you wish to skip all the other empty globals. Enter Yes (can be Yes, Y, y, and so on), which is the default:
      Exclude any other similar globals without asking again? Yes =>
      There then appears a list of all the empty globals that are not being copied:
      Exclude any other similar globals without asking again? Yes => Yes
      ^oddCOM      contains no data --  not included
      ^oddDEP      contains no data --  not included
      ^oddEXT      contains no data --  not included
      ^oddEXTR     contains no data --  not included
      ^oddMAP      contains no data --  not included
      ^oddPKG      contains no data --  not included
      ^oddPROC     contains no data --  not included
      ^oddPROJECT  contains no data --  not included
      ^oddSQL      contains no data --  not included
      ^oddStudioDocument contains no data --  not included
      ^oddStudioMenu contains no data --  not included
      ^oddTSQL     contains no data --  not included
      ^oddXML      contains no data --  not included
      ^rBACKUP     contains no data --  not included
      ^rINC        contains no data --  not included
      ^rINCSAVE    contains no data --  not included
      ^rINDEXEXT   contains no data --  not included
      ^rINDEXSQL   contains no data --  not included
      ^rMACSAVE    contains no data --  not included
      9 items selected from
      29 available globals
    9. ^GBLOCKCOPY then asks if you wish to disable journaling for this operation:
      Turn journaling off for this copy? Yes =>
      Enter Yes (can be Yes, Y, y, and so on), which is the default.
    10. ^GBLOCKCOPY then asks if to confirm that you wish to copy the data:
      Confirm copy? Yes =>
      Enter Yes (can be Yes, Y, y, and so on), which is the default. Depending on the size of the database and the speed of the processor, you may see the status of the copy as it progresses. When it completes, ^GBLOCKCOPY displays a message such as:
      Copy of data has completed
    11. ^GBLOCKCOPY then asks if you wish to save statistics associated with the copy. Enter No (can be No, N, n, and so on), which is the default:
      Do you want to save statistics for later review? No =>
      Control then returns to the main prompt.
  5. Test that the copied data is valid. You can do this by examining the classes, tables, or globals in the Management Portal’s System Explorer for the database into which ^GBLOCKCOPY has copied the data.
  6. If the data is valid, perform steps 3 and 4 of this procedure for each database encrypted with the inaccessible or damaged key.
  7. Once you have made copies of every encrypted database into an unencrypted database, make a second copy of each database, preferably to a different machine than that which holds the first copy of each.
  8. Now — and only now — you can dismount all encrypted databases and deactivate the active key (that is, the key for which the key file is missing or damaged). Caché requires that you dismount all encrypted databases prior to deactivating their key.
You now have your data in one or more unencrypted databases and there is no activated key.
To re-encrypt the formerly encrypted databases, the procedure is:
  1. Create a new database encryption key according to the procedure described in the section Creating a Key.”
  2. Create a new backup copy of the key file as described in Protection from Accidental Loss of Access to Encrypted Data.”
    Caution:
    Make sure you take the precautions described in Protection from Accidental Loss of Access to Encrypted Data; failure to follow these procedures can result in the permanent loss of data.
  3. Create one or more new encrypted databases, using the new key.
  4. Import the data exported in the previous procedure into the new encrypted database(s).
Your data is now stored in encrypted databases for which you have a valid key and a backup copy of the key file containing that key.
If the Database Encryption Key File Is Required at Startup and Is Not Present
Under certain conditions related to the required use of a database encryption key file at startup, the system starts in single-user mode. These conditions are:
If You Can Make the Key File Available
This situation may have been caused simply by the appropriate key file not being present at Caché startup time — such as if the media holding it is not currently available.
To correct the condition, after Caché starts running in single-user mode, then the procedure is:
  1. Shut down Caché. For example, if the instance of Caché is called “MyCache”, the command to do this would be:
    ccontrol force MyCache
  2. If you know the location where Caché is expecting to find the database encryption key file, then place the key file there. (Otherwise, you need to run ^STURECOV as specified in the next section.)
  3. Start Caché again.
Caché should start in its typical mode (multi-user mode) and operate as expected.
If a Backup Key File Is Available
If the appropriate key file is not present at Caché startup time and is not available, you may have a backup key file available. If so, then to correct the condition, after Caché starts running in single-user mode, then the procedure is:
  1. Contact InterSystems Worldwide Response Center. Engineers there can help guide you through the following procedure and answer any questions that may arise.
  2. Start a Terminal session according to the instructions in the most recent entry in the cconsole.log file. Typically, this specifies starting a Terminal session with the -B flag.
    For example, at a Windows command line, for an instance of Caché called “MyCache” that is installed in the default location, the command would be:
    C:\MyCache\bin\cache -sC:\MyCache\mgr -B
    This connects you with Caché in the operating system terminal window; the prompt in that window changes from the operating system prompt to the Caché %SYS prompt.
  3. If you have or can obtain a copy of the database encryption key file (such as a backup), then place a copy of the key file in a location accessible to Caché.
  4. Run the ^STURECOV (startup recovery) routine at the Terminal prompt. In that routine, activate the encryption key using an administrator username and password in that file. (You do not need to exit ^STURECOV when you have completed this process.)
  5. When you are satisfied that Caché is ready for use, use ^STURECOV to complete the startup procedure. Caché then starts in multi-user mode.
Caché should now operate as expected.
If No Key File Is Available
If you do not have any copy of the database encryption key file, then the procedure is:
  1. Contact InterSystems Worldwide Response Center (WRC). Engineers there can help guide you through the following procedure and answer any questions that may arise.
  2. Start a Terminal session with the -B flag. For example, at a Windows command line, for an instance of Caché called “MyCache” that is installed in the default location, the command would be:
    C:\MyCache\bin\cache -sC:\MyCache\mgr -B
    This connects you with Caché in the operating system terminal window; the prompt in that window changes from the operating system prompt to the Caché %SYS prompt.
  3. If any encrypted databases require mounting at startup, disable this feature for them:
    1. From the Management Portal Home page, go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).
    2. Click the name of the database in the table of databases. This displays the Edit: page for the database.
    3. On the Edit: page, clear the Mount Required at Startup check box.
    4. Click Save.
  4. Run the ^STURECOV routine at the Terminal prompt. In that routine, configure Caché database startup options not to require a database encryption key. This means that the CACHETEMP and CACHE databases as well as journal files should now operate as expected; it also means that any encrypted databases cannot be mounted.
  5. When you are satisfied that Caché is ready for use, use ^STURECOV to complete the startup procedure. Caché then starts in multi-user mode.
As you perform this procedure, you may need to perform other actions, according to the instructions of the representative from the WRC. Follow these instructions.
Caution:
If you have not performed the actions described in the section Protection from Accidental Loss of Access to Encrypted Data,” then your data may no longer be available in any form. This is a very serious problem, but if you do not have a key, there is no way to retrieve the lost data.
Handling Emergency Situations When Using a KMIP Server
This section describes what to do under certain circumstances when you are using a KMIP server and are in danger of losing data. These situations include:
If the KMIP Server Holding an Activated Key is Damaged or Missing
In this situation, the following circumstances have occurred:
If There Is a Backup Copy of the Key on the KMIP Server
If KMIP server holding an activated key becomes inaccessible or damaged, immediately perform restore procedures for the KMIP server according to your vendor’s instructions.
If There Is No Backup Copy of the Key on the KMIP Server
Warning:
THIS PROCEDURE IS FOR AN EMERGENCY SITUATION, WHERE ENCRYPTED DATA IN Caché DATABASES IS IN DANGER OF BEING LOST.
If there is no way to restore the KMIP server holding the activated key from backup, immediately perform the following procedure for each database encrypted with that key:
  1. Warning:
    Shutting down Caché or deactivating the active key will cause the permanent loss of your data.
  2. Contact the InterSystems Worldwide Response Center. Engineers there can help guide you through the following procedure and answer any questions that may arise.
  3. Dismount the database. This prevents all users from making any changes to the database with encrypted content while copying its data to an unencrypted database:
    1. From the Management Portal home page, go to the Databases page (System Operation > Databases).
    2. On the Databases page, if the encrypted database is mounted, select the Dismount option in the next-to-last column in that database’s row. Then select OK in the confirmation dialog.
    3. When the Databases page appears again, select the Mount option in the last column in the database’s row.
    4. On the Mount database confirmation screen, check the Read Only box and select OK.
    It is critical that no one makes any changes to the database during this procedure. Mounting the database read-only prevents any user from changing any data.
  4. Copy all data in unencrypted form to another database. The procedure for copying the data is:
    1. In the Terminal, go to the %SYS namespace:
      REGULARNAMESPACE>zn "%SYS"
    2. From that namespace, run the ^GBLOCKCOPY command:
      %SYS>do ^GBLOCKCOPY
      
      This routine will do a fast global copy from a database to another database or
      to a namespace. If a namespace is the destination, the global will follow any
      mappings set up for the namespace.
       
      1) Interactive copy
      2) Batch copy
      3) Exit
       
      Option?1
    3. At the ^GBLOCKCOPY prompt, specify 1, for an interactive copy:
      Option? 1
       
      1) Copy from Database to Database
      2) Copy from Database to Namespace
      3) Exit
       
      Option?
    4. When ^GBLOCKCOPY prompts for a copy type, select 1, for copying from database to database
      Option? 1
      Source Directory for Copy (? for List)?
      Here, either specify the name of the encrypted database or enter ? to see a numbered list of databases, which includes the encrypted database. If you enter ?, ^GBLOCKCOPY displays a list such as this one:
      Source Directory for Copy (? for List)? ?
       
      1) C:\InterSystems\MyCache\mgr\
      2) C:\InterSystems\MyCache\mgr\cache\
      3) C:\InterSystems\MyCache\mgr\cacheaudit\
      4) C:\InterSystems\MyCache\mgr\cachelib\
      5) C:\InterSystems\MyCache\mgr\cachetemp\
      6) C:\InterSystems\MyCache\mgr\docbook\
      7) C:\InterSystems\MyCache\mgr\encrypted1\
      8) C:\InterSystems\MyCache\mgr\encrypted2\
      9) C:\InterSystems\MyCache\mgr\samples\
      10) C:\InterSystems\MyCache\mgr\unencrypted\
      11) C:\InterSystems\MyCache\mgr\user\
      
       
      Source Directory for Copy (? for List)?
      Enter the number of the encrypted database, such as 7 here.
    5. When ^GBLOCKCOPY prompts for a destination directory for copying the data, enter the name of an unencrypted database or ? for a list similar to the one for the source directory.
    6. When ^GBLOCKCOPY asks if you wish to copy all globals, enter Yes (can be Yes, Y, y, and so on):
      All Globals? No => y
    7. If there is an empty global in the database, ^GBLOCKCOPY will now ask if you wish to copy it. This will appear something like the following:
      All Globals? No => y
       
      ^oddBIND     contains no data
      Include it anyway? No =>
      Enter No (can be No, N, n, and so on), which is the default.
    8. ^GBLOCKCOPY then asks if you wish to skip all the other empty globals. Enter Yes (can be Yes, Y, y, and so on), which is the default:
      Exclude any other similar globals without asking again? Yes =>
      There then appears a list of all the empty globals that are not being copied:
      Exclude any other similar globals without asking again? Yes => Yes
      ^oddCOM      contains no data --  not included
      ^oddDEP      contains no data --  not included
      ^oddEXT      contains no data --  not included
      ^oddEXTR     contains no data --  not included
      ^oddMAP      contains no data --  not included
      ^oddPKG      contains no data --  not included
      ^oddPROC     contains no data --  not included
      ^oddPROJECT  contains no data --  not included
      ^oddSQL      contains no data --  not included
      ^oddStudioDocument contains no data --  not included
      ^oddStudioMenu contains no data --  not included
      ^oddTSQL     contains no data --  not included
      ^oddXML      contains no data --  not included
      ^rBACKUP     contains no data --  not included
      ^rINC        contains no data --  not included
      ^rINCSAVE    contains no data --  not included
      ^rINDEXEXT   contains no data --  not included
      ^rINDEXSQL   contains no data --  not included
      ^rMACSAVE    contains no data --  not included
      9 items selected from
      29 available globals
    9. ^GBLOCKCOPY then asks if you wish to disable journaling for this operation:
      Turn journaling off for this copy? Yes =>
      Enter Yes (can be Yes, Y, y, and so on), which is the default.
    10. ^GBLOCKCOPY then asks if to confirm that you wish to copy the data:
      Confirm copy? Yes =>
      Enter Yes (can be Yes, Y, y, and so on), which is the default. Depending on the size of the database and the speed of the processor, you may see the status of the copy as it progresses. When it completes, ^GBLOCKCOPY displays a message such as:
      Copy of data has completed
    11. ^GBLOCKCOPY then asks if you wish to save statistics associated with the copy. Enter No (can be No, N, n, and so on), which is the default:
      Do you want to save statistics for later review? No =>
      Control then returns to the main prompt.
  5. Test that the copied data is valid. You can do this by examining the classes, tables, or globals in the Management Portal’s System Explorer for the database into which ^GBLOCKCOPY has copied the data.
  6. If the data is valid, perform steps 3 and 4 of this procedure for each database encrypted with the inaccessible or damaged key.
  7. Once you have made copies of every encrypted database into an unencrypted database, make a second copy of each database, preferably to a different machine than that which holds the first copy of each.
  8. Now — and only now — you can dismount all encrypted databases and deactivate the active key (that is, the key for which the key file is missing or damaged). Caché requires that you dismount all encrypted databases prior to deactivating their key.
You now have your data in one or more unencrypted databases and there is no activated key.
To re-encrypt the formerly encrypted databases, the procedure is:
  1. Create a new database encryption key according to the procedure described in the section Creating a Key on the KMIP Server.”
  2. Create a new backup copy of the key file as described in Protection from Accidental Loss of Access to Encrypted Data.”
    Caution:
    Make sure you take the precautions described in Protection from Accidental Loss of Access to Encrypted Data; failure to follow these procedures can result in the permanent loss of data.
  3. Create one or more new encrypted databases, using the new key.
  4. Import the data exported in the previous procedure into the new encrypted database(s).
Your data is now stored in encrypted databases for which you have a valid key and a backup copy of the key file containing that key.
If the KMIP Server Is Required at Startup and Is Not Accessible
Under certain conditions related to the required use of one or more database encryption keys at startup, the system starts in single-user mode. These conditions are:
If the Connection to the KMIP Server is Briefly Unavailable
The simplest solution to this case is when there has been a problem such as a network outage or the KMIP server is otherwise temporarily not running; in these cases, address networking or server problem and, if required, restart Caché.
If the KMIP Server Suffers a Longer-Term Outage
If it is not possible to connect to the KMIP server longer-term:
  1. Contact InterSystems Worldwide Response Center (WRC). Engineers there can help guide you through the following procedure and answer any questions that may arise.
  2. Start a Terminal session with the -B flag. For example, at a Windows command line, for an instance of Caché called MyInstance that is installed in the default location, the command would be:
    C:\MyInstance\bin\cache -sC:\MyInstance\mgr -B
    This connects you with Caché in the operating system terminal window; the prompt in that window changes from the operating system prompt to the Caché %SYS prompt.
  3. If any encrypted databases require mounting at startup, disable this feature for them:
    1. From the Management Portal Home page, go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).
    2. Click the name of the database in the table of databases. This displays the Edit: page for the database.
    3. On the Edit: page, clear the Mount Required at Startup check box.
    4. Click Save.
  4. Run the ^STURECOV routine at the Terminal prompt. In that routine, configure Caché database startup options not to require a database encryption key. This means that the CACHETEMP and CACHE databases as well as journal files should now operate as expected; it also means that any encrypted databases cannot be mounted.
  5. When you are satisfied that Caché is ready for use, use ^STURECOV to complete the startup procedure. Caché then starts in multi-user mode.
As you perform this procedure, you may must perform other actions, according to the instructions of the representative from the WRC. Follow these instructions.
Caution:
If you have not performed the actions described in the section Protection from Accidental Loss of Access to Encrypted Data,” then your data may no longer be available in any form. This is a very serious problem, but, if you do not have a key, there is no way to retrieve the lost data.
Other Information
This section addresses:
Key File Encryption Information
Database encryption administrator names are stored in the clear in the key file. Database encryption administrator passwords are not stored; when entered, they are used, along with other data, to derive key-encryption keys. If someone can successfully guess a valid password, the password policy is too weak. Key-encryption keys are derived using the PBKDF2 algorithm with 512 bits of salt and 65,536 iterations, making dictionary and brute force attacks impractical.
Encryption and Database-Related Caché Facilities
Caché database encryption protects database files themselves. Regarding related facilities in Caché: