Home > Class Reference > ENSLIB namespace > %SYSTEM.Encryption

%SYSTEM.Encryption

abstract class %SYSTEM.Encryption extends %SYSTEM.Help

This class provides class functions to perform data encryption, Base64 encoding, hashing, and generation of message authentication codes.

Method Inventory (Including Private)

Methods (Including Private)

classmethod AESCBCDecrypt(ciphertext As %String, key As %String, IV As %String) as %String
This method performs AES decryption in Cipher Block Chained (CBC) mode. Use with AESCBCEncrypt. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.)

Input parameters:

ciphertext - Encrypted ciphertext, as generated by AESCBCEncrypt.

key - Valid AES key. Key must be 16, 24, or 32 characters long (on Unicode systems, with all character values < 256).

IV - Initialization vector (optional). If this argument is present it must be 16 characters long (on Unicode systems, with all character values < 256). If this argument is omitted (or is an empty string), a null initialization vector is used.

Return value: Decrypted original plaintext, with block padding removed.
classmethod AESCBCDecryptStream(Ciphertext As %Stream.Object, Plaintext As %Stream.Object, Key As %String, IV As %String) as %Status
This method performs AES decryption in Cipher Block Chained (CBC) mode on Streams. Use with AESCBCEncryptStream. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.)

Input parameters:

Ciphertext - Stream to be decrypted.

Plaintext - Decrypted Stream, with block padding removed.

key - Valid AES key. Key must be 16, 24, or 32 characters long (on Unicode systems, with all character values < 256).

IV - Initialization vector (optional). If this argument is present it must be 16 characters long (on Unicode systems, with all character values < 256). If this argument is omitted (or is an empty string), a null initialization vector is used.

classmethod AESCBCEncrypt(plaintext As %String, key As %String, IV As %String) as %String
This method performs AES encryption in Cipher Block Chained (CBC) mode. Use with AESCBCDecrypt. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.)

Input parameters:

plaintext - String to be encrypted. This is padded before encryption to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)

key - Valid AES key. Key must be 16, 24, or 32 characters long (on Unicode systems, with all character values < 256).

IV - Initialization vector (optional). If this argument is present it must be 16 characters long (on Unicode systems, with all character values < 256). If this argument is omitted (or is an empty string), a null initialization vector is used.

Return value: Encrypted ciphertext.

NOTE: To AES-CBC encrypt and Base64 encode Unicode strings that may contain wide characters, UTF-8 encode the string first:

Set text=$ZCONVERT(plaintext,"O","UTF8")
Set text=$SYSTEM.Encryption.AESCBCEncrypt(text,key,IV)
Set ciphertext=$SYSTEM.Encryption.Base64Encode(text)

To decode and decrypt, perform these operations in the reverse order:

Set text=$SYSTEM.Encryption.Base64Decode(ciphertext)
Set text=$SYSTEM.Encryption.AESCBCDecrypt(text,key,IV)
Set plaintext=$ZCONVERT(text,"I","UTF8")
classmethod AESCBCEncryptStream(Plaintext As %Stream.Object, Ciphertext As %Stream.Object, Key As %String, IV As %String) as %Status
This method performs AES encryption in Cipher Block Chained (CBC) mode on Streams. Use with AESCBCDecryptStream. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.)

Input parameters:

Plaintext - Stream to be encrypted. The input is padded to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)

Ciphertext - Encrypted Stream.

key - Valid AES key. Key must be 16, 24, or 32 characters long (on Unicode systems, with all character values < 256).

IV - Initialization vector (optional). If this argument is present it must be 16 characters long (on Unicode systems, with all character values < 256). If this argument is omitted (or is an empty string), a null initialization vector is used.

classmethod AESCBCManagedKeyDecrypt(Ciphertext As %String) as %String
This method performs AES decryption in Cipher Block Chained (CBC) mode. Use with AESCBCManagedKeyEncrypt. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.)

Input parameter:

Ciphertext - Encrypted ciphertext, as generated by AESCBCManagedKeyEncrypt. The key used for encryption must currently be activated.

Return value: Decrypted original plaintext, with block padding removed.
classmethod AESCBCManagedKeyDecryptStream(Ciphertext As %Stream.Object, Plaintext As %Stream.Object) as %Status
This method performs AES decryption in Cipher Block Chained (CBC) mode on Streams. Use with AESCBCManagedKeyEncryptStream. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.)

Input parameters:

Ciphertext - Stream to be decrypted, as generated by AESCBCManagedKeyEncryptStream. The key used for encryption must currently be activated.

Plaintext - Decrypted Stream, with block padding removed.

classmethod AESCBCManagedKeyEncrypt(Plaintext As %String, KeyID As %String) as %String
This method performs AES encryption in Cipher Block Chained (CBC) mode using keys managed by Cache and securely stored in shared memory. A random initialization vector is generated for each encryption operation. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.) Use with AESCBCManagedKeyDecrypt.

Input parameters:

Plaintext - String to be encrypted. This is padded before encryption to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)

KeyID - Key identifier. The specified key must currently be activated.

Return value: Encrypted ciphertext with embedded key identifier and initialization vector.

NOTE: To AES-CBC encrypt and Base64 encode Unicode strings that may contain wide characters, UTF-8 encode the string first:

Set text=$ZCONVERT(plaintext,"O","UTF8")
Set text=$SYSTEM.Encryption.AESCBCManagedKeyEncrypt(text,key)
Set ciphertext=$SYSTEM.Encryption.Base64Encode(text)

To decode and decrypt, perform these operations in the reverse order:

Set text=$SYSTEM.Encryption.Base64Decode(ciphertext)
Set text=$SYSTEM.Encryption.AESCBCManagedKeyDecrypt(text,key)
Set plaintext=$ZCONVERT(text,"I","UTF8")
classmethod AESCBCManagedKeyEncryptStream(Plaintext As %Stream.Object, Ciphertext As %Stream.Object, KeyID As %String) as %Status
This method performs AES encryption in Cipher Block Chained (CBC) mode on Streams using keys managed by Cache and securely stored in shared memory. A random initialization vector is generated for each encryption operation. (See Federal Information Processing Standards Publication 197 and NIST Special Publication 200-38A for more information.) Use with AESCBCManagedKeyDecryptStream.

Input parameters:

Plaintext - Stream to be encrypted. The input is padded to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)

Ciphertext - Encrypted Stream.

KeyID - Key identifier. The specified key must currently be activated.

classmethod AESKeyUnwrap(EncKey As %String, KEK As %String) as %String
This method uses the Advanced Encryption Standard (AES) as a primitive to decrypt an encrypted key using a key-encryption key (KEK).
See: "AES Key Wrap Specification", 16 November 2001. (http://csrc.nist.gov/CryptoToolkit/kms/AES_key_wrap.pdf)

Input parameters:

EncKey - Encrypted key
KEK - Key-encryption key

Return value: Plaintext key
classmethod AESKeyWrap(Key As %String, KEK As %String) as %String
This method uses the Advanced Encryption Standard (AES) as a primitive to encrypt a plaintext key using a key-encryption key (KEK).
See: "AES Key Wrap Specification", 16 November 2001. (http://csrc.nist.gov/CryptoToolkit/kms/AES_key_wrap.pdf)

Input parameters:

Key - Plaintext key
KEK - Key-encryption key

Return value: Encrypted key
classmethod ActivateEncryptionKey(File As %String, Username As %String, Password As %String) as %Status
This method activates an encryption key for use with data element encryption for applications. Note: Must be run from the system namespace.

Input parameters:
File - Name of the key file to use.
Username - Name of an encryption key administrator for this ke