Skip to main content

Key Management Tasks

Key Management Tasks

A key, short for data-encryption key, is a 128–, 196–, or 256–bit bit string that is used with a cryptographic algorithm to reversibly encrypt or decrypt data. Each key has a unique identifier (known as a GUID), which InterSystems IRIS® data platform displays as part of key management activities.

Key management is the set of activities associated with creating keys, activating keys, deactivating keys, assigning default keys for various activities, and deleting keys. It also includes management activities associated with key storage. You can store keys in either of two ways:

  • In key files — The following types of key files are supported:

    • Standard Key Files — Key files that can contain multiple keys, the contents of which are encrypted via a key administrator passphrase. These key files can contain up to 256 encrypted keys. See Manage Keys in Standard Key Files for details.

    • KMS Key Files — Key files that contain keys encrypted via key management services (KMS) provided by the AWS or Azure cloud service provider (CSP). Each KMS key file can only contain a single key. See Using a KMS for Key Management for prerequisite and usage information.

  • On a KMIP server — A KMIP server is a key management server that can send and receive communications using the key management interoperability protocol (KMIP). KMIP servers are available from various third-party vendors; those vendors provide instructions for configuring and using the KMIP server generally.

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 Configure Encryption Startup Settings for details.

Manage Keys in Standard Key Files

A key file is a file that holds encrypted copies of one or more data-encryption keys (DEKs). Key file management is the set of activities associated with key files themselves, such as adding administrators to or removing administrators from key files. Within a particular standard key file, all administrators have access to all keys. All keys are stored in an encrypted form, along with administrator information; each DEK is individually encrypted using a key-encryption key (KEK). For each administrator in the standard key file, there is a unique, encrypted copy of the KEK, which is encrypted using a principal key — where each principal key is derived from an individual key administrator’s password. Encryption tasks require an activated DEK, and InterSystems IRIS requires an administrator username and password to decrypt that key so that it can then be used for encryption tasks. See the following diagram for a visual depiction of the standard key file process:

Standard key file key encryption process

Working with standard key files involves the following tasks:

Note:

If an instance uses multiple keys at startup time (such as with journal files, the audit database, and other databases), then those keys must all be in a single standard key file. This allows them all to be available when the instance starts.

Create a Standard Key File

When you create a standard key file, it contains one key. To create a standard key file and its initial key:

  1. From the Management Portal home page, go to the Create Encryption Key File page (System Administration > Encryption > Create New Encryption Key File).

  2. On the Create Encryption Key File page, specify the following values:

    • Key File — The name of the standard key file where the encryption key is stored; this can be an absolute or relative path name.

      If you enter an absolute file name, the standard key file is placed in the specified directory on the specified drive; if you enter a relative file name, the standard 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 standard key file. (If you provide the name of an existing file, InterSystems IRIS will not overwrite it and the save will fail.)

      WARNING:

      Any key stored in <install-dir>/Mgr/Temp is deleted when InterSystems IRIS next reboots — never store a key in <install-dir>/Mgr/Temp.

    • Administrator Name — The name of an administrator who can activate the key. There must be at least one administrator.

      Because the database encryption functionality exists independent of InterSystems IRIS security, this name need not match any user names that are part of InterSystems IRIS security. By default, the initial administrator name value is the current username. The administrator name cannot include Unicode characters.

    • Password — A password for this user.

      Because the database encryption functionality exists independent of InterSystems security, this password need not match the password that a user has for InterSystems IRIS 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.

      Important:

      The key administrator’s password is not stored anywhere on disk. It is the responsibility of the key administrator to ensure that this information is not lost.

    • Confirm Password — The password for this user entered again to confirm its value.

    • Cipher Security Level — The length of the key, where choices are 128–bit, 192–bit, and 256–bit.

    • Key Description — Text that describes the key that is initially created and stored in the standard key file. This text appears in the Description column of the Encryption Keys Defined in Key File table.

  3. Click Save at the top of the page to save the standard key file to disk.

  4. Having just created a key, follow the instructions in Protection from Accidental Loss of Access to Encrypted Data to create and store a backup copy of the newly updated standard key file.

