Managed Key Encryption

Caché includes support for managed key encryption, a suite of technologies that protects data at rest. These technologies are:

Block-level database encryption, also known simply as database encryption — A set of tools to allow creation and management of databases in which all the data is encrypted. Such databases are managed through the Management Portal.
Data element encryption for applications, also known simply as data element encryption — A programmatic interface so that applications can include code to encrypt and decrypt individual data elements (such as particular class properties) as they are stored to and retrieved from disk.
Encryption key management — A set of tools in the Management Portal for creating and managing data-encryption keys and for managing key files. Both database encryption and data element encryption use key files to support their functionality.

Each Caché 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); the database-encryption keys can be the same keys or other keys as the data-element encryption keys.

When you create a data-encryption key, an encrypted copy of it is stored in a key file and must be decrypted to be used. It is imperative that you store the key file in a secure location where it cannot be damaged in any way. Each key file can hold up to four keys.

Caché uses AES (the Advanced Encryption Standard) to perform its encryption and decryption when Caché 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 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.)

WARNING:

The loss of or damage to all copies of a key file will prevent encrypted data — whether data elements or databases — from being decrypted.

Topics in this chapter include:

Managing Keys and Key Files

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 encryption keys, activating keys, and deactivating keys.

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 key file, each key is available to every administrator in the key file. (In this chapter, the term administrator refers to a key administrator, not a Caché administrator.) 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 key, and Caché requires an administrator username and password to decrypt the key so that the key can be activated.

Topics in this section involve tasks related to key files, keys, and administrators. All tasks are performed in the Management Portal. Some tasks are for managing keys and key files, even if no keys in the key file have been activated on an instance of Caché; other tasks are related to an instance of Caché, activating keys for it, and so on. There are also other miscellaneous tasks.

For managing keys and key files (even if no keys in the key file have been activated on an instance of Caché), tasks are:

Related to an instance of Caché and encryption keys for it, tasks are:

Other miscellaneous tasks are:

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 Caché Database 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, the procedure is:

From the Management Portal home page, go to the Create Encryption Key File page (System Administration > Encryption > Create New Encryption Key File).
On the Create Encryption Key File page, specify the following values:
- Key File — The name of the file where the encryption key is stored; this can be an absolute or relative path name.
  If you enter an absolute file name, the key file is placed in the specified directory on the specified drive; if you enter a relative file name, the key file is placed in the manager’s directory for the Caché instance (which is below the Caché installation directory — that is, in <cache-install-dir>/mgr/). Also, no file suffix is appended to the file name, so that the file MyKey is saved simply with that file name. You can also use the Browse button to the right of this field to choose the directory where Caché will create the key file. (If you provide the name of an existing file, Caché will not overwrite it and the save will fail.)
  
  WARNING:
  
  Any key stored in <cache-install-dir>/Mgr/Temp is deleted when Caché next reboots — never store a key in <cache-install-dir>/Mgr/Temp.
- Administrator Name — The name of an administrator who can activate the key. There must be at least one administrator.
  Because the database encryption functionality exists independent of Caché security, this name need not match any user names that are part of Caché security. By default, the initial administrator name value is the current username. The administrator name cannot include Unicode characters.
- Password — A password for this user.
  Because the database encryption functionality exists independent of Caché security, this password need not match the password that a user has for Caché security. Note that this password is not stored anywhere on disk; it is the responsibility of the administrator to ensure that this information is not lost.
  InterSystems suggests that this password follow the administrator password strength guidelines. If someone can successfully guess a valid password, the password policy is too weak. Also, this password cannot include Unicode characters.
- Confirm Password — The password for this user entered again to confirm its value.
- Cipher Security Level — The length of the key, where choices are 128–bit, 192–bit, and 256–bit.
- Key File Format — Either
  - 1.0 - Single key only — the original data-encryption key format
  - 2.0 - Single or multiple keys — (the default) the current data-encryption key format
  Note:
  
  InterSystems recommends the use of the 2.0 key format.
