Skip to main content

%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

Methods

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 InterSystems IRIS 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)
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 InterSystems IRIS 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.
Note: To prevent data corruption on Write, if Ciphertext is a file-based Stream it should be an instance of %Stream.FileBinary.

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

classmethod AESGCMDecrypt(ciphertext As %String, key As %String, IV As %String, aad As %String = "", wasWide As %Boolean = 0) as %String
This method performs AES decryption in Galois/Counter mode (GCM). Use with AESGCMEncrypt.

Input parameters:

ciphertext - 16 character tag followed by ciphertext to be decrypted (on Unicode systems, with all character values < 256).

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

IV - Initialization vector (on Unicode systems, with all character values < 256).
When running in FIPS mode, IV must be of length >= 12
Note: repeated IVs cause serious vulnerability.

aad - Additional Associated Data (optional). Additional data associated with the plaintext, also provided during encryption.

wasWide - flag indicating original plaintext included wide chars.

Return value: Decrypted original plaintext.
classmethod AESGCMEncrypt(plaintext As %String, key As %String, IV As %String, aad As %String = "") as %String
This method performs AES encryption in Galois/Counter mode (GCM). Use with AESGCMDecrypt.

Input parameters:

plaintext - String to be encrypted.

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

IV - Initialization vector (on Unicode systems, with all character values < 256).
When running in FIPS mode, IV must be of length >= 12
Note: repeated IVs cause serious vulnerability.

aad - Additional Associated Data (optional). Additional data associated with the plaintext, also provided during decryption.