This creates a standard 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 standard 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 key-encryption key (KEK), and there is a single copy of the KEK, which is encrypted using the administrator’s principal key. You can add additional keys to the standard key file according to the instructions in Add a Key to a Standard Key File. You can add administrators to the standard key file according to the instructions in Add an Administrator to a Standard Key File.

WARNING:

InterSystems strongly recommends that you create and store a backup copy of the standard 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.

Add a Key to a Standard Key File

When using standard key files, there are two different ways to create a key:

  • Create a standard key file. This causes InterSystems IRIS to create a key and place it in the file. To create a standard key file, see Create a Standard Key File.

  • Add a key to an existing standard key file, as described in this section.

To add a key to an existing standard key file:

  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).

  2. On the Manage Encryption Key File page, in the Key File field, enter the name of the standard key file to which you want to add and store the key; click OK. This displays information about that standard key file; at the bottom of the shaded area, the Encryption Keys Defined in Key File table displays a list of the one to 256 keys in the standard key file. If there are 255 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 standard 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:

    • Existing Administrator Name — The name of an administrator associated with the standard key file. (Administrators associated with the file appear in the Administrators Defined in Key File table on the Manage Encryption Key File page.)

    • Existing Administrator Password — This administrator’s password.

    • Description — Text to describe the key. This text appears in the Description column of the Encryption Keys Defined in Key File table.

  5. Click OK to save the key to the standard 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 standard 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 standard key file, follow the instructions in Protection from Accidental Loss of Access to Encrypted Data to create and store a backup copy of the newly updated standard key file.

WARNING:

InterSystems strongly recommends that you create and store a backup copy of the standard 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.

Delete a Key from a Standard Key File

To delete a key from a standard key file:

  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).

  2. On the Manage Encryption Key File page, in the Key File field, enter the name of the standard key file from which you want to delete the key; click OK. This displays information about that standard key file; at the bottom of the shaded area, the Encryption Keys Defined in Key File table displays a list of the one to 256 keys in the standard key file. If there is one or more keys in the file, you can delete a key from the file.

  3. In the table of keys, click Delete in the row for a key to delete that key. Clicking Delete displays a confirmation page for the action.

    If the key’s Delete button is not available, this is because the key is the default encryption key or the journal encryption key for the file. To delete the key, first specify that another key is the default encryption key or the journal encryption key for the file by clicking Set Default or Set Journal for the other key.

  4. Click OK on the confirmation dialog to delete the key from the file.

WARNING:

Before deleting the only existing copy of a key, it is critical that you are absolutely sure that there is no existing encrypted content that uses it. If there is no copy of the key that is required to decrypt data, the encrypted data that it protected will be unreadable and permanently lost.

Add an Administrator to a Standard Key File

To add an administrator to an existing standard key file:

  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).

  2. In the Key File field, enter the path and filename of the standard key file to open and click OK; you can also use the Browse button to look for the key. Once the Portal opens the standard 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:

    • Existing Administrator Name — The name of an administrator already in the file.

    • Existing Administrator Password — The password associated with the already existing administrator in the file.

    • New Administrator Name — The name of the new administrator to be added to the file. Because the encryption functionality is independent of InterSystems IRIS security, the administrator name need not match any user names that are part of InterSystems IRIS 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 IRIS security, the password need not match the password that a user has for InterSystems IRIS security.

    • Confirm New Administrator Password — Confirmation of the password for the new administrator.

    Complete these fields and click OK. You have now added a new administrator to the standard key file.

Once you have added the new administrator to the standard key file, you may wish to copy the standard 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 standard key file are made and later on, as an administrative function, a new administrator is added, only the copy of the standard key file with the new administrator will be up to date.

Note:

When you add a new administrator to a standard 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 standard key file for that administrator name and then create a new entry with the same name and a new password.

Delete an Administrator from a Standard Key File

To delete an administrator from a standard key file:

  1. From the Management Portal home page, go to the Manage Encryption Key File page (System Administration > Encryption > Manage Encryption Key File).

  2. In the Key File field, enter the path and filename of the key and click OK. This displays a table with the administrators listed in the file (as well as a table of encryption keys in the file).

  3. In the table of administrators, click Delete next to an administrator to remove that administrator for the key. Clicking Delete displays a confirmation page for the action. (If there is only one administrator in the file, there is no Delete button, as it is not permitted to delete this administrator.)

  4. Click OK to delete the administrator from the file.