- Key Description — For keys in 2.0 key format only, text to describe the key that is initially created and stored in the key file. This text appears in the Description column of the Encryption Keys Defined in Key File table.
Click Save at the top of the page to save the key file to disk.
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.
Refer to the section “Protection from Unauthorized Access to Encrypted Data” for details about measures to prevent currently or formerly privileged users from gaining unsanctioned access to encrypted data.

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 “Creating a Key.” 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

To create a key, you can either:

Create a key file. This causes Caché to create a key and place it in the file. To create a key file, see the section “Creating a Key File.”
Add a key to an existing key file, as described in this section.

To add a key to an existing key file, the procedure is:

From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
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.
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.
In the Add a New Encryption Key screen, enter values in the following fields:
- Existing Administrator Name — The name of an administrator associated with the key file. (Administrators associated with the file appear in the Administrators Defined in Key File table on the Manage Encryption Key File page.)
- Existing Administrator Password — This administrator’s password.
- Description — Text to describe the key. This text appears in the Description column of the Encryption Keys Defined in Key File table.
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.)
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.
Refer to the section “Protection from Unauthorized Access to Encrypted Data” for details about measures to prevent currently or formerly privileged users from gaining unsanctioned access to encrypted data.

WARNING:

Deleting a Key from a Key File

To delete a key from a key file, the procedure is:

From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
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 keys in the key file.
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 there is only one key in the file, there is no Delete button, as it is not permitted to delete this key.)
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.
Click OK on the confirmation dialog to delete the key from the file.

Adding an Administrator to a Key File

To add an administrator to an existing key file, the procedure is:

From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
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.
In the table of administrators, click Add to add a new administrator. This displays a page with the following fields:
- Existing Administrator Name — The name of an administrator already in the file.
- Existing Administrator Password — The password associated with the already existing administrator in the file.
- New Administrator Name — The name of the new administrator to be added to the file. Because the encryption functionality is independent of Caché security, the administrator name need not match any user names that are part of Caché security. This user name cannot include Unicode characters
- New Administrator Password — The password for the new administrator. InterSystems suggests that this password follow the administrator password strength guidelines; also, this password cannot include Unicode characters. Because the encryption functionality is independent of Caché security, the password need not match the password that a user has for Caché security.
- Confirm New Administrator Password — Confirmation of the password for the new administrator.
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, the procedure is:

From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).
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).
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.)
Click OK to delete the administrator from the file.

Activating a Database Encryption Key

Caché supports up to four simultaneously activated keys for database encryption. To activate a key for database encryption, the procedure is:

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.
On this page, click Activate Key, which displays the fields for activating a key.
Enter values for the following fields:
- Key File — The name of the file where the encryption key is stored. If you enter an absolute file name, Caché looks for the key file in the specified directory on the specified drive; if you enter a relative file name, Caché looks for the key file starting in the manager’s directory for the Caché instance (which is below the Caché installation directory — that is, in <cache-install-dir>/mgr/). You can also use the Browse button to display a dialog for opening the key file.
- Administrator Name — The name of an administrator for this key, specified either when the key was created or edited.
- Password — The password specified for the named administrator.
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 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:

Set Default — Click to specify that Caché uses this key when creating new encrypted databases. For more details, see the section “Specifying the Default Encryption Key or Journaling Encryption Key for an Instance.”
Set Journal — Click to specify that Caché uses this key to encrypt journal files. For more details, see the section “Specifying the Default Encryption Key or Journaling Encryption Key for an Instance.”
Deactivate — Click to deactivate this key. For more details, see the section “Deactivating a Database Encryption Key”

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. To activate a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.

Deactivating a Database Encryption Key

To deactivate a database encryption key, the procedure is:

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.
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.
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.
Click OK on the confirmation dialog to deactivate the key.

