Skip to main content

Using Encrypted Databases

To protect entire databases that contain sensitive information, InterSystems IRIS® data platform supports block-level database encryption (or, for short, database encryption). Database encryption is technology that allows you to create and manage databases that, as entire entities, are encrypted; it employs the InterSystems IRIS key management tools to support its activities.

When you create a database, you can choose to have it be encrypted; this option is available if there is a currently activated key. Once you have created an encrypted database, you can use it in the same way as you would use an unencrypted database. The encryption technology is transparent and has a small and deterministic performance effect.

This topic describes how to create and manage encrypted databases. The database encryption functionality also supports the ability to encrypt the audit log and journal files. Both these features require access to the database encryption key at startup time, as described in Configure Encryption Startup Settings.

Create an Encrypted Database

When creating a new database, you can specify that it is encrypted. However, before you can create an encrypted database, InterSystems IRIS must have an activated database encryption key. Hence, the procedure is:

  1. Activate a database encryption key.

  2. From the Management Portal home page, go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

  3. On the Local Databases page, select Create New Database. This displays the Create Database wizard.

  4. On the second page of the wizard, in the Encrypt Database? box, select Yes. This causes InterSystems IRIS to create an encrypted database. On all the other pages of the wizard, choose database characteristics as you would when creating any database. (For more information on creating databases, see Create Local Databases.)

Note:

InterSystems IRIS also provides encryption management tools to encrypt unencrypted databases or decrypt encrypted databases, if this is necessary.

Establish Access to an Encrypted Database

To perform various operations, such as adding a database to a mirror, the database must be mounted. However, for an encrypted database to be mounted, its key must be activated. Hence, access to the database requires activating the key and mounting the database, and the procedure for this is:

  1. Activate the key.

  2. From the Management Portal home page, go to the Databases page (System Operation > Databases).

  3. On this page, for the database that you wish to mount, select the Mount button in the far right column of its row in the table of databases. After selecting OK on the confirmation screen, the database is mounted. If the key is not activated, InterSystems IRIS cannot mount the database and displays an error message.

You can now access the data within the database.

Close the Connection to an Encrypted Database

To close the connection to an encrypted database, the procedure is:

  1. From the Management Portal home page, go to the Databases page (System Operation > Databases).

  2. On this page, select the Dismount button on the right in the table of databases. After selecting OK on the confirmation screen, the database is dismounted.

  3. Deactivate the key.

Because the activated key is used for each read and write to the database, you cannot deactivate the key without first dismounting the database. If you attempt to deactivate the key prior to dismounting the database, InterSystems IRIS displays an error message.

Move an Encrypted Database Between Instances

If your organization has multiple InterSystems IRIS instances, you may need to use an encrypted database on one instance that was created on another instance using a different key. To move the data from one instance to another, back up and then re-encrypt the database using the available encryption management tools. For more information, see Modify Database Encryption Using ^EncryptionKey.

Configure Encryption Startup Settings

This topic describes how to set up each of the three database encryption startup options:

InterSystems IRIS has several features that require having a key available at startup time (either interactively or through unattended startup):

  • Encrypting the InterSystems IRIS audit log.

  • Encrypting the IRISTEMP and IRISLOCALDATA databases. (Either both are encrypted or neither.)

  • Encrypting InterSystems IRIS journal files.

  • Having an encrypted database mounted at startup time.

Startup without Key Activation

This is the default behavior for an instance of InterSystems IRIS prior to having any keys activated. If you have set up key activation at startup and choose to turn it off, the procedure is:

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

  2. Select Configure Startup Settings. This displays the area with options for configuring InterSystems IRIS startup and other options for encrypted databases.

  3. In this area, from the Startup Options list, select None.

  4. Click Save. InterSystems IRIS may prevent you from performing this action if:

    • Any encrypted databases are required at startup. See Encrypted Databases Required at Startup for more details.

    • There are any encrypted journal files with open transactions. See Encrypted Journal Files for more details.

    • The audit log is encrypted. (The error message for this refers to an encrypted database because InterSystems IRIS stores the audit log in a database called IRISAUDIT.) See Encrypted Audit Log for more details.

    Address the issue that is preventing the change and then perform this procedure again. Once any issues are corrected, you will be able to successfully change to having startup without key activation.

Encrypted Databases Required at Startup

If the instance has encrypted databases that are required at startup and you attempt to configure startup not to involve key activation, the Management Portal displays an error message stating this and indicating that the key activation option cannot be changed. (If the error message refers to the IRISAUDIT database, this is because the audit log is encrypted.)