Activate a Database Encryption Key from a Standard Key File

InterSystems IRIS supports up to 256 simultaneously activated keys for database encryption. To activate a key from a standard key file for database encryption:

  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption). If there are already any activated keys, the page displays a table listing these.

  2. On this page, click Activate Key, which displays the fields for activating a key.

  3. Enter values for the following fields:

    • 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 standard key file in the specified directory on the specified drive; if you enter a relative file name, InterSystems IRIS looks for the standard 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 standard key file.

    • Administrator Name — The name of an administrator for this key, specified either when the key was created or edited.

    • Password — The password specified for the named administrator.

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

Activate a Data-Element Encryption Key from a Standard Key File

InterSystems IRIS supports up to 256 activated keys at one time for data-element encryption. To activate a key for data-element encryption:

  1. From the Management Portal home page, go to the Data Element Encryption page (System Administration > Encryption > Data Element Encryption). If there are already any activated keys, the page displays a table listing these.

  2. On the Data Element Encryption page, select Activate Key, which displays the fields for activating a key. If key activation is not available, this is because there are already 256 activated data element keys.

  3. 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 standard key file in the specified directory on the specified drive; if you enter a relative file name, InterSystems IRIS looks for the standard 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/).

    • Administrator Name — The name of an administrator for this key, specified either when the key was created or edited.

    • Password — The password specified for the named administrator.

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

Manage Keys and Standard 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 for important information. (There are no mirroring-related requirements in regard to database encryption.)

There are two ways to enable sharing of a single key:

  • All of the instances share a single standard key file, which is located on one cluster node or mirror member.

    In this case, if you change the single copy of the standard key file, then these changes are visible to all nodes or members. However, if the host holding the standard key file becomes unavailable to the other nodes or members, any attempt to read the key from the standard key file fails; this can prevent InterSystems IRIS instances from restarting properly.

  • Each cluster node or mirror member has its own copy of the standard key file.

    Here, if you change the standard key file, then you propagate copies of the standard key file (containing the same key) to all the other nodes or members. This increases the burden of administering the standard 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 standard key files, the database encryption key itself is the same for all instances.

Using a Single Standard Key File

To use a single standard key file:

  1. Create a database encryption key on one node or member. For more information on this procedure, see Create a Standard Key File.

  2. Secure this key according to the instructions in 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 standard key file. For more information on this procedure, see 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 standard key file are visible to all instances.

Using Multiple Standard Key Files

To use multiple copies of a standard key file:

  1. Create a database encryption key on one node or member. For more information on this procedure, see Create a Standard Key File.

  2. Secure this key according to the instructions in 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 standard key file for each of the remaining nodes or members.

  4. On each node or member:

    1. Get a copy of the standard 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 Startup with Unattended Key Activation.

Since each copy of the standard 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 standard key file on its machine, the standard key file should always be available for an InterSystems IRIS restart. If there are any changes to the standard key file (such as adding or removing administrators), you must propagate new copies of the standard key file to each machine and reconfigure each instance of InterSystems IRIS for unattended startup using the new copy of the standard key file (even if that file is in the same location as the old file).

Using a KMS for Key Management

InterSystems IRIS enables you to use the key management services (KMS) provided by a cloud service provider (CSP). The KMS key acts as the key-encryption key (KEK), as in the standard key file encryption process. That is, the KEK encrypts the data-encryption key (DEK) which is then stored in the KMS key file. A diagram showing an overview of this process is below:

KMS key file encryption process

Prerequisites

  • Install the command line interface (CLI) specific to your KMS provider. See the KMS documentation provided by the CSP for specifics.

  • Create and configure the user/service principal that represents the InterSystems IRIS instance when authenticating to the CSP. This user needs to have the appropriate key access policy configured through the key’s associated key policy. For Azure, this is through the key’s associated key vault access configuration, using either vault access policy or RBAC permission models. Check you can authenticate to the CSP through the CLI using the InterSystems IRIS user or service principal you configured. See the KMS documentation provided by the CSP for specifics.

  • Create a KMS key on the CSP. For AWS, create a symmetric key. See Creating Keys for AWSOpens in a new tab for more details. For Azure, create an RSA key. See About Azure Key Vault KeysOpens in a new tab for more details. Keep the key ID of this key available as you need it for creating the KMS key file.