To deactivate the key, each underlying condition requires a different action:

For any encrypted database except CACHETEMP and CACHE, dismount the database on the Databases page (System Operation > Databases). You can then deactivate the key.
For CACHETEMP and CACHE, specify that these databases are not to be encrypted and then restart Caché. To do this, select Configure Startup Settings on the Database Encryption page; either you can choose not to activate a database encryption key at startup (in which case Caché turns off encryption for CACHETEMP and CACHE) or you can choose interactive or unattended database encryption key activation at startup (in which cases the choice whether or not to encrypt CACHETEMP and CACHE becomes available — choose “No”).
For encrypted journal files, ensure that no encrypted journal file is required for recovery. This is described in the section “Encrypted Journal Files and Configuring Startup without Key Activation.”

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, the procedure is:

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.
In the table of encryption keys:
- To specify a new default encryption key, click Set Default for that key. The Set Default button for the current default key is unavailable.
- To specify a new journal encryption key, click Set Journal for that key. The Set Journal button for the current journal encryption key is unavailable.
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.

Activating a Data Element Encryption Key

Caché supports up to four activated keys at one time for data element encryption. To activate a key for data element encryption, the procedure is:

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.
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.
Enter values for the following fields:
- Key File — The name of the file where the encryption key is stored. If you enter an absolute file name, Caché looks for the key file in the specified directory on the specified drive; if you enter a relative file name, Caché looks for the key file starting in the manager’s directory for the Caché instance (which is below the Caché installation directory — that is, in <cache-install-dir>/mgr/).
- Administrator Name — The name of an administrator for this key, specified either when the key was created or edited.
- Password — The password specified for the named administrator.
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 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. To activate a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.

Deactivating a Data Element Encryption Key

To deactivate a data element encryption key, the procedure is:

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.
In the table of activated keys, for the key you wish to deactivate, click Deactivate. This displays a confirmation dialog.
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.

Testing for a Valid Administrator Username-Password Pair

You can test interactively whether or not an administrator username-password pair is valid by attempting to activate a key in Caché. You can:

Use the Management Portal. For more information, see either “Activating a Database Encryption Key” or “Activating a Data Element Encryption Key.”
Use the ^DATABASE utility. For more information, see “^DATABASE” section of the “Using the Character-based Security Management Routines” appendix.
Run the database encryption conversion utility cvencrypt on an unmounted database (either encrypted with the database encryption key or unencrypted), up to the confirmation prompt:
```
Continue? [Y/N]: 
```
At this prompt, answer No. For more information on cvencrypt, see the chapter “Using the cvencrypt Utility.”

Do not perform this process programmatically, since it requires storing the password on disk, which is not recommended. (Unattended key activation at startup is a highly restricted special exception to storing a password on disk, as described in the section “Configuring Startup with Unattended Key Activation.”)

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 Caché 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:

All of the instances share a single key file, which is located on one cluster node or mirror member.
In this case, if you change the single copy of the key file, then these changes are visible to all nodes or members. However, if the host holding the key file becomes unavailable to the other nodes or members, any attempt to read the key from the key file fails; this can prevent Caché instances from restarting properly.
Each cluster node or mirror member has its own copy of the key file.
Here, if you change the key file, then you propagate copies of the key file (containing the same key) to all the other nodes or members. This increases the burden of administering the key file (which is typically small), but ensures that each instance of Caché always has a key available at startup.

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

Create a database-encryption key on one node or member. For more information on this procedure, see the section “Creating a Key File.”
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.
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.

Important:

Refer to the section “Protection from Unauthorized Access to Encrypted Data” for details about measures to prevent currently or formerly privileged users from gaining unsanctioned access to encrypted data.

Using Multiple Key Files

If you choose to use multiple copies of the key file:

Create a database-encryption key on one node or member. For more information on this procedure, see the section “Creating a Key File.”
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.
Make a copy of the key file for each of the remaining nodes or members.
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).