To configure InterSystems IRIS to start without activating an encryption key, any encrypted databases can only be mounted after startup. To configure a database to be mounted after startup:

  1. Confirm that the database is mounted or mount it:

    1. From the Management Portal home page, go to the Databases page (System Operation > Databases).

    2. Find the database’s row in the table of databases. If it is mounted, there is a Dismount choice in its row; if it is not mounted, there is no Dismount choice and there is a Mount choice.

    3. If it is not mounted, select Mount

    4. On the confirmation screen, select OK. (The database needs to be writable, so do not select the Read Only check box.)

  2. Edit the database’s properties so that it is not mounted at startup:

    1. Go to the Local Databases page (System Administration > Configuration > System Configuration > Local Databases).

    2. Find the database’s row in the table of databases.

    3. Select the database by clicking on its name. This displays the page for editing the database.

    4. On this Edit page, clear the Mount Required at Startup check box.

    5. Click Save.

The database will no longer be mounted at startup. This means that it will no longer require key activation at startup (though it may be required for other reasons.)

Encrypted Journal Files

If the instance uses journaling and you attempt to configure startup not to involve key activation, you may be unable to turn off key activation at startup. These conditions are:

  • The instance is configured to encrypt its journal files.

  • There are open transactions in the journal file (which is fairly likely on a busy system).

If this occurs, you need to suspend the use of encrypted journal files before you change the startup key activation settings. To do this, the procedure is:

  1. On the Database Encryption page (System Administration > Encryption > Database Encryption), change the Encrypt Journal Files setting to No. Leave the Key Activation at Startup setting as it is.

  2. Switch journal files. To do this, click Switch Journal on the Journals page (System Operation > Journals).

Once all open transactions within the encrypted journal files have either been committed or rolled back, you can then change the InterSystems IRIS startup configuration.

Caution:

Even after there are no open transactions, you may need the encrypted journal files to restore a database. For this reason, it is very important that you maintain copies of the key file containing the key used to encrypt these files.

For more information on journal files generally, see Journaling.

Encrypted Audit Log

If the instance has an encrypted audit log and you attempt to configure startup not to involve key activation, InterSystems IRIS displays an error message that an encrypted database is required at startup, such as:

ERROR #1217: Can not disable database encryption key activation at startup. 
Encrypted databases are required at startup: 
C:\InterSystems\IRIS\Mgr\IRISAudit\

The error message refers to encrypted databases because the audit log is stored in the InterSystems IRIS database IRISAUDIT.

The audit log cannot be encrypted if InterSystems IRIS starts without activating an encryption key. To configure startup not to involve key activation, you must change the InterSystems IRIS setting to specify that the instance uses an unencrypted audit log. The procedure is:

  1. Back up the instance’s audit data.

  2. Go to the Database Encryption page (System Administration > Encryption > Database Encryption).

  3. Select Configure Startup Settings, which displays the area with options for configuring InterSystems IRIS startup and other options for encrypted databases.

  4. Under Optionally Encrypted Data, in the Encrypt Audit Log list, click No.

Changing this setting causes InterSystems IRIS to erase any existing audit data, to start using unencrypted auditing immediately, and to write an AuditChange event to the audit log.

Caution:

If you have not backed up audit data, changing the encryption setting for the audit log results in the loss of that existing audit data.

Startup with Interactive Key Activation

This is the default behavior for an instance of InterSystems IRIS if a key has been activated. With interactive key activation, the InterSystems IRIS instance prompts for the location of a key and its associated information during its startup.

Important:

On Windows, interactive key activation is incompatible with configuring InterSystems IRIS as a service that starts automatically as part of system startup.

To configure InterSystems IRIS for interactive key activation:

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

  2. Select Configure Startup Settings. This displays the Startup Options area, which includes the Key Activation at Startup list.

  3. In the Key Activation at Startup list, select Interactive. If the previous value for the field was None, then this displays the page’s Optionally Encrypted Data area.

  4. The fields in this area are:

    • Encrypt IRISTEMP and IRISLOCALDATA Databases — Allows you to specify whether or not the IRISTEMP and IRISLOCALDATA databases are encrypted. To encrypt them, select Yes; to have them be unencrypted, select No.

    • Encrypt Journal Files — Allows you to specify whether or not the instance encrypts its own journal files. To encrypt journal files, select Yes; to have them be unencrypted, select No. This choice depends on startup options because InterSystems IRIS startup creates a new journal file; if you choose encryption, startup requires a key.

      Note:

      This change takes effect the next time that InterSystems IRIS switches journal files. To begin journal file encryption without a restart, switch journal files after completing this page.

    • Encrypt Audit Log — Allows you to specify whether or not InterSystems IRIS encrypts the audit log. To encrypt the audit log, select Yes; to have it be unencrypted, select No. This choice depends on startup options because the InterSystems IRIS startup procedure records various events in the audit log; if you choose encryption, startup requires a key.

      Caution:

      This change takes effect immediately and deletes any existing audit data. Back up the audit database prior to changing this setting; otherwise, audit data will be lost.

  5. Click Save to save the selected settings.