Interacting with the KMS

To perform key management tasks using the KMS for encryption, you can either invoke the ^EncryptionKey routine or the InterSystems IRIS KMS API, both are in the %SYS namespace in the InterSystems IRIS terminal. For the ^EncryptionKey routine, enter at the command line:

%SYS>do ^EncryptionKey

^EncryptionKey has a menu-driven interface that enables you to perform the following KMS key management tasks:

  • Create a key.

  • Activate a database encryption key.

  • Activate a data element encryption key.

  • Configure unattended key activation with a KMS key file.

See Command-Line Security Management Utilities for more information about ^EncryptionKey.

Creating a New KMS Encryption Key Using the ^EncryptionKey Routine

To create a new KMS encryption key using the ^EncryptionKey routine, follow these steps:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, switch to the %SYS namespace:

    >zn "%SYS"

  3. Run ^EncryptionKey:

    >do ^EncryptionKey

  4. In ^EncryptionKey, select option 1 Create new encryption file, then enter a name for your key file at the prompt. No extension is appended so the name you enter is the exact name of the file.

  5. To use KMS, enter y at the Use KMS? prompt.

  6. If desired, enter a description.

  7. Select the key size.

  8. Optional: If you decide to back up to a standard key file:

    1. Enter the name of the backup standard key file and a key description when prompted.

    2. Enter the username and password of a key administrator.

      Because the database encryption functionality exists independent of InterSystems security, this password need not match the password that a user has for InterSystems IRIS 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.

  9. Choose the desired KMS (AWS or Azure).

  10. At the Server Key ID prompt, enter the key ID of the KMS key you wish to use. This is the ID of the key you previously configured on the KMS.

  11. If you are using Azure, skip this step. If you are using AWS:

    1. Enter your region (for example, us-east-2).

    2. Optional: You can enter AWS environment variables at the Environment variable key prompt. For each desired variable, enter the variable key at the Environment variable key prompt. Then enter the value at the Environment variable value prompt. See the AWS documentationOpens in a new tab for more information about AWS environment variables. One reason for using environment variables is to use a shared credentials file (AWS_SHARED_CREDENTIALS_FILE) for authentication to the CSP through the command line.

  12. The new KMS key file and data-encryption key are created. The display will echo back the following information:

    Encryption key file created

    The name of the encryption file containing the data-encryption key.

    Encryption key backup file created

    The name of the backup standard key file (if provided).

    Encryption key created via KMS

    The key used to encrypt data in InterSystems IRIS.

  13. Optional: Configure InterSystems IRIS startup options to use the new KMS key file by default:

    1. Choose 4 Configure InterSystems IRIS startup options.

    2. Choose 3 Unattended key activation with a key file, then enter the KMS key file name. If you are not using AWS, ignore the Environment variable key prompt.

    For more information about unattended startup, see Startup with Unattended Key ActivationOpens in a new tab.

Creating a New KMS Encryption Key Using the InterSystems IRIS KMS API

To create a new KMS encryption key file using the API, use the $System.Encryption.KMSCreateEncryptionKey() method. It has the same KMS prerequisites as the ^EncryptionKey routine. It follows the below usage:

%SYS>set KeyID = $System.Encryption.KMSCreateEncryptionKey(File,Server,ServerKeyID,KeyLength,.Backup,Region,Description,.Env,.Status)