Important:

Recommended Policies for Managing Keys and Key Files

The following sections address important topics for managing encrypted databases:

Protection from Accidental Loss of Access to Encrypted Data

Once you have created and activated a key, you can encrypt data. However, to ensure that such data is always available, it is strongly suggested that you take the following preventative actions:

Create a second copy of a key file (a backup) and place it in a secure location, such as on some removable media that is stored in a fireproof safe.
Create an additional administrator, the name and password of which are written down and stored in a secure location, such as in a fireproof safe at a site that is sufficiently far from where the key is in use.

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.

Protection from Unauthorized Access to Encrypted Data

To read or alter encrypted data, the appropriate encryption key for the Caché instance must be activated. Key activation requires three separate and separable elements: (1) the encrypted database or database containing the encrypted data elements, (2) the key itself, and (3) someone with a knowledge of a username and password for using the key. The design of the data encryption mechanism allows for the separation of these three factors. This separation allows an organization to keep the key in a secure location, separate from the encrypted data and under the control of authorized individuals who cannot use the key. This prevents those individuals with knowledge of how to use the key from doing so in an unauthorized manner — even if they have access to the data.

Put another way, Caché makes it possible to secure encryption keys so that those who have the key cannot use it and those who can use the key do not have it. By this arrangement, the key can only be activated when those who have it make it available to those who can use it.

Caution:

If administrators have free access to a key file, then it is possible for them to make unauthorized copies of the key file. Such copies might be used by formerly authorized members of an organization, could be lost, and so on.

The degree of secure storage required is a function of the sensitivity of the data. Under the strictest circumstances, activation might occur as follows:

A system administrator (who does not have the key but does have the information to use the key) needs to re-start Caché. After or as part of a Caché re-start, the database encryption key needs to be activated, so that encrypted databases or databases containing encrypted data can be mounted.
The system administrator contacts the key holder (who has the key but lacks the information to use it). The key holder may be part of a site’s staff that provides physical security; the key itself may even be stored in a safe or vault.
The key holder retrieves the key, which may be on a CD, USB drive, or other portable storage device. The key holder then brings the key to where it is used for key activation.
The system administrator then performs key activation — under the oversight of the key holder, who ensures that the system administrator performs no other actions, such as copying the key file.
Once the key has been activated, the key holder returns the device holding the key to its physically secure location until it is needed again.

Implementing this arrangement is for the purpose of preventing the system administrator from obtaining the key. Again, this is because possessing the key would enable the administrator to gain potentially unauthorized access to the encrypted data.

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; for any instance that serves as a destination shadow server, enabling journal file encryption also results in the encryption of the journal files that the instance receives from its source production server. Both these features require access to the database encryption key at startup time, as described in the section “Configuring Caché 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:

Activate a database-encryption key.
From the Management Portal home page, go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).
On the Local Databases page, select Create New Database. This displays the Create Database wizard.
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 the cvencrypt utility 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:

Activate the key.
From the Management Portal home page, go to the Databases page (System Operation > Databases).
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:

From the Management Portal home page, go to the Databases page (System Operation > Databases).
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.
Deactivate the key.

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-key the database using the cvencrypt utility. For more information on this process, see the section “Converting an Encrypted Database to Use a New Key” in the “Using the cvencrypt Utility” appendix of this book.

Configuring Caché Database Encryption Startup Settings

By default, an instance of Caché does not have a database encryption key available at startup time. This means that, by default, there are several features that are not available (see below). Caché can either gather the encryption key file information interactively or without human intervention (called “unattended startup”). This section describes how to set up three database-encryption startup options:

The features that depend on having a key available at startup time are:

Encrypting the Caché audit log.
Encrypting the CACHETEMP and CACHE databases. (Either both are encrypted or neither.)
Encrypting Caché journal files and, for a destination shadow server, encrypting the journal files received from the source production server. (Either both are encrypted or neither.)
Having an encrypted database mounted at startup time.

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:

From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).
Select Configure Startup Settings. This displays the area with options for configuring Caché startup and other options for encrypted databases.
In this area, from the Startup Options list, select None.
Click Save. Caché may prevent you from performing this action if:
- Any encrypted databases are required at startup. See “Required Encrypted Databases and Configuring Startup without Key Activation” for more details.
- There are any encrypted journal files with open transactions. See “Encrypted Journal Files and Configuring Startup without Key Activation” for more details.
- The audit log is encrypted. (The error message for this refers to an encrypted database because Caché stores the audit log in a database called CACHEAUDIT.) See “The Caché Audit Log and Configuring Startup without Key Activation” for more details.
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, the procedure is:

Confirm that the database is mounted or mount it. To do this:
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 writeable, so do not select the Read Only check box.)
Edit the database’s properties so that it is not mounted at startup. To do this:
1. Go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).
2. Find the database’s row in the table of databases.
3. Select the database by clicking on its name. This displays the page for editing the database.
4. On this Edit page, clear the Mount Required at Startup check box.
5. 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:

The instance is configured to encrypt its journal files (either as a source production server or as a destination shadow server).
There are open transactions in the journal file (which is fairly likely on a busy system).

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:

On the Database Encryption page (System Administration > Encryption > Database Encryption), change the Encrypt Journal Files setting to “No.” Leave the Key Activation at Startup setting as it is.
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 Caché 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:

Back up the instance’s audit data.
Go to the Database Encryption page (System Administration > Encryption > Database Encryption).
Select Configure Startup Settings, which displays the area with options for configuring Caché startup and other options for encrypted databases.
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:

From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).
Select Configure Startup Settings. This displays the Startup Options area, which includes the Key Activation at Startup list.
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.
The fields in this area are:
- Encrypt CACHETEMP and CACHE Databases — Allows you to specify whether or not the CACHETEMP and CACHE databases are encrypted. To encrypt them, select “Yes”; to have them be unencrypted, select “No.”
- Encrypt Journal Files — Allows you to specify whether or not the instance encrypts its own journal files and, if it is a destination shadow server, if it encrypts the journal files it receives from its source production server. To encrypt journal files, select “Yes”; to have them be unencrypted, select “No.” This choice depends on startup options because Caché startup creates a new journal file; if you choose encryption, startup requires a key.
  
  Note:
  
  This change takes effect the next time that Caché switches journal files. To begin journal file encryption without a restart, switch journal files after completing this page.
- Encrypt Audit Log — Allows you to specify whether or not Caché encrypts the audit log. To encrypt the audit log, select “Yes”; to have it be unencrypted, select “No.” This choice depends on startup options because the Caché startup procedure records various events in the audit log; if you choose encryption, startup requires a key.
  
  Caution:
  
  This change takes effect immediately and deletes any existing audit data. Back up the audit database prior to changing this setting; otherwise, audit data will be lost.
Click Save to save the selected settings.

Important:

If Caché is configured to

Encrypt CACHETEMP and CACHE, journal files, or the audit log
Require an encrypted database at startup

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

Unattended startup requires that all the elements required to decrypt an encrypted database be available when Caché starts running. This includes the Caché instance itself, the encrypted database, the database-encryption key file, and the username and password used for unattended database encryption key activation. 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).

Caution:

InterSystems recommends that you do not use unattended key activation.

If you want Caché to activate a key at startup without requiring any human intervention, then:

You need to have a key currently activated. To activate a key, see the section “Activating a Key.”
From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).
Select Configure Startup Settings. This displays the Startup Options list.
In Startup Options, select Unattended (NOT RECOMMENDED). This changes the fields that the page displays.
The Startup Options area expands to display three fields. Complete these:
- Key File — The path of the database-encryption key file. This can be an absolute or relative path; if you specify a relative path, it is relative to the Caché installation directory. Click Browse to search for the database-encryption key file on the file system.
- Administrator Name — An administrator for this key file.
- Password — The administrator’s password.
Complete the fields in the Optionally Encrypted Data area:
- Encrypt CACHETEMP and CACHE Databases — Allows you to specify whether or not the CACHETEMP and CACHE databases are encrypted. To encrypt them, select “Yes”; to have them be unencrypted, select “No.”
- Encrypt Journal Files — Allows you to specify whether or not the instance encrypts its own journal files and, if it is a destination shadow server, if it encrypts the journal files it receives from its source production server. To encrypt journal files, select “Yes”; to have them be unencrypted, select “No.” This choice depends on startup options because Caché startup creates a new journal file; if you choose encryption, startup requires a key.
  
  Note:
  
  This change takes effect the next time that Caché switches journal files. By default, this occurs the next time that Caché restarts. To begin journal file encryption without a restart, switch journal files after completing this page.
- Encrypt Audit Log — Allows you to specify whether or not Caché encrypts the audit log. To encrypt the audit log, select “Yes”; to have it be unencrypted, select “No.” This choice depends on startup options because the Caché startup procedure records various events in the audit log; if you choose encryption, startup requires a key.
  
  Caution:
  
  This change takes effect immediately and deletes any existing audit data. Back up the audit database prior to changing this setting; otherwise, audit data will be lost.
Click Save to save the selected settings.

When you configure Caché for unattended startup, it adds another administrator to the database-encryption key file; that administrator has a system-generated name and password. Ideally, the key file should be on a medium that can be physically locked in place, such as a lockable CD-ROM or DVD drive in a rack; the data center facility where it is stored should be locked and monitored. Do not store the database-encryption key on the same drive as any databases that it is used to encrypt.

Important:

If Caché is configured to

Encrypt CACHETEMP and CACHE, journal files, or the audit log
Require an encrypted database at startup

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:

CACHE: Can be encrypted in conjunction with the CACHETEMP database. Encrypting CACHE requires that a key be available at startup, since the database is required at startup time.
CACHEAUDIT: Can be encrypted. Encrypting CACHEAUDIT requires that a key be available at startup, since the database is required at startup time.
CACHELIB: Must not be encrypted. (Note that all content in CACHELIB is publicly available.)
CACHESYS: Must not be encrypted. If an instance has an encrypted form of this database, Caché cannot start.
CACHETEMP: Can be encrypted in conjunction with the CACHE database. Encrypting CACHETEMP requires that a key be available at startup, since the database is required at startup time.
DOCBOOK: Can be encrypted. (Note that all content in DOCBOOK is publicly available.)
SAMPLES: Can be encrypted. (Note that all content in SAMPLES is publicly available.)
USER: Can be encrypted.

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.EncryptionOpens in a new tab class.

Data Element Encryption Calls

The system methods available for data element encryption are all methods of the %SYSTEM.EncryptionOpens in a new tab 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:

plaintext — The unencrypted text to be encrypted.
keyID — The GUID of the data-encryption key to be used to encrypt plaintext.
The method returns the encrypted ciphertext.

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 Caché ObjectScript.

For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyEncryptOpens in a new tab 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:

ciphertext — The encrypted text to be decrypted.
The method returns the decrypted plaintext.

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.AESCBCManagedKeyDecryptOpens in a new tab 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:

plaintext — The unencrypted stream to be encrypted.
ciphertext — The variable to receive the encrypted stream.
keyID — The GUID of the data-encryption key to be used to encrypt plaintext.
The method returns a %StatusOpens in a new tab code.

For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyEncryptStreamOpens in a new tab 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:

ciphertext — The encrypted stream to be decrypted.
plaintext — The variable to receive the unencrypted stream.
The method returns a %StatusOpens in a new tab code.

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.AESCBCManagedKeyDecryptStreamOpens in a new tab class reference content.