Important:

If InterSystems IRIS is configured to

  • Encrypt IRISTEMP and IRISLOCALDATA, journal files, or the audit log

  • Require an encrypted database at startup

then failure to activate the required encryption key causes an InterSystems IRIS startup failure. If this occurs, use InterSystems IRIS emergency startup mode to configure InterSystems IRIS not to require any encrypted facilities at startup.

Startup with Unattended Key Activation

Startup with unattended key activation, also known as unattended startup, activates a key and potentially mounts encrypted databases at startup time without any human intervention. Successful unattended startup requires that the instance have access to:

  • The encrypted database

  • The database encryption key, either through:

    • The KMIP server that holds the key

    • The database encryption key file that holds the key and the username and password used for unattended database encryption key activation

This section includes the following topics:

Caution:

By making all these items available, the security of the data in InterSystems IRIS becomes entirely dependent on the physical security of the machine(s) holding these elements. If your site cannot ensure this physical security, your data will then be subject to the same level of risk as if it were not encrypted; to avoid this situation, either use interactive startup (which prevents the simultaneous exposure of these elements) or ensure the physical security of the relevant machine(s).

Configuring Unattended Startup Using a Key on a KMIP Server

To configure an InterSystems IRIS instance for unattended startup using a 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 3, Database encryption.

  5. At the next prompt, select option 4, Configure startup options.

  6. At the next prompt, select option 4, Unattended key activation with a KMIP server.

  7. At the KMIP server instance name prompt, enter the name of a KMIP server configuration.

  8. At the prompts that follow, specify what items to encrypt (all of which require an activated key at startup time):

    • Encrypt journal files (no by default) — Allows you to specify whether or not the instance encrypts its own journal files. To encrypt journal files, enter yes; to have them be unencrypted, enter or select no (the default). This choice depends on startup options because InterSystems IRIS startup creates a new journal file; if you choose encryption, startup requires a key.

      This change takes effect the next time that InterSystems IRIS switches journal files. By default, this occurs the next time that InterSystems IRIS restarts. To begin journal file encryption without a restart, switch journal files after completing this page.

    • Encrypt IRISTEMP and IRISLOCALDATA databases (no by default) — Allows you to specify whether or not the IRISTEMP and IRISLOCALDATA databases are encrypted. To encrypt them, enter yes; to have them be unencrypted, enter or select no (the default).

    • Encrypt audit database (no by default) — Allows you to specify whether or not InterSystems IRIS encrypts the audit log. To encrypt the audit log, select yes; to have it be unencrypted, select no (the default). This choice depends on startup options because the InterSystems IRIS startup procedure records various events in the audit log; if you choose encryption, startup requires a key.

      Caution:

      This change takes effect immediately and deletes any existing audit data. Back up the audit database prior to changing this setting; otherwise, audit data will be lost.

  9. The routine then displays the current list of KMIP keys to activate at startup, and then prompts for the next action:

    • To add a key to the list of the startup keys, select option 1, Add key to list.

    • To remove a key from the list of the startup keys, select option 2, Delete key from list.

    • To save the list of startup keys, select option 3, Save list.

  10. When the list contains the desired list of KMIP keys to activate at startup, select option 3, which saves the list.

Configuring Unattended Startup Using a Key in a Key File

Caution:

When you configure InterSystems IRIS for unattended startup, the instance adds another administrator to the database encryption key file; that administrator has a system-generated name and password. Once InterSystems IRIS has modified the key file to add this username and password, InterSystems strongly recommends that you place any copies of the key file only on hardware that can be physically locked in place, such as a lockable CD-ROM or DVD drive in a rack. Further, you should lock and monitor the data center facility where this hardware is stored. Do not store the database encryption key on the same drive as any databases that it is used to encrypt.