Return value: 16 character tag followed by ciphertext.
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: NIST SP 800-38F, "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping", December 2012
(https://csrc.nist.gov/publications/detail/sp/800-38f/final)

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: NIST SP 800-38F, "Recommendation for Block Cipher Modes of Operation: Methods for Key Wrapping", December 2012
(https://csrc.nist.gov/publications/detail/sp/800-38f/final)

Input parameters:

Key - Plaintext key
KEK - Key-encryption key

Return value: Encrypted key
classmethod ActivateAutoEncryptionKey(file As %String, Username As %String, Password As %String, iristemp As %Boolean, journal As %Boolean, audit As %Boolean) as %Status
This method activated a database encryption key and key file suitable for use only with unattended database encryption key activation at startup. See CreateAutoEncryptionKeyOnly() for generating such a key. Must be run from the system namespace.

Input parameters:
file - Name of the key file to create.
Username and Password - obtained from CreateAutoEncryptionKeyOnly().
iristemp - boolean 0/1. Encrypt IRISTEMP and IRISLOCALDATA.
journal - boolens 0/1. Encrypt journal files.
audit - boolean 0/1. Encrypt audit database.

Return value: Return status.
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 key file.
Password - Password of this encryption key administrator for this key file. This value should always be obtained from a user prompt, never embedded in application code.

Return value: Return status.
classmethod Base32Decode(Text As %String, Flags As %Integer = 0) as %String
This method performs Base 32 decoding. Use with Base32Encode. (See RFC 4648 for more information.)

Input parameters:
Text - Encoded string, as generated by Base32Encode.
Flags - 0 - Text must be a fully padded "=" octet.
Flags - 1 - Text may not be padded, may contain spaces or "-". Text may also be mixed case. Text entered as 0,1,8 are translated to O,L,B before decoding.

Return value: Decoded original string.
classmethod Base32Encode(Text As %String, Flags As %Integer = 0) as %String
This method performs Base 32 encoding. Use with Base32Decode. (See RFC 4648 for more information.)

Input parameter:
Text - String to be encoded
Flags - 0 - Pad result with "=" to create an octet (Default).
Flags - 1 - Do not pad result with "=".


Return value: Encoded string.

Note: Base 32 encoding is not able to encode a string which contains unicode (2 byte) characters. If you need to Base 32 encode an unicode string, you should first translate the string to UTF8 format, then encode it.

s BinaryText=$ZCONVERT(UnicodeText,"O","UTF8")
s Base32Encoded=$system.Encryption.Base32Encode(BinaryText)
Now to Decode it:
s BinaryText=$system.Encryption.Base32Decode(Base32Encoded)
s UnicodeText=$ZCONVERT(BinaryText,"I","UTF8")
classmethod Base32HexDecode(Text As %String, Flags As %Integer = 0) as %String
This method performs Base 32 Hex decoding. Use with Base32HexEncode. (See RFC 4648 for more information.)

Input parameters:
Text - Encoded string, as generated by Base32HexEncode.
Flags - 0 - Text must be a fully padded "=" octet.
Flags - 1 - Text may not be padded, may contain spaces or "-". Text may also be mixed case.

Return value: Decoded original string.
classmethod Base32HexEncode(Text As %String, Flags As %Integer = 0) as %String
This method performs Base 32 Hex encoding. Use with Base32HexDecode. (See RFC 4648 for more information.)

Input parameter:
Text - String to be encoded
Flags - 0 - Pad result with "=" to create an octet (Default).
Flags - 1 - Do not pad result with "=".


Return value: Encoded string.

Note: Base 32 Hex encoding is not able to encode a string which contains unicode (2 byte) characters. If you need to Base 32 encode an unicode string, you should first translate the string to UTF8 format, then encode it.

s BinaryText=$ZCONVERT(UnicodeText,"O","UTF8")
s Base32HexEncoded=$system.Encryption.Base32HexEncode(BinaryText)
Now to Decode it:
s BinaryText=$system.Encryption.Base32HexDecode(Base32HexEncoded)
s UnicodeText=$ZCONVERT(BinaryText,"I","UTF8")
classmethod Base64Decode(Text As %String) as %String
This method performs Base64 decoding. Use with Base64Encode. (See RFC 4648 for more information.)

Input parameter:
Text - Encoded string, as generated by Base64Encode.

Return value: Decoded original string.
classmethod Base64Encode(Text As %String, Flags As %Integer = 0) as %String
This method performs Base64 encoding. Use with Base64Decode. (See RFC 4648 for more information.)

Input parameter:
Text - String to be encoded
Flags - 0 - Insert CR/LF after every 76 characters (Default)
Flags - 1 - Do not insert CR/LF after every 76 characters. Note: To fulfil RFC 4648, set parameter Flags to 1 - Do not insert CR/LF after every 76 characters.


Return value: Encoded string.

Note: Base 64 encoding is not able to encode a string which contains unicode (2 byte) characters. If you need to Base 64 encode an unicode string, you should first translate the string to UTF8 format, then encode it.

s BinaryText=$ZCONVERT(UnicodeText,"O","UTF8")
s Base64Encoded=$system.Encryption.Base64Encode(BinaryText)
Now to Decode it:
s BinaryText=$system.Encryption.Base64Decode(Base64Encoded)
s UnicodeText=$ZCONVERT(BinaryText,"I","UTF8")
classmethod CreateAutoEncryptionKeyOnly(file As %String, bitlength As %Integer, Description As %String, ByRef Username As %String, ByRef Password As %String) as %Status
This method creates a database encryption key and key file suitable for use only with unattended database encryption key activation at startup. See ActivateAutoEncryptionKey() for activating such a key. Must be run from the system namespace.

Input parameters:
file - Name of the key file to create.
bitlength - Size of the AES keys to create, in bits. Must be 128, 192, or 256.
Description - Description of the key.
Output parameters:
Username and Password - for activating the key via ActivateAutoEncryptionKey().

Return value: Return status.
classmethod CreateEncryptionKey(File As %String, Username As %String, Password As %String, KeyLength As %Integer, ByRef Status As %Status) as %String
This method creates a new encryption key and key file, for use with block-level database encryption and/or data element encryption for applications. Note: Must be run from the system namespace.

Input parameters:
File - Name of the key file to create.
Username - Name of the initial encryption key administrator for the new key file.
Password - Password for the initial encryption key administrator for the new key file. This value should always be obtained from a user prompt, never embedded in application code.
KeyLength - Length in bytes of the data- and key-encryption keys. Must be 16, 24, or 32.
Status - Parameter passed by reference for the return status.

Return value: On success, the unique key identifier of the new encryption key.
classmethod DeactivateEncryptionKey(KeyID As %String) as %Status
This method deactivates an encryption key currently activated for use with data element encryption for applications. Note: Must be run from the system namespace.

Input parameter:
KeyID - Key identifier of key to deactivate.
Return value: Return status.
classmethod ECGetLastError() as %String
This method returns internal error information from the last invocation of ECSHASign(), ECSHAVerify(), if an error occurred and such information was generated.

Return value: Error string.
classmethod ECSHASign(Bitlength As %Integer, Data As %String, Key As %String, Password As %String) as %String
Elliptic Curve SHA Sign

Input parameters:

Bitlength - Length in bits of the desired hash. Legal values are:
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Data - Data to be signed.

Key - EC private key, PEM encoded.

Password - Private key password (optional).

Return value: Digital signature in DER-encoded ASN.1 format.
classmethod ECSHAVerify(Bitlength As %Integer, Data As %String, Signature As %String, PublicKey As %String) as %Integer
Elliptic Curve SHA Verify

Input parameters:

Bitlength - Length in bits of the desired hash. Legal values are:
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Data - Data that was signed.

Signature - Signature to be verified (in DER-encoded ASN.1 format).

PublicKey
The EC public key corresponding to the EC private key that was used to generate the signature, in PEM-encoded format.
(The actual public key, not the name of a file containing it.)

Return value: 1 if the signature was successfully verified, any other value otherwise.
classmethod GenCryptRand(Length As %Integer, RequireBestEntropy As %Boolean) as %String
This is a deterministic cryptographic pseudorandom number generator compliant with FIPS PUB 140-2 "Security Requirements for Cryptographic Modules" Annex C "Approved Random Number Generators" and FIPS PUB 186-2 "Digital Signature Standard (DSS)" Change Notice 1 Appendix 3.1 "Algorithm for Computing m values of x" and Appendix 3.3 "Constructing the function G from the SHA-1". It is useful for generating secure encryption keys and salt. (See Federal Information Processing Standards Publications 140-2 Annex C, 180-2, and 186-2 for more information.)

Input parameters:

Length - Length of random string to generate.

RequireBestEntropy - Require best entropy source for initialization (optional). If this parameter equals 1, the function will return an error unless the generator's internal state has been seeded using the best source of true entropy (OS dependent).

Return value: Random string. (On Unicode systems all values are < 256.)
classmethod GenCryptToken() as %String
GenCryptToken() generates a random eight character numeric string which is to be used as a one-shot security token. The user has only one attempt to enter this token after which it must be discarded. It is composed of numerics only as it was found that users often made errors entering alphanumeric tokens. Return value: 8-character numeric security token
classmethod HMACMD5(text As %String, key As %String) as %String
This method generates a 16-byte keyed hash-based message authentication code using the MD5 message digest algorithm.
Not available when running in FIPS mode
(See Federal Information Processing Standards Publication 198 and Internet Engineering Task Force Request for Comments 1321 and 2104 for more information.)

Input parameters:

text - String for which to generate message authentication code.

key - Key.

Return value: 16-byte authentication code.
classmethod HMACSHA(bitlength As %Integer, text As %String, key As %String) as %String
This method generates a keyed hash-based message authentication code using one of the U.S. Secure Hash Algorithms. (See Federal Information Processing Standards Publications 180-2 and 198 and Internet Engineering Task Force Request for Comments 2104, 3174, and 4634 for more information.)

Input parameters:

bitlength - Length in bits of the desired message authentication code. Legal values are:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

text - String for which to generate message authentication code.

key - Key.

Return value: String containing message authentication code, one byte per character.
classmethod HMACSHA1(text As %String, key As %String) as %String
This method generates a 20-byte keyed hash-based message authentication code using U.S. Secure Hash Algorithm 1 (SHA-1). (See Federal Information Processing Standards Publications 180-2 and 198 and Internet Engineering Task Force Request for Comments 2104 and 3174 for more information.)

Input parameters:

text - String for which to generate message authentication code.

key - Key.

Return value: 20-byte authentication code.
classmethod HMACSHA3(bitlength As %Integer, text As %String, key As %String) as %String
This method generates a keyed hash-based message authentication code using one of the U.S. Secure Hash Algorithms - 3. (See Federal Information Processing Standards Publications 202 for more information.)

Input parameters:

bitlength - Length in bits of the desired message authentication code. Legal values are:
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

text - String for which to generate message authentication code.

key - Key.

Return value: String containing message authentication code, one byte per character.
classmethod HMACSHA3Stream(bitlength As %Integer, input As %Stream.Object, key As %String, ByRef sc As %Status) as %String
This method generates a keyed hash-based message authentication code using one of the U.S. Secure Hash Algorithms - 3. (See Federal Information Processing Standards Publications 202 for more information.)

Input parameters:

bitlength - Length in bits of the desired hash. Legal values are:
224 (SHA3-224)
256 (SHA3-256)
384 (SHA3-384)
512 (SHA3-512)

input - Stream for which to generate message authentication code.

key - Key.

Return value: String containing message authentication code, one byte per character.
classmethod HMACSHAStream(bitlength As %Integer, input As %Stream.Object, key As %String, ByRef sc As %Status) as %String
This method generates a keyed hash-based message authentication code using one of the U.S. Secure Hash Algorithms. (See Federal Information Processing Standards Publications 180-2 and 198 and Internet Engineering Task Force Request for Comments 2104, 3174, and 4634 for more information.)

Input parameters:

bitlength - Length in bits of the desired hash. Legal values are:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

input - Stream for which to generate message authentication code.

key - Key.

Return value: String containing message authentication code, one byte per character.
classmethod HOTP(Secret As %String, MovingFactor As %Integer, CodeDigits As %Integer = 6, AddCheckSum As %Boolean = 0, TruncationOffset As %Integer = 19) as %String
An HMAC-Based One-Time Password Algorithm.
This change implements the the HOTP algorithm which is an HMAC-Based One-Time Password Algorithm. The specification for the algorithm is found in RFC 4226.
https://tools.ietf.org/html/rfc4226

Parameters:
Secret - Text string shared between the client and authentication module, typically 160 bits.
MovingFactor - The counter, time, or other value that changes on a per use basis.
CodeDigits - (default 6) Number of digits to return in the HOTP value. Must be between 6 and 8.
AddCheckSum - 0/1 (default 0) - Whether a Luhn Checksum should be added to the end of the HOTP value. If 1, then the number of digits returned is CodeDigits+1.
TruncationOffset - (default 19, dynamic truncation) the offset into the MAC result to begin truncation. If this value is out of the range of 0 ... 15, then dynamic truncation will be used. Dynamic truncation is when the last 4 bits of the last byte of the MAC are used to determine the start offset.
classmethod KMSCreateEncryptionKey(File As %String, Server As %String, ServerKeyID As %String, KeyLength As %Integer, ByRef Backup As %String, Region As %String = "", Description As %String = "", ByRef Env As %String, ByRef Status As %Status) as %String
This method creates a new encryption key and key file via a given KMS server, for use with block-level database encryption and/or data element encryption for applications. Note: Must be run from the system namespace.

Input parameters:
File - Name of the key file to create.
Server - Name of the KMS server. Currently accepted values are "AWS" and "Azure" (case insensitive).
ServerKeyID - Key ID of the master key on the server.
KeyLength - Length in bytes of the data- and key-encryption keys. Must be 16, 24, or 32.
Backup - (Passed by reference, optional) info for creating a backup key file. If specified, it should contain the following entries: Backup("File"): Name of the backup key file.
Backup("Username"): Name of the initial encryption key administrator for the backup key file.
Backup("Password"): Password for the initial encryption key administrator for the backup key file. This value should always be obtained from a user prompt, never embedded in application code.
Backup("Desc"): (optional) Description of the key
Region - (AWS only) Name of the region, e.g., "us-east-2".
Description - (optional) Description of the key.
Env - (Passed by reference, optional) to specify environment variables to be set for key activation (currently for AWS only), e.g., Env("AWS_CONFIG_FILE")=(path of AWS config file), Env("AWS_SHARED_CREDENTIALS_FILE")=(path of AWS credential file), etc.
Status - Parameter passed by reference for the return status.
Return value: On success, the unique key identifier of the new encryption key.
classmethod ListEncryptionKeys() as %String
This method returns a comma-separated list of the key identifiers of encryption keys currently activated for use with data element encryption for applications. Note: Must be run from the system namespace.

Return value: Comma-separated list of key identifiers.
classmethod LuhnCheckSum(text As %String) as %String
Calculate a checksum for a numeric string.
This method will calculate a checksum for a numeric string using the Luhn Algorithm.
More details about the algorithm can be found at http://en.wikipedia.org/wiki/Luhn_algorithm


Input parameter:
Text - String containing nothing but numbers.


Return value: 1 character string containing the checksum.

Examples:
s CheckSum=$SYSTEM.Encryption.LuhnCheckSum("37127922268703")
CheckSum=1
s Validate=$SYSTEM.Encryption.LuhnValidate("371279222687031")
Validate=1
classmethod LuhnValidate(text As %String) as %Boolean
Validate that a numeric string passes the Luhn Algorithm.
This method will validate that a numeric string passes the Luhn Algorithm.
This algorithm is typically used to validate the entry of credit card numbers.
More details about the algorithm can be found at http://en.wikipedia.org/wiki/Luhn_algorithm


Input parameter:
Text - String containing nothing but numbers.


Return values:
0 - String does not pass the Luhn Algorithm.
1 - String passes the Luhn Algorithm.

Examples:
s CheckSum=$SYSTEM.Encryption.LuhnCheckSum("37127922268703")
CheckSum=1
s Validate=$SYSTEM.Encryption.LuhnValidate("371279222687031")
Validate=1
s Validate=$SYSTEM.Encryption.LuhnValidate("371279222687039")
Validate=0
classmethod MD5Hash(text As %String) as %String
This method generates a 16-byte hash using the MD5 message digest algorithm.
Not available when running in FIPS mode
(See Internet Engineering Task Force Request for Comments 1321 for more information.)
Note: MD5 is no longer considered secure. Consider using another algorithm.

Input parameter:
text - String to be hashed.

Return value: 16-byte MD5 hash.
classmethod MD5HashStream(input As %Stream.Object, ByRef sc As %Status) as %String
This method generates the hash of a Stream using the MD5 algorithm.
Not available when running in FIPS mode
Note: MD5 is no longer considered secure. Consider using another algorithm.
(See the Internet Engineering Task Force Request for Comments 1321 for more information.)

Input parameter:

input - Stream to be hashed.

Return value: String containing hash value, one byte per character.
classmethod OpenSSLVersion() as %String
This method returns a string describing the version of the OpenSSL libraries, including the release date.
classmethod PBKDF2(Password As %String, Iterations As %Integer, Salt As %String, KeyLength As %Integer, bitlength As %Integer = 160) as %String
This method generates an encryption key from a password, iteration count, and salt. It uses Password-Based Key Derivation Function 2 (PBKDF2) with HMAC-SHA. (See RSA Laboratories Public-Key Cryptography Standards #5 and Federal Information Processing Standards Publications 180-4 and 198-1 for more information.)

Input parameters:

Password - User's password

Iterations - Number of iterations to run

Salt - Fixed random salt for this user

KeyLength - Length of encryption key to generate

bitlength - Length in bits of the underlying HMAC-SHA function (optional). Legal values are:
160 (SHA-1) (default)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Return value: Encryption key
classmethod RSADecrypt(Ciphertext As %String, Key As %String, Password As %String, Encoding As %Integer) as %String
This method performs RSA decryption as specified in PKCS #1 v2.1: RSA Cryptography Specifications, section 7 Encryption Schemes. This is intended primarily for encryption of temporary symmetric encryption keys.

Input parameters:

Ciphertext - Data to be decrypted.

Key - RSA private key corresponding to the RSA public key that was used for encryption, PEM encoded.

Password - Private key password (optional).

Encoding - PKCS #1 v2.1 encoding method (optional):
1 = OAEP (default)
2 = PKCS1-v1_5

Return value: Plaintext.
classmethod RSAEncrypt(Plaintext As %String, Certificate As %String, CAfile As %String, CRLfile As %String, Encoding As %Integer) as %String
This method performs RSA encryption as specified in PKCS #1 v2.1: RSA Cryptography Specifications, section 7 Encryption Schemes.

Input parameters:

Plaintext - Data to be encrypted.

Certificate/PublicKey - Either
An X.509 certificate containing the RSA public key to be used for encryption, in PEM encoded or binary DER format.
or
The RSA public key to be used for encryption, in PEM-encoded PKCS#1 RSAPublicKey format or PEM-encoded SubjectPublicKeyInfo format.
(The actual certificate or public key, not the name of a file containing it.)
Note that the length of the plaintext can not be greater than the length of the modulus of the RSA public key minus 42 bytes.

CAfile - The name of a file containing trusted Certificate Authority X.509 Certificates in PEM-encoded format, one of which was used to sign the Certificate (optional).

CRLfile - The name of a file containing X.509 Certificate Revocation Lists in PEM-encoded format that should be checked to verify the status of the Certificate (optional).

Encoding - PKCS #1 v2.1 encoding method (optional):
1 = OAEP (default)
2 = PKCS1-v1_5


Return value: Ciphertext.
classmethod RSAGetLastError() as %String
This method returns internal error information from the last invocation of RSASHA1Sign(), RSASHA1Verify(), RSAEncrypt(), or RSADecrypt(), if an error occurred and such information was generated.

Return value: Error string.
classmethod RSASHA1Sign(Data As %String, Key As %String, Password As %String) as %String
This method generates an RSA-SHA1 digital signature as specified in PKCS #1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5.
Note: SHA1 is no longer considered secure. Consider using another algorithm.

Input parameters:

Data - Data to be signed.

Key - RSA private key, PEM encoded.

Password - Private key password (optional).

Return value: Digital signature.

Note: SHA-1 is deprecated for digital signature generation.
classmethod RSASHA1Verify(Data As %String, Signature As %String, Certificate As %String, CAfile As %String, CRLfile As %String) as %Boolean
This method verifies an RSA-SHA1 digital signature as specified in PKCS #1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5.
Note: SHA1 is no longer considered secure. Consider using another algorithm.

Input parameters:

Data - Data that was signed.

Signature - Signature to be verified.

Certificate - An X.509 certificate containing the RSA public key corresponding to the RSA private key that was used to generate the signature, in PEM encoded or binary DER format.

CAfile - The name of a file containing trusted Certificate Authority X.509 Certificates in PEM-encoded format, one of which was used to sign the Certificate (optional).

CRLfile - The name of a file containing X.509 Certificate Revocation Lists in PEM-encoded format that should be checked to verify the status of the Certificate (optional).

Return value: 1 if the signature was successfully verified, 0 otherwise.

Note: This function has an alternate 4-argument usage, where the third and fourth arguments are the RSA public key modulus and exponent in binary format.
classmethod RSASHA3Sign(Bitlength As %Integer, Data As %String, Key As %String, Password As %String) as %String
This method generates an RSA-SHA-3 digital signature as specified in RFC 3447 PKCS #1 v2.1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5, using any of the SHA-3 hash functions defined in FIPS 202 Secure Hash Standard (SHS).

Note: Not available on systems without OpenSSL v1.1.x

Input parameters:

Bitlength - Length in bits of the desired hash. Legal values are:
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Data - Data to be signed.

Key - RSA private key, PEM encoded.

Password - Private key password (optional).

Return value: Digital signature.
classmethod RSASHA3Verify(Bitlength As %Integer, Data As %String, Signature As %String, Certificate As %String, CAfile As %String, CRLfile As %String) as %Boolean
This method verifies an RSA-SHA-3 digital signature as specified in RFC 3447 PKCS #1 v2.1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5, using any of the SHA-3 hash functions defined in FIPS 202 Secure Hash Standard (SHS).

Note: Not available on systems without OpenSSL v1.1.x

Input parameters:

Bitlength - Length in bits of the desired hash. Legal values are:
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Data - Data that was signed.

Signature - Signature to be verified.

Certificate/PublicKey - Either
An X.509 certificate containing the RSA public key corresponding to the RSA private key that was used to generate the signature, in PEM encoded or binary DER format.
or
The RSA public key corresponding to the RSA private key that was used to generate the signature, in PEM-encoded PKCS#1 RSAPublicKey format or PEM-encoded SubjectPublicKeyInfo format.
(The actual certificate or public key, not the name of a file containing it.)

CAfile - The name of a file containing trusted Certificate Authority X.509 Certificates in PEM-encoded format, one of which was used to sign the Certificate (optional).

CRLfile - The name of a file containing X.509 Certificate Revocation Lists in PEM-encoded format that should be checked to verify the status of the Certificate (optional).

Return value: 1 if the signature was successfully verified, 0 otherwise.

Note: This function has an alternate 5-argument usage, where the fourth and fifth arguments are the RSA public key modulus and exponent in binary format.
classmethod RSASHASign(Bitlength As %Integer, Data As %String, Key As %String, Password As %String) as %String
This method generates an RSA-SHA digital signature as specified in RFC 3447 PKCS #1 v2.1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5, using any of the SHA hash functions defined in FIPS 180-3 Secure Hash Standard (SHS).

Input parameters:

Bitlength - Length in bits of the desired hash. Legal values are:
160 (SHA-1) Note: SHA-1 is deprecated for digital signature generation.
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Data - Data to be signed.

Key - RSA private key, PEM encoded.

Password - Private key password (optional).

Return value: Digital signature.
classmethod RSASHAVerify(Bitlength As %Integer, Data As %String, Signature As %String, Certificate As %String, CAfile As %String, CRLfile As %String) as %Boolean
This method verifies an RSA-SHA digital signature as specified in RFC 3447 PKCS #1 v2.1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5, using any of the SHA hash functions defined in FIPS 180-3 Secure Hash Standard (SHS).

Input parameters:

Bitlength - Length in bits of the desired hash. Legal values are:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

Data - Data that was signed.

Signature - Signature to be verified.

Certificate/PublicKey - Either
An X.509 certificate containing the RSA public key corresponding to the RSA private key that was used to generate the signature, in PEM encoded or binary DER format.
or
The RSA public key corresponding to the RSA private key that was used to generate the signature, in PEM-encoded PKCS#1 RSAPublicKey format or PEM-encoded SubjectPublicKeyInfo format.
(The actual certificate or public key, not the name of a file containing it.)

CAfile - The name of a file containing trusted Certificate Authority X.509 Certificates in PEM-encoded format, one of which was used to sign the Certificate (optional).

CRLfile - The name of a file containing X.509 Certificate Revocation Lists in PEM-encoded format that should be checked to verify the status of the Certificate (optional).

Return value: 1 if the signature was successfully verified, 0 otherwise.

Note: This function has an alternate 5-argument usage, where the fourth and fifth arguments are the RSA public key modulus and exponent in binary format.
classmethod RSASize(Input As %String, Password As %String) as %Integer
This method returns the length of the modulus of an RSA key. Intended for use with RSAEncrypt().

Input parameters:

Input - An X.509 digital certificate containing an RSA public key, in PEM encoded or binary DER format, or an RSA private key, PEM encoded.

Password - Private key password (optional).

Return value: The length of the modulus of the RSA key, in bytes.
classmethod SHA1Hash(text As %String) as %String
This method generates a 20-byte hash using U.S. Secure Hash Algorithm 1 (SHA-1). (See Federal Information Processing Standards Publication 180-2 and Internet Engineering Task Force Request for Comments 3174 for more information.)
Note: SHA1 is no longer considered secure. Consider using another algorithm.

Input parameter:
text - String to be hashed.

Return value: 20-byte SHA-1 hash.
classmethod SHA1HashStream(input As %Stream.Object, ByRef sc As %Status) as %String
This method generates a 20-byte hash of a Stream using U.S. Secure Hash Algorithm 1 (SHA-1). (See Federal Information Processing Standards Publication 180-2 and Internet Engineering Task Force Request for Comments 3174 for more information.)
Note: SHA1 is no longer considered secure. Consider using another algorithm.

Input parameter:
input - Stream to be hashed.

Return value: 20-byte SHA-1 hash.
classmethod SHA3Hash(bitlength As %Integer, text As %String) as %String
This method generates a hash using one of the U.S. Secure Hash Algorithms - 3. (See Federal Information Processing Standards Publication 202 for more information.)

Input parameters:

bitlength - Length in bits of the desired hash. Legal values are:
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

text - String to be hashed.

Return value: String containing hash value, one byte per character.
classmethod SHA3HashStream(bitlength As %Integer, input As %Stream.Object, ByRef sc As %Status) as %String
This method generates a hash of a Stream using one of the U.S. Secure Hash Algorithms - 3. (See Federal Information Processing Standards Publication 202 for more information.)

Input parameters:

bitlength - Length in bits of the desired hash. Legal values are:
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

input - Stream to be hashed.

Return value: String containing hash value, one byte per character.
classmethod SHAHash(bitlength As %Integer, text As %String) as %String
This method generates a hash using one of the U.S. Secure Hash Algorithms. (See Federal Information Processing Standards Publication 180-2 and Internet Engineering Task Force Request for Comments 3174 and 4634 for more information.)

Input parameters:

bitlength - Length in bits of the desired hash. Legal values are:
160 (SHA-1 Note: SHA1 is no longer considered secure. Consider using another algorithm.)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

text - String to be hashed.

Return value: String containing hash value, one byte per character.
classmethod SHAHashStream(bitlength As %Integer, input As %Stream.Object, ByRef sc As %Status) as %String
This method generates a hash of a Stream using one of the U.S. Secure Hash Algorithms. (See Federal Information Processing Standards Publication 180-2 and Internet Engineering Task Force Request for Comments 3174 and 4634 for more information.)

Input parameters:

bitlength - Length in bits of the desired hash. Legal values are:
160 (SHA-1 Note: SHA1 is no longer considered secure. Consider using another algorithm.)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)

input - Stream to be hashed.

Return value: String containing hash value, one byte per character.
classmethod TOTP(Secret As %String, UTCTimeStamp As %String = $ztimestamp, TimeStep As %Integer = 30, CodeDigits As %Integer = 6, AddCheckSum As %Boolean = 0, TruncationOffset As %Integer = 19) as %String
Generate a TOTP: Time-Based One-Time Password.
This method implements the the TOTP algorithm which is an HMAC-Based One-Time Password Algorithm. The specification for the algorithm is found in RFC 6238.
https://tools.ietf.org/html/rfc6238

Parameters:
Secret - Text string shared between the client and authentication module, typically 160 bits.
UTCTimeStamp - (default - current $ZTIMESTAMP) UTC time in $H format used to calculate the password.
TimeStep - (default - 30) Waiting time in seconds until the next password is generated. See section 5.2. Validation and Time-Step Size in RFC 6238 for how this value is used.
CodeDigits - (default 6) Number of digits to return in the HOTP value. Must be between 6 and 8.
AddCheckSum - 0/1 (default 0) - Whether a Luhn Checksum should be added to the end of the HOTP value. If 1, then the number of digits returned is CodeDigits+1. Note that if a check sum is added, it must be removed from the TOTP value before the Validate() method is called.
TruncationOffset - (default 19, dynamic truncation) the offset into the MAC result to begin truncation. If this value is out of the range of 0 ... 15, then dynamic truncation will be used. Dynamic truncation is when the last 4 bits of the last byte of the MAC are used to determine the start offset. This is typically not used.
Notes:
Typically the only parameter passed into this method is the Secret, and the default taken for all the other parameters.

Examples:
Generate a TOTP password for the current time. This generates a 6 digit TOTP value which will pass the TOTPValidate() method for between 61 and 90 seconds (3 TimeStepLimits * 30).
s TOTP=$SYSTEM.Encryption.TOTP("12345678901234567890")
s Valid=$SYSTEM.Encryption.TOTPValidate(TOTP,"12345678901234567890")
Generate a TOTP password for the current time. This generates an 8 digit TOTP value which will pass the TOTPValidate() method for between 61 and 90 seconds (3 TimeStepLimits * 30). Note that if the TimeStep and CodeDigits parameters are specified, then these same values must also be used in the TOTPValidate() method.
s TOTP=$SYSTEM.Encryption.TOTP("12345678901234567890",,,8)
s Valid=$SYSTEM.Encryption.TOTPValidate(TOTP,"12345678901234567890",,,,8)

classmethod TOTPValidate(TOTP As %String, Secret As %String, TOTPLastValidPasswords As %String = "", UTCTimeStamp As %String = $ztimestamp, TimeStep As %Integer = 30, TimeStepLimit As %Integer = $$$TOTPDefaultTimeStepLimit, CodeDigits As %Integer = 6, AddCheckSum As %Boolean = 0, TruncationOffset As %Integer = 19) as %Boolean
Validate TOTP: Time-Based One-Time Password.
This method validates a TOTP Time-Based One-Time Password. The TOTP password generation specification is RFC 6238.
https://tools.ietf.org/html/rfc6238

Parameters:
TOTP - Time-Based one-time password to validate.
Secret - Text string shared between the client and authentication module, typically 160 bits.
TOTPLastValidPasswords - Comma delimited string of valid TOTP passwords which were entered by the user. Once a TOTP password is used once, it can't be used again within the time Step. You must pass in the last TimeStepLimit number of valid TOTP passwords. So If TimeStepLimit is 3, you must pass in the last 3 valid TOTP passwords to this call in the format "PW1,PW2,PW3" where PW1 is the oldest PW..
UTCTimeStamp - (default - current $ZTIMESTAMP) UTC time in $H format used to calculate the password.
TimeStep - (default - 30) Waiting time in seconds until the next password is generated.
See section 5.2. Validation and Time-Step Size in RFC 6238 for how this value is used.
TimeStepLimit - (default - 3) Number of time steps a password is valid for.
See section 5.2. Validation and Time-Step Size in RFC 6238 for how this value is used.
CodeDigits - (default 6) Number of digits to use in generating and comparing the TOTP value. Must be between 6 and 8.
AddCheckSum - 0/1 (default 0) - Whether a Luhn Checksum should be added to the end of the TOTP value. If 1, then the number of digits returned is CodeDigits+1.
TruncationOffset - (default 19, dynamic truncation) the offset into the MAC result to begin truncation. If this value is out of the range of 0 ... 15, then dynamic truncation will be used. Dynamic truncation is when the last 4 bits of the last byte of the MAC are used to determine the start offset. This is typically not used.

This method can be used as an authentication method with Google Authenticator. First create a unique 160 bit secret as follows:

Set Secret=$System.Encryption.GenCryptRand(20)

Now convert the secret to base 32.

Set SecretBase32=$SYSTEM.Encryption.Base32Encode(Secret)

Now open the Google Authenticator application on your phone. Select to set up an account. Then enter an account name of your choosing, and the base 32 representation of the secret. Make sure the option is time based. Now as the verification code changes, you can validate it using the Secret generated above as follows:

Set Valid=$SYSTEM.Encryption.TOTPValidate(GoogleVerificationCode,Secret)

You can also enter the Secret into Google Authenticator by scanning a QR code which you can generate. First generate the SecretBase32 as described above. Then create an "Issuer" which further identifies the account in Google Authenticatior. Then generate a QR Code in a file as follows:

Set FileName="qrcode.png" Set Account="Userxxx"
Set Issuer="InterSystemsIRIS-"_##class(%SYS.System).GetNodeName(1)_"-"_##class(%SYS.System).GetInstanceName()
Set QRString="otpauth://totp/"_Issuer_":"_Account_"?secret="_SecretBase32_"&issuer="_Issuer
Set Status=##Class(%SYS.QRcode).GenerateFile(QRString,FileName)

Now in Google Authenticator you can create a new account by scanning the QR code.
classmethod X509GetField(Certificate As %String, Field As %String) as %String
This methods returns a string representation of the value of a field in an X.509 digital certificate.

Input parameters:

Certificate - An X.509 digital certificate, in PEM encoded or binary DER format.

Field - The name of the field to be extracted. Legal field names, the sections of RFC 5280 that describe the corresponding fields, the ASN.1 types of the fields, and the value types returned by this function are:
"SerialNumber", 4.1.2.2, INTEGER, decimal character string
"Issuer", 4.1.2.4, X.501 Name, RFC 2253 conformant string representation
"ValidityNotBefore", 4.1.2.5, UTCTime or GeneralizedTime, ODBC time string ("yyyy-MM-dd hh:mm:ss")
"ValidityNotAfter", 4.1.2.5, UTCTime or GeneralizedTime, ODBC time string ("yyyy-MM-dd hh:mm:ss")
"Subject", 4.1.2.6, X.501 Name, RFC 2253 conformant string representation
"SubjectKeyIdentifier", 4.2.1.2, OCTET STRING, byte string
"RSAPublicKeyModulus", 4.1.2.7, BIT STRING, byte string
"RSAPublicKeyExponent", 4.1.2.7, BIT STRING, byte string

Also supported are all certificate extensions, using the syntax "Extension:name". A string representation of the extension, if present, is returned. Legal names and the sections of RFC 5280 that describe the corresponding field follow:
"Extension:authorityKeyIdentifier", 4.2.1.1
"Extension:subjectKeyIdentifier", 4.2.1.2
"Extension:keyUsage", 4.2.1.3
"Extension:certificatePolicies", 4.2.1.4
"Extension:policyMappings", 4.2.1.5
"Extension:subjectAltName", 4.2.1.6
"Extension:issuerAltName", 4.2.1.7
"Extension:subjectDirectoryAttributes", 4.82.1.
"Extension:basicConstraints", 4.2.1.9
"Extension:nameConstraints", 4.2.1.10
"Extension:policyConstraints", 4.2.1.11
"Extension:extendedKeyUsage", 4.2.1.12
"Extension:crlDistributionPoints", 4.2.1.13
"Extension:inhibitAnyPolicy", 4.2.1.14
"Extension:freshestCRL", 4.2.1.15
"Extension:authorityInfoAccess", 4.2.2.1
"Extension:subjectInfoAccess", 4.2.2.2
"Extension:nsCertType", deprecated

Return value: The value of the field.
classmethod X509VerifyCertChain(Certificate As %String, CAFile As %String, CRLFile As %String) as %String
This method verifies an X.509 certificate chain with a certificate, a trusted CA certificate file, and optionally a CRL file. It is intended to be used to verify that two SSL/TLS configurations have X.509 certificates and CA files that can be used to establish an SSL/TLS session between them. Note that this method verifies only the certificates, CA files, and optionally CRL files, and not other properties of the SSL/TLS configurations. Intended use case, for a Client verifying that it can connect to, and accept connections from, a Server:

Client sends Client certificate to Server
Server verifies Client certificate with Server CA file
Server returns result of verification, along with Server certificate
Client verifies Server certificate with Client CA file
Client sends result of verification to Server

Input parameters:

Certificate - X.509 certificate in PEM or DER format

CAFile - Name of a file containing trusted Certificate Authority certificates

CRLFile - Name of a file containing Certificate Revocation lists (optional)

Return value: the string "OK" if verification is successful, otherwise a ";" delimited list of error strings

Inherited Members

Inherited Methods

FeedbackOpens in a new tab