We retrieve and store the KeyID because it is required to identify and import the desired data-encryption key. This works for data-at-rest encryption and data-element encryption.

  • File — Required. Name of the key file to create.

  • Server — Required. Name of the KMS CSP server. Currently accepted values are “AWS" and "Azure" (case insensitive).

  • ServerKeyID — Required. Key ID of the principal key on the server.

  • KeyLength — Required. Length in bytes of the data- and key-encryption keys. Must be 16, 24, or 32.

  • Backup — Passed by reference, optional. Information for creating a backup key file. If specified, it must contain the following entries:

    • Backup(“File”) — Required. Name of the backup key file.

    • Backup(“Username”) — Required. Name of the initial encryption key administrator for the backup key file.

    • Backup(“Password”) — Required. Password for the initial encryption key administrator for the backup key file.

      Note:

      You should always obtain this value from a user prompt. You should never embed it in application code.

    • Backup(“Desc”) — Optional. Description of the key.

  • Region — Required for AWS only. Name of the region, for example us-east-2.

  • Description — Optional. Description of the key.

  • Env — Passed by reference, optional for AWS only. Environment variable information. For example, Env("AWS_CONFIG_FILE") or Env("AWS_SHARED_CREDENTIALS_FILE").

  • Status — Passed by reference, required. Returns the method status.

On success, this method returns the unique identifier of the new encryption key. See the below examples for AWS and Azure usage. Note, the API requires the calling user to have %Admin_Secure:U privileges as well as access to the %SYS namespace.

For AWS KMS API call:

%SYS>w ^KeyIDaws
604cae51-139d-4b88-b8ac-8b303446ebe7
%SYS>s KeyID=$System.Encryption.KMSCreateEncryptionKey("KMSTestAWS.key","AWS",^KeyIDaws,16,,"us-east-2","aws test key",,.rc) 
%SYS>w rc," ",KeyID
1 3C978FFD-DEA8-4393-A454-BC06B311D545

For Azure KMS API call:

%SYS>w ^KeyIDaz
https://test.vault.azure.net/keys/testkey/3ab1ba844c0b407c9b6063cefe5053dd
%SYS>s KeyID=$System.Encryption.KMSCreateEncryptionKey("KMSTestAZ.key","azure",^KeyIDaz,16,,,,,.rc)
%SYS>w rc," ",KeyID
1 8DC5555E-A464-4A59-9B3A-FD06857E5056

Managing Keys with the Key Management Interoperability Protocol (KMIP)

InterSystems supports the use of a KMIP server to manage database encryption keys. Using KMIP includes the following tasks:

Note:

  • InterSystems IRIS supports KMIP protocol versions 1.0–2.1.

  • KMIP activities are not supported on macOS instances of InterSystems IRIS.

Create a KMIP Server Configuration