To configure an InterSystems IRIS instance for unattended startup with a key in a key file:

  1. You need to have a key currently activated. To activate a key, see Activating a Key.

  2. From the Management Portal home page, go to the Database Encryption page (System Administration > Encryption > Database Encryption).

  3. Select Configure Startup Settings. This displays the Startup Options list.

  4. In Startup Options, select Unattended (NOT RECOMMENDED). This changes the fields that the page displays.

  5. The Startup Options area expands to display three fields. Complete these:

    • Key File — The path of the database encryption key file. This can be an absolute or relative path; if you specify a relative path, it is relative to the InterSystems IRIS installation directory. Click Browse to search for the database encryption key file on the file system.

    • Administrator Name — An administrator for this key file.

    • Password — The administrator’s password.

  6. Complete the fields in the Optionally Encrypted Data area:

    • Encrypt IRISTEMP and IRISLOCALDATA Databases — Allows you to specify whether or not the IRISTEMP and IRISLOCALDATA databases are encrypted. To encrypt them, select Yes; to have them be unencrypted, select No.

    • Encrypt Journal Files — Allows you to specify whether or not the instance encrypts its own journal files. To encrypt journal files, select Yes; to have them be unencrypted, select No. This choice depends on startup options because InterSystems IRIS startup creates a new journal file; if you choose encryption, startup requires a key.

      Note:

      This change takes effect the next time that InterSystems IRIS switches journal files. By default, this occurs the next time that InterSystems IRIS restarts. To begin journal file encryption without a restart, switch journal files after completing this page.

    • Encrypt Audit Log — Allows you to specify whether or not InterSystems IRIS encrypts the audit log. To encrypt the audit log, select Yes; to have it be unencrypted, select No. This choice depends on startup options because the InterSystems IRIS startup procedure records various events in the audit log; if you choose encryption, startup requires a key.

      Caution:

      This change takes effect immediately and deletes any existing audit data. Back up the audit database prior to changing this setting; otherwise, audit data will be lost.

  7. Click Save to save the selected settings.

Temporarily Addressing Issues with Unattended Startup

If InterSystems IRIS is configured to

  • Encrypt IRISTEMP and IRISLOCALDATA, journal files, or the audit log

  • Require an encrypted database at startup

then failure to activate the encryption key causes an InterSystems IRIS startup failure. If this occurs, use InterSystems IRIS emergency startup mode to configure InterSystems IRIS not to require any encrypted facilities at startup.

Encrypt the Databases that Ship with InterSystems IRIS

Each instance of InterSystems IRIS ships with a number of databases. The ability to encrypt and the value of encryption depends on the database:

  • IRISLOCALDATA: Can be encrypted in conjunction with the IRISTEMP database. Encrypting IRISLOCALDATA requires that a key be available at startup, since the database is required at startup time.

  • IRISAUDIT: Can be encrypted. Encrypting IRISAUDIT requires that a key be available at startup, since the database is required at startup time.

  • IRISLIB: Must not be encrypted. (Note that all content in IRISLIB is publicly available.)

  • IRISSYS: Must not be encrypted. If an instance has an encrypted form of this database, InterSystems IRIS cannot start.

  • IRISTEMP: Can be encrypted in conjunction with the IRISLOCALDATA database. Encrypting IRISTEMP requires that a key be available at startup, since the database is required at startup time.

  • USER: Can be encrypted.

Modify Database Encryption Using ^EncryptionKey

There are occasions when you may need to perform encryption management operations that are not available through the Management Portal. Using the ^EncryptionKey utility, you can perform the following actions:

The following is true about the tools used by the ^EncryptionKey utility:

The ^EncryptionKey utility uses a set of encryption management tools:

  • When built-in hardware instructions are available for encryption-related activities, these activities are considerably faster than when using software-based encryption. The encryption management tools use hardware instructions when they are available.

  • The encryption management tools can use keys stored on a KMIP server.

  • The encryption management tools can run in FIPS mode.

Note:

The encryption management tools do not operate on journal files.

Convert an Unencrypted Database to be Encrypted