Support for Re-Keying Data in Real Time

Data element encryption allows Caché applications to support re-keying data, which is 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-keying data. Given merely the handle to ciphertext and an activated key, an application can perform re-keying. For example, data element encryption supports the ability to re-key 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-key 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.

Emergency Situations

This section describes what to do under certain circumstances when you are in danger of losing data. These include:

If the File Containing an Activated Key is Damaged or Missing

In this situation, the following circumstances have occurred:

A database-encryption key has been activated for the Caché instance.
Caché is using encrypted data.
The key file containing the database-encryption key becomes damaged.

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:

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.”
Make a new backup copy of the key file and store it in a safe place. Follow all the precautions specified in the section “Special Cautions to Preserve the Data in Encrypted Databases.”
Set up Caché to use the new copy of the key:
- If you are using interactive startup, incorporate the new copy of the key into your startup procedures.
- If you are using unattended startup, then re-configure your startup options using the new copy of the key file — even if you are setting it up for the same options as before.

If There Is No Backup Copy of the Key File or the Key has No Known Administrator Username and Password

Important:

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:

Do not shut down Caché.
Do not deactivate the currently active key.

WARNING:

Shutting down Caché or deactivating the active key will cause the permanent loss of your data.
Contact the InterSystems Worldwide Response Center. Engineers there can help guide you through the following procedure and answer any questions that may arise.
Prevent all users from making any changes to the database with encrypted content while copying its data to an unencrypted database. To do this, the procedure is:
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.

Copy all data in unencrypted form to another database. The procedure for copying the data is:

In the Terminal, go to the %SYS namespace:
```
REGULARNAMESPACE> zn "%SYS"
```

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

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?

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.

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.
When ^GBLOCKCOPY asks if you wish to copy all globals, enter Yes (can be Yes, Y, y, and so on):
```
All Globals? No => y
```
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.

^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

^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.
^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
```
^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.

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.
If the data is valid, perform steps 3 and 4 of this procedure for each database encrypted with the inaccessible or damaged key.
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.
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:

Create a new database-encryption key according to the procedure described in the section “Creating a Key.”
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.
Create one or more new encrypted databases, using the new key.
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:

Caché is configured for either interactive or unattended startup.
Startup specifies that journal files and/or the CACHETEMP and CACHE databases are encrypted, or an encrypted database is specified as required at startup.
The database-encryption key file is not present.

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:

Shut down Caché. For example, if the instance of Caché is called “MyCache”, the command to do this would be:
```
ccontrol force MyCache
```
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.)
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:

Contact InterSystems Worldwide Response Center. Engineers there can help guide you through the following procedure and answer any questions that may arise.
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.
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é.
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.)
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:

Contact InterSystems Worldwide Response Center (WRC). Engineers there can help guide you through the following procedure and answer any questions that may arise.
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.
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.
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.
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.

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. Nonetheless, database encryption key files should be securely stored separately from the encrypted databases if you want three-factor security (database, key file, password); for details on protecting data in this way, see the section “Protection from Unauthorized Access to Encrypted Data.”

Encryption and Database-Related Caché Facilities

Caché database encryption protects database files themselves. Regarding related facilities in Caché:

Caché online backups are not encrypted. To ensure that the Caché database is encrypted in a backup, it is recommended that you quiesce Caché and then perform a file system backup (as described in the section “External Backup” in the “Backup and Restore” chapter of the Caché Data Integrity Guide).
In the write image journal (WIJ) file, the blocks for encrypted databases are encrypted. (For clustered systems, the same is true for the PIJ file.)
The CACHETEMP and CACHE databases can optionally be encrypted. To provide encryption for CACHETEMP and CACHE, see the section “Configuring Caché Encryption Settings.”
You can optionally encrypt journal files; on a destination shadow server, this switch also encrypts all the journal files that it receives from its source production server. To encrypt journal files, see the section “Configuring Caché Encryption Settings.”