docs.intersystems.com
Home / Security Administration Guide / Managed Key Encryption

Security Administration Guide
Managed Key Encryption
Previous section           Next section
 InterSystems: The power behind what matters   
Search:  

InterSystems IRIS™ includes support for managed key encryption, a suite of technologies that protects data at rest. These technologies are:
Each InterSystems IRIS 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.
InterSystems IRIS uses AES (the Advanced Encryption Standard) to perform its encryption and decryption when InterSystems IRIS writes to or reads from disk. For databases, InterSystems IRIS 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 InterSystems IRIS platform. (This chapter also includes a section that addresses how the InterSystems IRIS 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 InterSystems IRIS 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 an InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS; other tasks are related to an instance of InterSystems IRIS, 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 InterSystems IRIS), tasks are:
Related to an instance of InterSystems IRIS and encryption keys for it, tasks are:
Other miscellaneous tasks are:
Note:
If you wish to configure encryption for journal files or the IRISTEMP and IRISLOCALDATA databases, this is part of InterSystems IRIS startup configuration. See the section “Configuring InterSystems IRIS Database Encryption Startup Settings” for details.
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:
  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.
  5. 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 InterSystems IRIS 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 InterSystems IRIS 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 Filey.” 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:
To add a key to an existing key file, the procedure is:
  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 InterSystems IRIS 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 InterSystems IRIS 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.
  7. 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:
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, the procedure is:
  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.
Adding an Administrator to a Key File
To add an administrator to an existing key file, the procedure is:
  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, the procedure is:
  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
InterSystems IRIS supports up to four simultaneously activated keys for database encryption. To activate a key for database encryption, the procedure is:
  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.
InterSystems IRIS 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 InterSystems IRIS opens as many keys as it can.
After key activation, the page displays the table of activated keys. For each key that InterSystems IRIS 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, InterSystems IRIS 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:
  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 InterSystems IRIS 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. InterSystems IRIS does not allow you deactivate a key under the following circumstances:
    • The IRISTEMP and IRISLOCALDATA databases are encrypted.
    • There is a currently-mounted encrypted database (other than IRISTEMP and IRISLOCALDATA) 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, InterSystems IRIS 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:
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 InterSystems IRIS shutdowns and restarts.
To specify a new key for either of these purposes, the procedure is:
  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.
InterSystems IRIS 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 InterSystems IRIS instance). Hence, specifying either of these for a key makes the key’s Delete button unavailable.
Activating a Data Element Encryption Key
InterSystems IRIS supports up to four activated keys at one time for data element encryption. To activate a key for data element encryption, the procedure is:
  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.
InterSystems IRIS 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 InterSystems IRIS opens as many keys as it can.
After key activation, the page displays the table of activated keys. For each key that InterSystems IRIS 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, InterSystems IRIS 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:
  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.
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 InterSystems IRIS. You can:
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 an InterSystems IRIS cluster, the InterSystems IRIS 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 an InterSystems IRIS 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
  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 InterSystems IRIS for unattended startup and provide InterSystems IRIS 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 InterSystems IRIS 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:
  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 InterSystems IRIS 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 InterSystems IRIS instances are able to read data encrypted by each other. Since each InterSystems IRIS instance has a key file on its machine, the key file should always be available for an InterSystems IRIS 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 InterSystems IRIS 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:
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.
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:
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 InterSystems IRIS 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, InterSystems IRIS 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:
  1. A system administrator (who does not have the key but does have the information to use the key) needs to re-start InterSystems IRIS. After or as part of an InterSystems IRIS re-start, the database encryption key needs to be activated, so that encrypted databases or databases containing encrypted data can be mounted.
  2. 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.
  3. 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.
  4. 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.
  5. 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, InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS 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, InterSystems IRIS must have an activated database-encryption key. Hence, the procedure is:
  1. Activate a database-encryption key.
  2. From the Management Portal home page, go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).
  3. On the Local Databases page, select Create New Database. This displays the Create Database wizard.
  4. On the second page of the wizard, in the Encrypt Database? box, select Yes. This causes InterSystems IRIS 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 InterSystems IRIS” chapter of the System Administration Guide.)
Note:
InterSystems IRIS 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:
  1. Activate the key.
  2. From the Management Portal home page, go to the Databases page (System Operation > Databases).
  3. 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, InterSystems IRIS 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.
  3. 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, InterSystems IRIS displays an error message.
Moving an Encrypted Database Between Instances
If your organization has multiple InterSystems IRIS 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 InterSystems IRIS Database Encryption Startup Settings
By default, an instance of InterSystems IRIS 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). InterSystems IRIS 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:
Configuring Startup without Key Activation
This is the default behavior for an instance of InterSystems IRIS 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 InterSystems IRIS startup and other options for encrypted databases.
  3. In this area, from the Startup Options list, select None.
  4. Click Save. InterSystems IRIS 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 IRISAUDIT database, this is because the audit log is encrypted.)
To configure InterSystems IRIS 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:
  1. 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 writable, so do not select the Read Only check box.)
  2. 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:
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. 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.
  2. 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 InterSystems IRIS 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 Data Integrity Guide.