To convert an unencrypted database to an encrypted database:

  1. Back up the data in the database to be encrypted.

    InterSystems IRIS encrypts data in place. This means that it uses on-disk space for its operations (not copying the database elsewhere and restoring it to its current disk location after successful completion). If the utility is interrupted before completion, the database will be partly encrypted and partly unencrypted, rendering it unusable.

    Caution:

    It is critical that you back up the database before converting it. Failure to do so can result in data being lost.

  2. Activate the key with which you wish to encrypt the database, either from a key file or a KMIP server.

  3. Start the Terminal.

  4. In the %SYS namespace, run the ^EncryptionKey utility.

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

  6. In the database encryption submenu, select option 7, Modify encrypted status of existing database.

  7. In the Database directories submenu, select the database that you wish to modify; databases are listed by their directories. When you select a database, the routine announces if the database is encrypted or not.

  8. If the database is unencrypted, the routine allows you to encrypt it; at the Encrypt database? prompt, enter yes or y. This is not case sensitive.

  9. At the Select key for encryption prompt, select the key that the routine will use to encrypt the database. If the database is currently mounted, the routine then displays this information.

  10. If the database is currently mounted, the routine states this. At the Dismount database prompt, enter yes or y. This is not case sensitive.

    Important:

    Because dismounting and then remounting a database interrupts its operations, take the appropriate precautions to ensure that this does not cause problems.

The routine then encrypts the database. As part of this process, if the database was mounted, the routine displays messages that it has dismounted and mounted the database. When the database is mounted again, encryption is complete.

Convert an Encrypted Database to be Unencrypted

To convert an encrypted database to an unencrypted database:

  1. Back up the data in the database to be unencrypted.

    InterSystems IRIS unencrypts data in place. This means that it uses on-disk space for its operations (not copying the database elsewhere and restoring it to its current disk location after successful completion). If the utility is interrupted before completion, the database will be partly encrypted and partly unencrypted, rendering it unusable.

    Caution:

    It is critical that you back up the database before converting it. Failure to do so can result in data being lost.

  2. Activate the key with which you wish to encrypt the database, either from a key file or a KMIP server.

  3. Start the Terminal.

  4. In the %SYS namespace, run the ^EncryptionKey utility.

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

  6. In the database encryption submenu, select option 7, Modify encrypted status of existing database.

  7. In the Database directories submenu, select the database that you wish to modify; databases are listed by their directories. When you select a database, the routine announces if the database is encrypted or not. If the database is encrypted and its encryption key has not been activated, the routine announces this as well.

  8. If the database is encrypted, the routine allows you to decrypt it; at the Decrypt database? prompt, enter yes or y. This is not case sensitive.

  9. After reporting the encryption key for the database, the routine prompts if you wish to encrypt the database with a different key. Press Enter to simply convert it to a decrypted database and use a new key to encrypt it.

  10. If the database is currently mounted, the routine states this. At the Dismount database prompt, enter yes or y. This is not case sensitive.

    Important:

    Because dismounting and then remounting a database interrupts its operations, take the appropriate precautions to ensure that this does not cause problems.

The routine then decrypts the database. As part of this process, if the database was mounted, the routine displays messages that it has dismounted and mounted the database. When the database is mounted again, decryption is complete.

Convert an Encrypted Database to Use a New Key

To convert an encrypted database to use a new key:

  1. Back up the data in the database to be re-encrypted.

    InterSystems IRIS encrypts data in place. This means that it uses on-disk space for its operations (not copying the database elsewhere and restoring it to its current disk location after successful completion). If the utility is interrupted before completion, the database will be partly encrypted and partly unencrypted, rendering it unusable.

    Caution:

    It is critical that you back up the database before converting it. Failure to do so can result in data being lost.

  2. Activate the keys with which the database is encrypted and with which you wish to re-encrypt the database, either from a key file or a KMIP server.

  3. Start the Terminal.

  4. In the %SYS namespace, run the ^EncryptionKey utility.

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

  6. In the database encryption submenu, select option 7, Modify encrypted status of existing database.

  7. In the Database directories submenu, select the database that you wish to modify; databases are listed by their directories. When you select a database, the routine announces if the database is encrypted or not.

  8. If the database is encrypted, the routine allows you to decrypt it; at the Decrypt database? prompt, enter yes or y. This is not case sensitive.

  9. At the next prompt, which is the Re-encrypt database? prompt, enter yes or y. This is not case sensitive.

  10. At the Select key for encryption prompt, select the key that the routine will use to encrypt the database.

  11. If the database is currently mounted, the routine states this. At the Dismount database prompt, enter yes or y. This is not case sensitive.

    Important:

    Because dismounting and then remounting a database interrupts its operations, take the appropriate precautions to ensure that this does cause problems.

The routine then re-encrypts the database. As part of this process, if the database was mounted, the routine displays messages that it has dismounted and mounted the database. When the database is mounted again, encryption is complete.

FeedbackOpens in a new tab