Skip to main content

Using Data-Element Encryption

Data-element encryption provides a means of encrypting application data at a finer level of granularity than the database as a whole; it is for sensitive data elements whose exposure must be prevented. For example, customer records can exclusively encrypt the credit card field; patient records can exclusively encrypt fields that display test results (such as for HIV testing); or a record that includes a social security number can exclusively encrypt that field.

Data-element encryption is available programmatically (via an API), rather than through the Management Portal. Because it is accessible through an API, you can use it in your application code. You have the option of using data-element encryption with database encryption (though there is no requirement to use both).

For an application to use data-element encryption, the required keys must be available when the application is running. To make a key available, activate it; for details, either see Programmatically Manage Keys or, if using the Portal, see Activating a Key for Data-Element Encryption. When a key is activated, InterSystems IRIS® data platform displays its unique identifier in the table of activated keys; the application then uses this identifier to refer to the key so that it can be loaded from memory for encryption operations. Since there can be up to four keys simultaneously activated, data-element encryption provides the infrastructure for tasks that require multiple keys.

When encrypting data for data-element encryption, InterSystems IRIS stores the encryption key’s unique identifier with the resulting ciphertext. The unique identifier enables the system to identify the key at decryption time using only the ciphertext itself.

This topic describes:

Programmatically Manage Keys

Since data-element encryption is available through an API, there are also a set of calls for managing keys:

These are all methods of the %SYSTEM.EncryptionOpens in a new window class.

Data-Element Encryption Calls

The system methods available for data-element encryption are all methods of the %SYSTEM.EncryptionOpens in a new window class and are:

These method names all begin with “AESCBCManagedKey” because the methods use AES (the Advanced Encryption Standard) in cipher block chaining (CBC) mode and are part of the suite of tools for managed key encryption.

Important:

The AESCBC methods that do not include “ManagedKey” in their names are older methods and cannot be used for these purposes.

$SYSTEM.Encryption.AESCBCManagedKeyEncrypt

The signature of this method as it is usually called is:

$SYSTEM.Encryption.AESCBCManagedKeyEncrypt
        (
        plaintext As %String, 
        keyID As %String, 
        ) 
    As %String
Copy code to clipboard

where:

  • plaintext — The unencrypted text to be encrypted.

  • keyID — The GUID of the data-encryption key to be used to encrypt plaintext.

  • The method returns the encrypted ciphertext.

If the method fails, it throws either the <FUNCTION> or <ILLEGAL VALUE> error. Place calls to this method in a Try-Catch loop; for more information on Try-Catch, see The TRY-CATCH Mechanism.

For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyEncryptOpens in a new window class reference content.

$SYSTEM.Encryption.AESCBCManagedKeyDecrypt

The signature of this method as it is usually called is:

$SYSTEM.Encryption.AESCBCManagedKeyDecrypt
        (
        ciphertext As %String
        ) 
    As %String
Copy code to clipboard

where:

  • ciphertext — The encrypted text to be decrypted.

  • The method returns the decrypted plaintext.

If the method fails, it throws either the <FUNCTION> or <ILLEGAL VALUE> error. Place calls to this method in a Try-Catch loop; for more information on Try-Catch, see The TRY-CATCH Mechanism.

You do not need to include the key ID with this call, as the key ID is associated with the ciphertext to be decrypted.

For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyDecryptOpens in a new window class reference content.

$SYSTEM.Encryption.AESCBCManagedKeyEncryptStream

The signature of this method as it is usually called is:

$SYSTEM.Encryption.AESCBCManagedKeyEncryptStream
        (
        plaintext As %Stream.Object, 
        ciphertext As %Stream.Object, 
        keyID As %String, 
        ) 
    As %Status
Copy code to clipboard

where:

  • plaintext — The unencrypted stream to be encrypted.

  • ciphertext — The variable to receive the encrypted stream.

  • keyID — The GUID of the data-encryption key to be used to encrypt plaintext.

  • The method returns a %StatusOpens in a new window code.

For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyEncryptStreamOpens in a new window class reference content.

$SYSTEM.Encryption.AESCBCManagedKeyDecryptStream

The signature of this method as it is usually called is:

$SYSTEM.Encryption.AESCBCManagedKeyDecryptStream
        (
        ciphertext As %Stream.Object, 
        plaintext As %Stream.Object
        ) 
    As %Status
Copy code to clipboard

where:

  • ciphertext — The encrypted stream to be decrypted.

  • plaintext — The variable to receive the unencrypted stream.

  • The method returns a %StatusOpens in a new window code.

You do not need to include the key ID with this call, as the key ID is associated with the ciphertext to be decrypted.

For more details, see the $SYSTEM.Encryption.AESCBCManagedKeyDecryptStreamOpens in a new window class reference content.

Support for Re-Encrypting Data in Real Time

Data-element encryption allows InterSystems IRIS applications to support re-encrypting an encrypted data element with a new key.

Because an encrypted data element has its encrypting key identifier stored with it, this simplifies the process of re-encrypting data. Given merely the handle to ciphertext and an activated key, an application can perform re-encryption. For example, data-element encryption supports the ability to re-encrypt sensitive data without any downtime; this is particularly useful for users required to perform this action for legal reasons, such as those fulfilling PCI DSS (Payment Card Industry Data Security Standard) requirements.

If you need to re-encrypt data, create a new key and specify to your application that this is the new encryption key. You can then perform an action such as running a background application to decrypt the elements and encrypt them with the new key. This uses the specified key for encryption and always uses the correct key for decryption, since it is stored with the encrypted data.

FeedbackOpens in a new window