The InterSystems IRIS 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, InterSystems IRIS 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\IRIS\Mgr\IRISAudit\
The error message refers to encrypted databases because the audit log is stored in the InterSystems IRIS database IRISAUDIT.
The audit log cannot be encrypted if InterSystems IRIS starts without activating an encryption key. To configure startup not to involve key activation, you must change the InterSystems IRIS setting to specify that the instance uses an unencrypted audit log. The procedure is:
  1. Back up the instance’s audit data.
  2. Go to the Database Encryption page (System Administration > Encryption > Database Encryption).
  3. Select Configure Startup Settings, which displays the area with options for configuring InterSystems IRIS startup and other options for encrypted databases.
  4. Under Optionally Encrypted Data, in the Encrypt Audit Log list, click “No”.
Changing this setting causes InterSystems IRIS 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 InterSystems IRIS if a key has been activated. With interactive key activation, the InterSystems IRIS 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 InterSystems IRIS as a service that starts automatically as part of system startup.
To configure InterSystems IRIS 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 InterSystems IRIS is configured to
then failure to activate the required encryption key causes an InterSystems IRIS startup failure. If this occurs, use InterSystems IRIS emergency startup mode to configure InterSystems IRIS 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 InterSystems IRIS starts running. This includes the InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS to activate a key at startup without requiring any human intervention, then:
  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.
When you configure InterSystems IRIS 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 InterSystems IRIS is configured to
then failure to activate the encryption key causes an InterSystems IRIS startup failure. If this occurs, use InterSystems IRIS emergency startup mode to configure InterSystems IRIS not to require any encrypted facilities at startup.
About Encrypting the Databases that Ship with InterSystems IRIS
Each instance of InterSystems IRIS 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, InterSystems IRIS 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, InterSystems IRIS 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-Keying Data in Real Time
Data element encryption allows InterSystems IRIS 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:
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 InterSystems IRIS 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. Follow all the precautions specified in the section “Special Cautions to Preserve the Data in Encrypted Databases.”
  3. Set up InterSystems IRIS 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
Important:
THIS PROCEDURE IS FOR AN EMERGENCY SITUATION, WHERE ENCRYPTED DATA IN INTERSYSTEMS IRIS DATABASES IS IN DANGER OF BEING LOST.
If the file containing the activated key becomes inaccessible or damaged while InterSystems IRIS is running, immediately perform the following procedure for each database encrypted with that key:
  1. Do not shut down InterSystems IRIS.
    Do not deactivate the currently active key.
    Warning:
    Shutting down InterSystems IRIS 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. 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.
  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\MyIRIS\mgr\
2) C:\InterSystems\MyIRIS\mgr\irislocaldata\
3) C:\InterSystems\MyIRIS\mgr\irisaudit\
4) C:\InterSystems\MyIRIS\mgr\irislib\
5) C:\InterSystems\MyIRIS\mgr\iristemp\
6) C:\InterSystems\MyIRIS\mgr\encrypted1\
7) C:\InterSystems\MyIRIS\mgr\encrypted2\
8) C:\InterSystems\MyIRIS\mgr\unencrypted\
 
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). InterSystems IRIS 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 InterSystems IRIS startup time — such as if the media holding it is not currently available.
To correct the condition, after InterSystems IRIS starts running in single-user mode, then the procedure is:
  1. Shut down InterSystems IRIS. For example, if the instance of InterSystems IRIS is called “MyIRIS”, the command to do this would be: 
    iris force MyIRIS
  2. If you know the location where InterSystems IRIS 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 InterSystems IRIS again.
InterSystems IRIS 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 InterSystems IRIS startup time and is not available, you may have a backup key file available. If so, then to correct the condition, after InterSystems IRIS 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 messages.log file. Typically, this specifies starting a Terminal session with the -B flag.
    For example, at a Windows command line, for an instance of InterSystems IRIS called “MyIRIS” that is installed in the default location, the command would be: 
    c:\InterSystems\MyIRIS\bin\irisdb -sc:\InterSystems\MyIRIS\mgr -B
    This connects you with InterSystems IRIS in the operating system terminal window; the prompt in that window changes from the operating system prompt to the InterSystems IRIS %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 InterSystems IRIS.
  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 InterSystems IRIS is ready for use, use ^STURECOV to complete the startup procedure. InterSystems IRIS then starts in multi-user mode.
InterSystems IRIS 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 InterSystems IRIS called “MyIRIS” that is installed in the default location, the command would be: 
    c:\InterSystems\MyIRIS\bin\irisdb -sc:\InterSystems\MyIRIS\mgr -B
    This connects you with InterSystems IRIS in the operating system terminal window; the prompt in that window changes from the operating system prompt to the InterSystems IRIS %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 InterSystems IRIS database startup options not to require a database encryption key. This means that the IRISTEMP and IRISLOCALDATA 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 InterSystems IRIS is ready for use, use ^STURECOV to complete the startup procedure. InterSystems IRIS 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 InterSystems IRIS Facilities
InterSystems IRIS database encryption protects database files themselves. Regarding related facilities in InterSystems IRIS:

Previous section           Next section
View this book as PDF
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-02-22 00:52:40