When establishing a connection between InterSystems IRIS and a KMIP server, you create a KMIP server configuration, which defines properties of the KMIP server and represents it within the InterSystems IRIS instance. To create a KMIP server configuration:

  1. Set up the KMIP server according to its vendor’s instructions.

    Caution:

    When configuring a KMIP server, follow all proper backup procedures according to your vendor’s instructions. If you do not have backup copies of your keys, you may lose data permanently.

    Once you have set up the server, you can then set up the KMIP server configuration in InterSystems IRIS:

  2. To set up a KMIP server configuration, you must have:

    • The certificate authority (CA) certificate for the KMIP server, which must a trusted CA. You should receive this certificate from the vendor that provides the KMIP server or should obtain it according to instructions from that vendor.

    • A public-key certificate and private key for each instance of InterSystems IRIS that will communicate with the KMIP server. The certificate must be issued by a trusted CA. You should receive this certificate and private key from the vendor that provides the KMIP server or should obtain them according to instructions from that vendor.

    • The following information about the KMIP server:

      • Its fully-qualified DNS name or IP address

      • The port number on which it accepts connections

      • The version of the KMIP protocol that it supports

      • Any TLS settings that it requires for its clients

  3. On the InterSystems IRIS instance that will communicate with the KMIP server, create an TLS configuration that will represent the instance to the KMIP server:

    1. In the Portal, go to the SSL/TLS Configurations page (Home > System Administration > Security > SSL/TLS Configurations).

    2. On the SSL/TLS Configurations page, click the Create New Configuration button, which displays the New SSL/TLS Configuration page.

    3. On the New SSL/TLS Configuration page, set up the TLS configuration. For the fields listed below, specify or select values as follows

      • Enabled — Select this check box.

      • Type — Select Client.

      The values for other fields (Server certificate verification, the This client’s credentials fields, and the Cryptographic settings fields) depend on the requirements of the KMIP server. The values for the This client’s credentials fields depend on the client certificate, client private key, and CA certificate that you have received from the vendor that provides the KMIP server.

      For more information on this creating an TLS configuration, see Create or Edit a TLS Configuration.

  4. Create the configuration to the KMIP server:

    1. Start the Terminal and log in as a sufficiently privileged user.

    2. At the terminal prompt, go to the %SYS namespace:

      >set $namespace="%SYS"

    3. Run ^SECURITY

      %SYS>do ^SECURITY

    4. In ^SECURITY, select option 14, KMIP server setup.

    5. In the KMIP server setup choices, select option 1, Create KMIP server.

    6. At the Create KMIP server prompts, specify values for the following:

      • KMIP server to create? — The name of the KMIP server configuration.

      • Description? — A text description.

      • Server host DNS name? — The fully-qualified DNS name or IP address of the KMIP server.

      • TCP port number? — The port number on which the KMIP server accepts connections.

      • OASIS KMIP protocol version? — The number associated with your KMIP server’s supported version of the protocol. This is part of the information that you have received from the vendor that provides the KMIP server.

      • SSL/TLS Configuration name? — The name of the TLS configuration that you created in the previous step.

        Note:

        This case of the value that you enter here must match that of the TLS configuration name as defined.

      • Non-blocking I/O? — Whether or not connections to the KMIP server enable non-blocking I/O. InterSystems recommends Yes, which enables non-blocking I/O.

        If non-blocking I/O is enabled, control returns to the application after the timeout specified at the I/O timeout, in seconds? prompt (below). If non-blocking I/O is disabled, control returns to the application after an operating-system timeout (which may not occur).

      • Auto-reconnect? — Whether or not InterSystems IRIS reconnects with the KMIP server if the connection drops. InterSystems recommends that you select No; there is then no attempt to automatically reconnect if the connection drops.

      • I/O timeout, in seconds? — The amount of time, in seconds, before a timeout occurs in the connection to the KMIP server. This is only relevant if the configuration has enabled non-blocking I/O.

      • Log KMIP messages? — Whether or not InterSystems IRIS logs messages that it sends to the KMIP server. If messages are logged, InterSystems IRIS stores them in the <install-dir>/mgr/kmipcmd.log file.

      • Debug SSL/TLS? — Whether or not InterSystems IRIS logs TLS debugging information. If information is logged, InterSystems IRIS stores it in the <install-dir>/mgr/kmipssl.log file.

    7. After the prompts for KMIP server properties, confirm that you wish to create the KMIP server at the Confirm creation of KMIP server prompt.

Note:

InterSystems supports the use of multiple KMIP servers and the use of a single KMIP server that has multiple configurations. The most recently activated configuration is the default.

Edit a KMIP Server Configuration

To modify the values of the properties of an existing KMIP server configuration:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^SECURITY:

    %SYS>do ^SECURITY

  4. In ^SECURITY, select option 14, KMIP server setup.

  5. In the KMIP server setup choices, select option 2, Edit KMIP server.

  6. At the Edit KMIP server prompt, enter the name of the configuration to edit.

  7. ^SECURITY then presents prompts for the same properties as when creating a KMIP server configuration; it uses the existing values for the configuration’s properties as its defaults. Modify these values as required.

  8. After the prompts for KMIP server properties, confirm any edits to the properties of the KMIP server at the Confirm changes to KMIP server <servername> prompt.

Delete a KMIP Server Configuration

To delete a KMIP server configuration:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^SECURITY

    %SYS>do ^SECURITY

  4. In ^SECURITY, select option 14, KMIP server setup.

  5. In the KMIP server setup choices, select option 5, Delete KMIP server.

  6. At the KMIP server to delete? prompt, enter the name of the configuration to delete.

  7. Confirm the deletion when prompted.

List the KMIP Server Configurations

To list an InterSystems IRIS instance’s KMIP server configurations:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^SECURITY

    %SYS>do ^SECURITY

  4. In ^SECURITY, select option 14, KMIP server setup.

  5. In the KMIP server setup choices, select option 3, List KMIP servers.

