Security Administration Guide
Managed Key Encryption
|
|
InterSystems IRIS™ 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 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:
A
key, short for
data-encryption key, is a 128, 196, or 256bit 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:
When you create an encryption key file, it contains one key. To create an encryption key file and its initial key, the procedure is:
-
-
-
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 InterSystems IRIS instance (which is below the InterSystems IRIS installation directory that is, in
<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 InterSystems IRIS will create the key file. (If you provide the name of an existing file, InterSystems IRIS will not overwrite it and the save will fail.)
-
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 InterSystems security, this name need not match any user names that are part of InterSystems security. By default, the initial administrator name value is the current username. The administrator name cannot include Unicode characters.
-
Because the database encryption functionality exists independent of InterSystems security, this password need not match the password that a user has for InterSystems 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.
-
-
-
Click
Save at the top of the page to save the key file to disk.
-
-
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.
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.
To create a key, you can either:
-
Create a key file. This causes InterSystems IRIS 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:
-
-
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
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.)
-
-
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.
To delete a key from a key file, the procedure is:
-
-
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.
-
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.
-
Click
OK on the confirmation dialog to delete the key from the file.
To add an administrator to an existing key file, the procedure is:
-
-
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:
-
-
-
New Administrator Name The name of the new administrator to be added to the file. Because the encryption functionality is independent of InterSystems security, the administrator name need not match any user names that are part of InterSystems 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 InterSystems security, the password need not match the password that a user has for InterSystems security.
-
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.
To delete an administrator from a key file, the procedure is:
-
-
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.
InterSystems IRIS supports up to four simultaneously activated keys for database encryption. To activate a key for database encryption, the procedure is:
-
-
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, InterSystems IRIS looks for the key file in the specified directory on the specified drive; if you enter a relative file name, InterSystems IRIS looks for the key file starting in the manager’s directory for the InterSystems IRIS instance (which is below the InterSystems IRIS installation directory that is, in
<install-dir>/mgr/). You can also use the
Browse button to display a dialog for opening the key file.
-
-
Password The password specified for the named administrator.
-
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.
To deactivate a database encryption key, the procedure is:
-
-
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.
-
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:
-
-
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.
-
Click
OK on the confirmation dialog to deactivate the key.
To deactivate the key, each underlying condition requires a different action:
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:
-
-
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.
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.
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:
-
-
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, InterSystems IRIS looks for the key file in the specified directory on the specified drive; if you enter a relative file name, InterSystems IRIS looks for the key file starting in the manager’s directory for the InterSystems IRIS instance (which is below the InterSystems IRIS installation directory that is, in
<install-dir>/mgr/).
-
-
Password The password specified for the named administrator.
-
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.
To deactivate a data element encryption key, the procedure is:
-
-
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.
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:
-
-
-
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:
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.”
)
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.
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 InterSystems IRIS 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 InterSystems IRIS 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.
-
Create a database-encryption key on one node or member. For more information on this procedure, see the section
“Creating a Key File.”
-
Caution:
Failure to take these precautions can result in a situation in which the encrypted databases or journal files are unreadable and
permanently lost.
-
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.
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.”
-
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.
-
-
Get a copy of the key file and put it in a secure and stable location on that machine.
-
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).
The following sections address important topics for managing encrypted databases:
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.
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:
-
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.
-
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.
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.
Management tasks for encrypted databases include:
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:
-
-
-
-
Note:
InterSystems IRIS also provides the
cvencrypt utility to encrypt unencrypted databases or decrypt encrypted databases, if this is necessary.
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:
-
-
-
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.
To close the connection to an encrypted database, the procedure is:
-
-
On this page, select the
Dismount button on the right in the table of databases. After selecting
OK on the confirmation screen, the database is dismounted.
-
Because the activated key is used for each read and write to the database, you cannot deactivate the key without first dismounting the database. If you attempt to deactivate the key prior to dismounting the database, InterSystems IRIS displays an error message.
The features that depend on having a key available at startup time are:
-
Encrypting the InterSystems IRIS audit log.
-
-
Encrypting InterSystems IRIS journal files.
-
Having an encrypted database mounted at startup time.
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:
-
-
Select
Configure Startup Settings. This displays the area with options for configuring InterSystems IRIS startup and other options for encrypted databases.
-
-
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:
-
Confirm that the database is mounted or mount it. To do this:
-
-
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.
-
If it is not mounted, select
Mount
-
On the confirmation screen, select
OK. (The database needs to be writable, 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:
-
-
Find the database’s row in the table of databases.
-
Select the database by clicking on its name. This displays the page for editing the database.
-
-
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.
-
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:
-
-
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.
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:
-
Back up the instance’s audit data.
-
-
Select
Configure Startup Settings, which displays the area with options for configuring InterSystems IRIS startup and other options for encrypted databases.
-
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:
-
-
-
-
The fields in this area are:
-
-
Note:
This change takes effect the next time that InterSystems IRIS switches journal files. To begin journal file encryption without a restart, switch journal files after completing this page.
-
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 InterSystems IRIS is configured to
-
-
Require an encrypted database at startup
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:
-
You need to have a key currently activated. To activate a key, see the section
“Activating a Key.”
-
-
-
-
-
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 InterSystems IRIS installation directory. Click
Browse to search for the database-encryption key file on the file system.
-
-
Password The administrator’s password.
-
-
-
Note:
This change takes effect the next time that InterSystems IRIS switches journal files. By default, this occurs the next time that InterSystems IRIS restarts. To begin journal file encryption without a restart, switch journal files after completing this page.
-
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 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
-
-
Require an encrypted database at startup
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.
Each instance of InterSystems IRIS ships with a number of databases. The ability to encrypt and the value of encryption depends on the database:
-
IRISLOCALDATA: Can be encrypted in conjunction with the
IRISTEMP database. Encrypting
IRISLOCALDATA requires that a key be available at startup, since the database is required at startup time.
-
IRISAUDIT: Can be encrypted. Encrypting
IRISAUDIT requires that a key be available at startup, since the database is required at startup time.
-
IRISLIB: Must not be encrypted. (Note that all content in
IRISLIB is publicly available.)
-
IRISSYS: Must not be encrypted. If an instance has an encrypted form of this database, InterSystems IRIS cannot start.
-
IRISTEMP: Can be encrypted in conjunction with the
IRISLOCALDATA database. Encrypting
IRISTEMP requires that a key be available at startup, since the database is required at startup time.
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).
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.
Since data element encryption is available through an API, there are also a set of calls for managing keys:
$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
-
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.
$SYSTEM.Encryption.AESCBCManagedKeyDecrypt
The signature of this method as it is usually called is:
$SYSTEM.Encryption.AESCBCManagedKeyDecrypt
(
ciphertext As %String
)
As %String
-
-
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.
$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
-
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.
-
$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
-
ciphertext The encrypted stream to be decrypted.
-
plaintext The variable to receive the unencrypted stream.
-
You do not need to include the key ID with this call, as the key ID is associated with the ciphertext to be decrypted.
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.
This section describes what to do under certain circumstances when you are in danger of losing data. These include:
In this situation, the following circumstances have occurred:
-
A database-encryption key has been activated for the InterSystems IRIS instance.
-
InterSystems IRIS 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 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:
-
-
-
Set up InterSystems IRIS 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 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:
-
Warning:
Shutting down InterSystems IRIS 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:
-
-
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.
-
When the
Databases page appears again, select the
Mount option in the last column in the database’s row.
-
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"
-
%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\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.
-
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):
-
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:
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). 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:
-
Create a new database-encryption key according to the procedure described in the section
“Creating a Key.”
-
-
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.
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:
-
InterSystems IRIS is configured for either interactive or unattended startup.
-
Startup specifies that journal files and/or the
IRISTEMP and
IRISLOCALDATA 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 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:
-
-
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.)
-
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:
-
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
messages.log file. Typically, this specifies starting a Terminal session with the
-B flag.
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.
-
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.
-
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 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:
-
Contact InterSystems Worldwide Response Center (WRC). Engineers there can help guide you through the following procedure and answer any questions that may arise.
-
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.
-
If any encrypted databases require mounting at startup, disable this feature for them:
-
-
Click the name of the database in the table of databases. This displays the
Edit: page for the database.
-
-
-
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.
-
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.
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.”
InterSystems IRIS database encryption protects database files themselves. Regarding related facilities in InterSystems IRIS:
-
-
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.)
-
-
Content Date/Time: 2019-02-22 00:52:40