Skip to main content

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 — A key file is a file that holds encrypted copies of up to 256 keys. A key file administrator provides a password in order to decrypt the key for use.

  • 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 Key Files

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

Working with 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 key file. This allows them all to be available when the instance starts.

Create a Key File

When you create an encryption key file, it contains one key. To create an encryption key file and its initial key:

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

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

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

      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 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 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 key file.

This creates a key file with a single database encryption key in it and with a single administrator. The page displays ID for the key, which is a string such as 9158980E-AE52-4E12-82FD-AA5A2909D029. The key ID is a unique identifier for the key which InterSystems IRIS displays here and on other pages. It provides a means for you to keep track of the key, regardless of its location. This is important because, once you save the key file, you can move it anywhere you choose; this means that InterSystems IRIS cannot track it by its location.

The key is encrypted using the master encryption key, and there is a single copy of master encryption key, which is encrypted using the administrator’s key-encryption key (KEK). You can add additional keys to the key file according to the instructions in Add a Key to a Key File. You can add administrators to the key file according to the instructions in Add an Administrator to a Key File.

WARNING:

InterSystems strongly recommends that you create and store a backup copy of the key file. Each time you create a database encryption key, it is a unique key that cannot be re-created. Using the same administrator and password for a new key still results in the creation of a different and unique key. If an unactivated key is lost and cannot be recovered, the encrypted database that it protected will be unreadable and its data will be permanently lost.

Add a Key to a Key File

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

  • Create a key file. This causes InterSystems IRIS to create a key and place it in the file. To create a key file, see Create 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:

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

  2. On the Manage Encryption Key File page, in the Key File field, enter the name of the key file to which you want to add and store the key; click OK. This displays information about that key file; at the bottom of the shaded area, the Encryption Keys Defined in Key File table displays a list of the one to 256 keys in the key file. If there are three or fewer keys in the file, you can create a new key and add it to the file.

  3. Click the Add button below the Encryption Keys Defined in Key File table to add a key to the key file. This displays the Add a New Encryption Key screen.

  4. In the Add a New Encryption Key screen, enter values in the following fields:

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

    • Existing Administrator Password — This administrator’s password.

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

  5. Click OK to save the key to the key file. This displays information about it in the Encryption Keys Defined in Key File table, including its ID, which is a string such as 9158980E-AE52-4E12-82FD-AA5A2909D029. (The key ID is a unique identifier for the key which InterSystems IRIS displays here and on other pages. It provides a means for you to keep track of the key, regardless of its location. This is important because, once you save the key file, you can move it anywhere you choose; this means that InterSystems IRIS cannot track it by its location.)

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

WARNING:

InterSystems strongly recommends that you create and store a backup copy of the key file. Each time you create a database encryption key, it is a unique key that cannot be re-created. Using the same administrator and password for a new key still results in the creation of a different and unique key. If an unactivated key is lost and cannot be recovered, the encrypted database that it protected will be unreadable and its data will be permanently lost.

Delete a Key from a Key File

To delete a key from a key file:

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

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

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

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

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

WARNING:

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

Add an Administrator to a Key File

To add an administrator to an existing key file:

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

  2. In the Key File field, enter the path and filename of the key file to open and click OK; you can also use the Browse button to look for the key. Once the Portal opens the key file, it displays a table with the administrators listed in the file; administrator names appear in all capital letters, regardless of how they were defined.

  3. In the table of administrators, click Add to add a new administrator. This displays a page with the following fields:

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

Delete an Administrator from a Key File

To delete an administrator from a key file:

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

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

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

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

Activate a Database Encryption Key from a Key File

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

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

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

  3. Enter values for the following fields:

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

    • 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 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 Key File

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

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

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

  3. Enter values for the following fields:

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

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

Using a Single Key File

To use a single key file:

  1. Create a database encryption key on one node or member. For more information on this procedure, see Create a 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 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 key file are visible to all instances.

Using Multiple Key Files

To use multiple copies of a key file:

  1. Create a database encryption key on one node or member. For more information on this procedure, see Create a 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 key file for each of the remaining nodes or members.

  4. On each node or member:

    1. Get a copy of the key file and put it in a secure and stable location on that machine.

    2. Configure each instance of InterSystems IRIS for unattended startup. For more information on this procedure, see Startup with Unattended Key Activation.

Since each copy of the key file contains the same key, all the InterSystems IRIS instances are able to read data encrypted by each other. Since each InterSystems IRIS instance has a key file on its machine, the key file should always be available for an InterSystems IRIS restart. If there are any changes to the key file (such as adding or removing administrators), you must propagate new copies of the key file to each machine and reconfigure each instance of InterSystems IRIS for unattended startup using the new copy of the key file (even if that file is in the same location as the old file).

Managing Keys with the Key Management Interoperability Protocol (KMIP)

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

Note:

KMIP activities are not supported on macOS instances of 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 four activated keys at one time for data-element encryption. To activate a key for data-element encryption from a KMIP server:

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

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

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

Feedback