^SECURITY then displays a list of any existing configurations to KMIP servers by name, whether or not they are currently in use.

List Details about a KMIP Server Configuration

To view details about a particular KMIP server configuration:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^SECURITY

    %SYS>do ^SECURITY

  4. In ^SECURITY, select option 14, KMIP server setup

  5. In the KMIP server setup choices, select option 4, Detailed list KMIP server.

  6. Enter the name of a KMIP server configuration at the Display which KMIP configuration? prompt.

^SECURITY then displays a list of the specified configuration’s properties, along with each one’s value.

Create a Key on the KMIP Server

To create a data-encryption key on a KMIP server:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 5, Manage KMIP server.

  5. When prompted, enter the name of the configuration for the KMIP server on which you wish to create a key.

  6. At the next prompt, where you select the action you wish to take, select option 2, for Create new key on KMIP server.

  7. At the next prompt, select a key length.

The ^EncryptionKey routine then creates the key and displays its key ID. Newly created keys are not activated by default; to activate the key, see Activate a Database Encryption Key from a KMIP Server.

Important:

InterSystems recommends that you record the key ID, so that you have this information available for future reference.

Delete a Key on the KMIP Server

To delete an encryption key on a KMIP server:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 5, Manage KMIP server.

  5. When prompted, enter the name of the configuration for the KMIP server on which you wish to delete the key.

  6. At the next prompt, where you select the action you wish to take, select option 3, for Destroy existing key on KMIP server.

  7. The routine then lists the keys on the KMIP server and prompts for the key to delete. Specify a key at the Select key prompt.

    WARNING:

    Before deleting the only existing copy of a key, it is critical that you are absolutely sure that there is no existing encrypted content that uses it. If there is no copy the key required to decrypt data, the encrypted data that it protected will be unreadable and will be permanently lost.

  8. When prompted, confirm that you wish to delete the key.

The routine then deletes the key from the KMIP server.

List the Keys on the KMIP Server

To list the encryption keys on a KMIP server:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 5, Manage KMIP server.

  5. When prompted, enter the name of the configuration of the KMIP server for which you wish to list the key(s).

  6. At the next prompt, select option 1, for List keys on KMIP server.

The routine then displays a list of all the keys on the KMIP server.

Activate a Database Encryption Key from a KMIP Server

To activate a database encryption key from a KMIP server:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 3, Database encryption.

  5. In the Database encryption choices, select option 1, Activate database encryption keys.

  6. In the Activate database encryption keys choices, select option 2, Use KMIP server.

    Note:

    If this prompt does not appear, it is because the instance does not have any KMIP server configurations; see Create a KMIP Server Configuration for instructions on this process.

  7. When prompted, enter the name of the configuration of the KMIP server from which you wish to activate the key.

  8. The routine then lists the keys on the KMIP server and prompts for which key to activate. Specify a key at the Select key prompt.

The routine then activates the key, displaying its ID.

For each key that InterSystems IRIS activates, the Database Encryption page (System Administration > Encryption > Database Encryption) adds the key to table of activated keys and displays the key’s identifier.

Note:

The table of keys does not display any file or path information. When activating a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.

Activate a Data-Element Encryption Key from a KMIP Server

InterSystems IRIS supports up to 256 activated keys at one time for data-element encryption. To activate a key for data-element encryption from a KMIP server:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 4, Data element encryption for applications.

  5. In the Data element encryption for applications choices, select option 1, Activate data element encryption key.

  6. In the Activate data element encryption key choices, select option 2, Use KMIP server.

    Note:

    If this prompt does not appear, it is because the instance does not have any KMIP server configurations; see Create a KMIP Server Configuration for instructions on this process.

  7. At the KMIP server prompt, enter the name of the configuration of the KMIP server from which you wish to activate the key.

  8. The routine then lists the keys on the KMIP server and prompts for which key to activate. Specify a key at the Select key prompt.

The routine then activates the key, displaying its ID.

For each key that InterSystems IRIS activates, the Data Element Encryption page (System Administration > Encryption > Data Element Encryption) adds the key to table of activated keys and displays the key’s identifier.

Note:

The table of keys does not display any file or path information. When activating a second or subsequent key, note the identifier(s) for the currently activated key(s) first, so that you can identify the new one.

Copy a Key from a KMIP Server to a Key File

You can copy a database encryption key from a KMIP server to a key file. This allows you to make keys available both for backup and for recovery from a network or KMIP service outage. You can:

Important:

Always store encryption key files on removable devices that are kept in securely locked storage.

Create a Key File with a Copy of a Key from a KMIP Server

To create a key file and copy a key from a KMIP server to it:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 1, Create new encryption key file.

  5. At the prompts that follow, specify:

    • The name of the key file (which is relative the <install-dir>/mgr/ directory)

    • A description of the key file

    • The name of an administrator for the key — this is a new administrator and can have a new name

    • The password (then confirmed) for that administrator — this is a new password, which can have any valid value

    • Available cipher security levels — the length of the key used to encrypt keys stored in the file

  6. At the next prompt, select option 2, Copy key from KMIP server. ^EncryptionKey then prompts for the key to copy to the file.

  7. At the Select key prompt, specify the number of the key to copy.

^EncryptionKey then creates the file with the administrator username and password that you specified, and places the selected key in that file.

Adding a Copy of a Key from a KMIP Server to an Existing Key File

To add a key from a KMIP server to an existing key file:

  1. For the relevant instance, start the Terminal and log in as a sufficiently privileged user.

  2. At the terminal prompt, go to the %SYS namespace:

    >set $namespace="%SYS"

  3. Run ^EncryptionKey:

    %SYS>do ^EncryptionKey

  4. In ^EncryptionKey, select option 2, Manage existing encryption key file.

  5. At the Encryption key file prompt, enter the path and name of the key file to which you are adding a key. The path is relative to the <install-dir>/mgr/ directory.

  6. At the next prompt, select option 5, Add encryption key. At the prompts that follow:

    1. Under Existing administrator, enter the Username and Password of an administrator for the key file.

    2. Enter a description of the key that you are adding to the key file.

  7. At the next prompt, select option 2, Copy key from KMIP server. At the prompts that follow:

    1. At the KMIP server prompt, enter the name of the KMIP server from which you are copying the key.

    2. At the Select key prompt, specify the number of the key to copy.

^EncryptionKey then adds the selected key to selected key file.

Storage-Independent Key Management Tasks

Some tasks are the same for keys in files and keys on a KMIP server:

Deactivate a Database Encryption Key

To deactivate a database encryption key:

  1. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption). If a key is currently activated, its identifier appears in the table of keys.

  2. You cannot deactivate a key if it is the default key either for new encrypted databases or for encrypting journal files. If you wish to deactivate a key that is 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:

  • For any encrypted database except IRISTEMP and IRISLOCALDATA, dismount the database on the Databases page (System Operation > Databases). You can then deactivate the key.

  • For IRISTEMP and IRISLOCALDATA, specify that these databases are not to be encrypted and then restart InterSystems IRIS. To do this, select Configure Startup Settings on the Database Encryption page; either you can choose not to activate a database encryption key at startup (in which case InterSystems IRIS turns off encryption for IRISTEMP and IRISLOCALDATA) or you can choose interactive or unattended database encryption key activation at startup (in which cases the choice whether or not to encrypt IRISTEMP and IRISLOCALDATA becomes available — choose No).

  • For encrypted journal files, ensure that no encrypted journal file is required for recovery. This is described in Encrypted Journal Files.

Deactivate a Data-Element Encryption Key

To deactivate a data-element encryption key:

  1. From the Management Portal home page, go to the Data Element Encryption page (System Administration > Encryption > Data Element Encryption) page. If there are any activated keys, the page displays a table listing them.

  2. In the table of activated keys, for the key you wish to deactivate, click Deactivate. This displays a confirmation dialog.

  3. In the confirmation dialog, click OK.

When the Data Element Encryption page appears again, the row in the table for the deactivated key should no longer be present.

Specify 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:

  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:

    • 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.

  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.

Next sectionUsing Encrypted Databases
Previous sectionIntroduction to InterSystems Encryption
FeedbackOpens in a new tab