%SYSTEM.Encryption

Class %SYSTEM.Encryption Extends Help [ Abstract, ProcedureBlock, System = 4 ]

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

Methods

AESGCMEncrypt

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.

AESGCMEncryptInit

ClassMethod AESGCMEncryptInit(key As %String, IV As %String, aad As %String, iswide As %Boolean = 0) As %Status [ CodeMode = expression, Internal ]

This method initializes AES encryption in Galois/Counter mode (GCM). Use with AESGCMEncryptUpdate and AESGCMEncryptResult.

Input parameters:

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.

iswide (optional) - flag indicating plaintext will include wide chars.

AESGCMEncryptUpdate

ClassMethod AESGCMEncryptUpdate(plaintext As %String) As %String [ CodeMode = expression, Internal ]

This method updates AES encryption in Galois/Counter mode (GCM). Use with AESGCMEncryptInit and AESGCMEncryptResult.

Input parameters:

plaintext - String to be encrypted.

Return value: encrypted ciphertext.

AESGCMEncryptResult

ClassMethod AESGCMEncryptResult() As %String [ CodeMode = expression, Internal ]

This method retrieves the tag for AES encryption in Galois/Counter mode (GCM). Use with AESGCMEncryptInit and AESGCMEncryptUpdate.

Return value: encryption tag.

AESGCMDecrypt

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.

AESGCMDecryptInit

ClassMethod AESGCMDecryptInit(key As %String, IV As %String, aad As %String = "", wasWide As %Boolean = 0) As %Status [ CodeMode = expression, Internal ]

This method initializes AES decryption in Galois/Counter mode (GCM). Use with AESGCMDecryptUpdate and AESGCMDecryptValidate.

Input parameters:

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.

AESGCMDecryptUpdate

ClassMethod AESGCMDecryptUpdate(plaintext As %String) As %String [ CodeMode = expression, Internal ]

This method updates AES decryption in Galois/Counter mode (GCM). Use with AESGCMDecryptInit and AESGCMDecryptValidate.

Input parameters:

ciphertext - String to be decrypted.

Return value: decrypted plaintext.

AESGCMDecryptValidate

ClassMethod AESGCMDecryptValidate(tag As %String) As %Boolean [ CodeMode = expression, Internal ]

This method vaidates the tag for AES decryption in Galois/Counter mode (GCM). Use with AESGCMDecryptInit and AESGCMDecryptValidate.

Input parameters:

tag - encryption tag.

Return value:
1 - AES GCM tag validation passed
0 - AES GCM tag validation did not

AESCBCEncrypt

ClassMethod AESCBCEncrypt(plaintext As %String, key As %String, IV As %String) As %String [ CodeMode = expression ]

This method performs AES encryption in Cipher Block Chained (CBC) mode. Use with AESCBCDecrypt. (See Federal Information Processing Standards Publication 197-upd1 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")

AESCBCDecrypt

ClassMethod AESCBCDecrypt(ciphertext As %String, key As %String, IV As %String) As %String [ CodeMode = expression ]

This method performs AES decryption in Cipher Block Chained (CBC) mode. Use with AESCBCEncrypt. (See Federal Information Processing Standards Publication 197-upd1 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).

Return value: Decrypted original plaintext, with block padding removed.

AESCBCEncryptStream

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

AESCBCDecryptStream

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

AESCBCManagedKeyEncrypt

ClassMethod AESCBCManagedKeyEncrypt(Plaintext As %String, KeyID As %String) As %String [ CodeMode = expression ]

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-upd1 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")

AESCBCManagedKeyDecrypt

ClassMethod AESCBCManagedKeyDecrypt(Ciphertext As %String) As %String [ CodeMode = expression ]

This method performs AES decryption in Cipher Block Chained (CBC) mode. Use with AESCBCManagedKeyEncrypt. (See Federal Information Processing Standards Publication 197-upd1 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.

AESCBCManagedKeyEncryptStream

ClassMethod AESCBCManagedKeyEncryptStream(Plaintext As %Stream.Object, Ciphertext As %Stream.Object, KeyID As %String) As %Status [ ProcedureBlock = 1 ]

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-upd1 and NIST Special Publication 200-38A for more information.) Use with AESCBCManagedKeyDecryptStream.

Input parameters:

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.

AESCBCManagedKeyDecryptStream

ClassMethod AESCBCManagedKeyDecryptStream(Ciphertext As %Stream.Object, Plaintext As %Stream.Object) As %Status [ ProcedureBlock = 1 ]

This method performs AES decryption in Cipher Block Chained (CBC) mode on Streams. Use with AESCBCManagedKeyEncryptStream. (See Federal Information Processing Standards Publication 197-upd1 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.

AESDecode

ClassMethod AESDecode(cipher As %String, key As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

Allow for 56-byte header in first block **DEPRECATED**
Use AESCBCEncrypt and AESCBCDecrypt instead for new applications.

Use AES decryption in Electronic Code Book (ECB) mode to decrypt a string. This class method will take an encrypted ciphertext and a key, and return a decrypted plaintext string. The method will decrypt a ciphertext created by the AESEncode method.

Input parameters:

cipher - This is the encrypted string returned by the AESEncode method.

key - Can be any string (8-bit or unicode) up to 32 characters long. When using Unicode strings for keys, each character in the string is treated internally as 2 bytes. Thus a 16 character key (32 bytes) is the largest key which can be used under a unicode system. Note however, that a 32 character key is allowed to be passed to the function: We simply truncate it to 16 characters (32 bytes) when generating the cipher.

InterSystems IRIS will decrypt the string using either 128/192/256 bit decryption depending on the size of the key passed to the function.

If a 16 byte or less key is passed to the decryption function, it is padded with nulls ($c(0)) to make it 16 bytes (128 bits) and the decryption function is called.

If a 17-24 byte key is passed to the decryption function, it is padded with nulls to make it 24 bytes (192 bits), and the decryption function is called.

If a 25-32 byte key is passed to the decryption function, it is padded with nulls to make it 32 bytes (256 bits) and the decryption function is called.

A key greater than 32 bytes will generate a MAXSTRING error.

AESEncode

ClassMethod AESEncode(text As %String, key As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

**DEPRECATED**
Use AESCBCEncrypt and AESCBCDecrypt instead for new applications.

Use AES encryption in Electronic Code Book (ECB) mode to encrypt a string. This class method provides a native AES encryption. The AES encryption standard is based on the Rijndael encryption algorithm. When the text is encrypted it is padded with nulls ($c(0)) to make the entire text string an even multiple of 16 bytes. When the ciphertext is decrypted, the decrypted plaintext will contain any trailing nulls which were used for padding, so a strict string comparison of before encryption and after encryption may fail because of the trailing nulls on the decrypted string. Therefore it is recomended that the user of this function perform their own padding to an even multiple of 16 bytes. This method returns a ciphertext which is an even multiple of 16 bytes. If a unicode string (i.e. string containing characters with ascii values > 255) is encrypted by this method, it will not be able to be decrypted by software outside of InterSystems IRIS. However, the string will be able to be encrypted/decrypted within InterSystems IRIS.

Input parameters:

text - Can be any string (8-bit or unicode) up to 12,000 characters long. A string longer than 12,000 bytes will generate a MAXSTRING error. Since encryption is performed on 16 byte quantities, when the string is encrypted it is padded with nulls ($c(0)) to the next higher multiple of 16 bytes.

InterSystems IRIS will encrypt the string using either 128/192/256 bit encryption depending on the size of the key passed to the function.

If a 16 byte or less key is passed to the encryption function, it is padded with nulls ($c(0)) to make it 16 bytes (128 bits) and the encryption function is called.

If a 17-24 byte key is passed to the encryption function, it is padded with nulls to make it 24 bytes (192 bits), and the encryption function is called.

If a 25-32 byte key is passed to the encryption function, it is padded with nulls to make it 32 bytes (256 bits) and the encryption function is called.

A key greater than 32 bytes will generate a MAXSTRING error.

AESCRCEncode

ClassMethod AESCRCEncode(text As %String, key As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

**DEPRECATED**
Use AESCBCEncrypt and AESCBCDecrypt instead for new applications.

This class methods provide an AES encryption which is compatible only within InterSystems IRIS instances. When the string is encrypted, a header is embedded in the encrypted string which contains a CRC of the text, and the length of the $c(0) padding required to make it an even multiple of 16 bytes. When the cipher is decrypted, trailing $c(0)'s are automatically removed, and the CRC of the decrypted string is checked against the header. If they don't match an ILLEGAL VALUE error is generated. This encryption method is less secure than the native RijndaelEncode method since the generation of the ILLEGAL VALUE error will give an indication of whether a decryption succeded or not. However, it does provide for automatic $c(0) handling, and verifies that the decryption did succeed especially if the encrypted data is passed across an unreliable transport medium.

AESCRCDecode

ClassMethod AESCRCDecode(text As %String, key As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

**DEPRECATED**
Use AESCBCEncrypt and AESCBCDecrypt instead for new applications.

This class methods will decrypt a cipher created by the AESCRCEncode method. When the cipher is decrypted, trailing nulls ($c(0)) are removed from the text, and the crc embedded in the header is checked against the crc of the decrypted string. If they do not match, the string was not successfully decrypted, and an ILLEGAL VALUE error is generated.

AESBase64Encode

ClassMethod AESBase64Encode(text As %String, key As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

**DEPRECATED**
Use AESCBCEncrypt and AESCBCDecrypt with Base64Encode and Base64Decode instead for new applications.

This class method is the same as the AESCRCEncode method, with the additional feature that is will take the encrypted string and encode it in base64 format.

AESBase64Decode

ClassMethod AESBase64Decode(cipher As %String, key As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

**DEPRECATED**
Use AESCBCEncrypt and AESCBCDecrypt with Base64Encode and Base64Decode instead for new applications.

This class method is the same as the AESCRCDecode method, with the additional feature that is will first decode the base 64 string, and then decrypt the result. It will only decode ciphers created with the RijndaelBase64Encode method.

Base32Encode

ClassMethod Base32Encode(Text As %String, Flags As %Integer = 0) As %String [ CodeMode = expression ]

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")

Base32Decode

ClassMethod Base32Decode(Text As %String, Flags As %Integer = 0) As %String [ CodeMode = expression ]

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.

Base32HexEncode

ClassMethod Base32HexEncode(Text As %String, Flags As %Integer = 0) As %String [ CodeMode = expression ]

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")

Base32HexDecode

ClassMethod Base32HexDecode(Text As %String, Flags As %Integer = 0) As %String [ CodeMode = expression ]

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.

Base64Encode

ClassMethod Base64Encode(Text As %String, Flags As %Integer = 0) As %String [ CodeMode = expression ]

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")

Base64Decode

ClassMethod Base64Decode(Text As %String) As %String [ CodeMode = expression ]

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.

GenCryptRand

ClassMethod GenCryptRand(Length As %Integer, RequireBestEntropy As %Boolean) As %String [ CodeMode = expression ]

This is a deterministic cryptographic pseudorandom number generator compliant with FIPS 140-3 requirement SP 800-107 "Recommendation for Applications Using Approved Hash Algorithms" Section 5.5 Random Number (Bit) Generation, which points to SP 800-90A for approved random bit generators.
This implementation is based on the deterministic random bit generator (DRBG) model as described in [NIST SP 800-90A Rev. 1].

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

GenCryptToken

ClassMethod GenCryptToken() As %String [ CodeMode = expression ]

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

LuhnCheckSum

ClassMethod LuhnCheckSum(text As %String) As %String [ CodeMode = expression ]

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

LuhnValidate

ClassMethod LuhnValidate(text As %String) As %Boolean [ CodeMode = expression ]

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

HOTP

ClassMethod HOTP(Secret As %String, MovingFactor As %Integer, CodeDigits As %Integer = 6, AddCheckSum As %Boolean = 0, TruncationOffset As %Integer = 19) As %String [ CodeMode = expression ]

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.

TOTP

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 [ ProcedureBlock = 1 ]

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)

TOTPValidate

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 [ ProcedureBlock = 1 ]

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.

MD5Encode

ClassMethod MD5Encode(text As %String) As %String [ CodeMode = expression, Deprecated, Internal ]

** DEPRECATED ***
This method has been renamed MD5Hash.

MD5Hash

ClassMethod MD5Hash(text As %String) As %String [ CodeMode = expression ]

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.

SHA1Hash

ClassMethod SHA1Hash(text As %String) As %String [ CodeMode = expression ]

This method generates a 20-byte hash using U.S. Secure Hash Algorithm 1 (SHA-1). (See Federal Information Processing Standards Publication 180-4 and Internet Engineering Task Force Request for Comments 3174 for more information.)
Use ToHex on the output to make it a hex string
and use FromHex to decode a hex hash.

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.

SHAHash

ClassMethod SHAHash(bitlength As %Integer, text As %String) As %String [ CodeMode = expression ]

This method generates a hash using one of the U.S. Secure Hash Algorithms. (See Federal Information Processing Standards Publication 180-4 and Internet Engineering Task Force Request for Comments 3174 and 4634 for more information.)
Use ToHex on the output to make it a hex string
and use FromHex to decode a hex hash.

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.

HMACMD5

ClassMethod HMACMD5(text As %String, key As %String) As %String [ CodeMode = expression ]

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

HMACSHA1

ClassMethod HMACSHA1(text As %String, key As %String) As %String [ CodeMode = expression, Deprecated ]

This method generates a 20-byte keyed hash-based message authentication code using U.S. Secure Hash Algorithm 1 (SHA-1). In general, SHA-1 is no longer considered secure. Consider using another algorithm. This warning is based on the Approved Hash Algorithms requirements as described in [NIST SP 800-107r1]. Use $System.Encryption.HMACSHA(160,message, key) if a SHA-1 hash is necessary.

Input parameters:

text - String for which to generate message authentication code.

key - Key.

Return value: 20-byte authentication code.

HMACSHA

ClassMethod HMACSHA(bitlength As %Integer, text As %String, key As %String) As %String [ CodeMode = expression ]

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-4 and 198-1 and Internet Engineering Task Force Request for Comments 2104, 3174, and 4634 for more information.) In general, SHA-1 is no longer considered secure. Consider using another algorithm. This warning is based on the Approved Hash Algorithms requirements as described in [NIST SP 800-107r1].

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.

HMACSHAStream

ClassMethod HMACSHAStream(bitlength As %Integer, input As %Stream.Object, key As %String, ByRef sc As %Status) As %String

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.

PBKDF2

ClassMethod PBKDF2(Password As %String, Iterations As %Integer, Salt As %String, KeyLength As %Integer, bitlength As %Integer = 160) As %String [ CodeMode = expression ]

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. This implementation is based on the PBKDF specification as described in [NIST SP 800-132]. (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

AESKeyWrap

ClassMethod AESKeyWrap(Key As %String, KEK As %String) As %String [ CodeMode = expression ]

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

AESKeyUnwrap

ClassMethod AESKeyUnwrap(EncKey As %String, KEK As %String) As %String [ CodeMode = expression ]

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

SHA1HashStream

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-4 and Internet Engineering Task Force Request for Comments 3174 for more information.)
Note: SHA1 is no longer considered secure. Consider using another algorithm.
Use ToHex on the output to make it a hex string
and use FromHex to decode a hex hash.

Input parameter:
input - Stream to be hashed.

Return value: 20-byte SHA-1 hash.

SHA1HashInput

ClassMethod SHA1HashInput(text As %String) [ CodeMode = expression, Internal ]

This method is used with SHA1HashResult to generate a 20-byte hash using U.S. Secure Hash Algorithm 1 (SHA-1) for Streams. These functions could be used, for example, as follows:

do strm.Rewind()
set len=32000
set str=strm.Read(.len)
while (len>0) {
do $System.Encryption.SHA1HashInput(str)
set len=32000
set str=strm.Read(.len)
}
set hash=$System.Encryption.SHA1HashResult()

Note: SHA1 is no longer considered secure. Consider using another algorithm.

Input parameter:
text - String to be hashed.

SHA1HashResult

ClassMethod SHA1HashResult() As %String [ CodeMode = expression, Internal ]

This method is used with SHA1HashInput to generate a 20-byte hash using U.S. Secure Hash Algorithm 1 (SHA-1). for Streams. See SHA1HashInput for an example of usage.
Note: SHA1 is no longer considered secure. Consider using another algorithm.

Return value: 20-byte SHA-1 hash.

SHAHashStream

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-4 and Internet Engineering Task Force Request for Comments 3174 and 4634 for more information.)
Use ToHex on the output to make it a hex string
and use FromHex to decode a hex hash.

Input parameters:

input - Stream to be hashed.

Return value: String containing hash value, one byte per character.

MD5HashStream

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.

RSASHA1Sign

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: SHA-1 shall not be used in any new digital signature applications that require at least 80 bits of security strength. Furthermore, SHA-1 shall not be used for the generation of digital signatures after the end of 2013 (NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms)
In general, SHA-1 is no longer considered secure. Consider using another algorithm. This warning is based on the Approved Hash Algorithms requirements as described in [NIST SP 800-107r1].

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.

RSASHA1Verify

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: SHA-1 shall not be used in any new digital signature applications that require at least 80 bits of security strength. Furthermore, SHA-1 shall not be used for the generation of digital signatures after the end of 2013 (NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms)
In general, SHA-1 is no longer considered secure. Consider using another algorithm. This warning is based on the Approved Hash Algorithms requirements as described in [NIST SP 800-107r1].

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.

RSASHASign

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-4 Secure Hash Standard (SHS). Note: SHA-1 shall not be used in any new digital signature applications that require at least 80 bits of security strength. Furthermore, SHA-1 shall not be used for the generation of digital signatures after the end of 2013 (NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms)
In general, SHA-1 is no longer considered secure. Consider using another algorithm. This warning is based on the Approved Hash Algorithms requirements as described in [NIST SP 800-107r1].

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.

RSASHAVerify

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-4 Secure Hash Standard (SHS). Note: SHA-1 shall not be used in any new digital signature applications that require at least 80 bits of security strength. Furthermore, SHA-1 shall not be used for the generation of digital signatures after the end of 2013 (NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms)
In general, SHA-1 is no longer considered secure. Consider using another algorithm. This warning is based on the Approved Hash Algorithms requirements as described in [NIST SP 800-107r1].

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.

RSAEncrypt

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.

RSADecrypt

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.

RSASHA1GetLastError

ClassMethod RSASHA1GetLastError() As %String [ Deprecated, Internal ]

**DEPRECATED**
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. A synonym for RSAGetLastError().

Return value: Error string.

RSAGetLastError

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.

RSASize

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.

ECSHASign

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.

ECSHAVerify

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.

ECGetLastError

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.

X509GetField

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.

X509VerifyCertChain

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

CreateEncryptionKey

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.

KMSCreateEncryptionKey

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.

ActivateEncryptionKey

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.

ListEncryptionKeys

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.

DeactivateEncryptionKey

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.

OpenSSLVersion

ClassMethod OpenSSLVersion() As %String

This method returns a string describing the version of the OpenSSL libraries, including the release date.

SHA3HashStream

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.)
Use ToHex on the output to make it a hex string
and use FromHex to decode a hex hash.

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.

HMACSHA3

ClassMethod HMACSHA3(bitlength As %Integer, text As %String, key As %String) As %String [ CodeMode = expression ]

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.

HMACSHA3Stream

ClassMethod HMACSHA3Stream(bitlength As %Integer, input As %Stream.Object, key As %String, ByRef sc As %Status) As %String

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.

SHA3Hash

ClassMethod SHA3Hash(bitlength As %Integer, text As %String) As %String [ CodeMode = expression ]

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.)
Use ToHex on the output to make it a hex string
and use FromHex to decode a hex hash.

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.

RSASHA3Sign

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.

RSASHA3Verify

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.

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.

SHA3HashInput

ClassMethod SHA3HashInput(text As %String) [ CodeMode = expression, Internal ]

This method is used with SHA3HashResult to generate hash string using U.S. Secure Hash Algorithm 3 (SHA-3) for Streams. These functions could be used, for example, as follows:

do strm.Rewind()
set len=32000
set str=strm.Read(.len)
while (len>0) {
do $System.Encryption.SHA3HashInput(224,str)
set len=32000
set str=strm.Read(.len)
}
set hash=$System.Encryption.SHA3HashResult(224)

Input parameter:
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.

SHA3HashResult

ClassMethod SHA3HashResult() As %String [ CodeMode = expression, Internal ]

This method is used with SHA3HashInput to generate a hash string using U.S. Secure Hash Algorithm 3 (SHA-3). for Streams. See SHA3HashInput for an example of usage.

Return value: SHA-3 hash.

CreateAutoEncryptionKeyOnly

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.

ActivateAutoEncryptionKey

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.

ToHex

ClassMethod ToHex(toEncode As %String = "") As %String

Returns an encoding of a byte string as a hexadecimal string.
Returned string is twice the length of the input.

Input parameters:
toEncode - the string that you want to encode.

Return value: An encoded string that is twice the length.

FromHex

ClassMethod FromHex(toDecode As %String = "") As %String

Returns a decoding of a hexadecimal string as a byte string.
Returned string is half the length of the input.

Input parameters:
toDecode - the string that you want to decode.

Return value: A decoded string that is half the length of the input.

Methods​

AESGCMEncrypt​

AESGCMEncryptInit​

AESGCMEncryptUpdate​

AESGCMEncryptResult​

AESGCMDecrypt​

AESGCMDecryptInit​

AESGCMDecryptUpdate​

AESGCMDecryptValidate​

AESCBCEncrypt​

AESCBCDecrypt​

AESCBCEncryptStream​

AESCBCDecryptStream​

AESCBCManagedKeyEncrypt​

AESCBCManagedKeyDecrypt​

AESCBCManagedKeyEncryptStream​

AESCBCManagedKeyDecryptStream​

AESDecode​

AESEncode​

AESCRCEncode​

AESCRCDecode​

AESBase64Encode​

AESBase64Decode​

Base32Encode​

Base32Decode​

Base32HexEncode​

Base32HexDecode​

Base64Encode​

Base64Decode​

GenCryptRand​

GenCryptToken​

LuhnCheckSum​

LuhnValidate​

HOTP​

TOTP​

TOTPValidate​

MD5Encode​

MD5Hash​

SHA1Hash​

SHAHash​

HMACMD5​

HMACSHA1​

HMACSHA​

HMACSHAStream​

PBKDF2​

AESKeyWrap​

AESKeyUnwrap​

SHA1HashStream​

SHA1HashInput​

SHA1HashResult​

SHAHashStream​

MD5HashStream​

RSASHA1Sign​

RSASHA1Verify​

RSASHASign​

RSASHAVerify​

RSAEncrypt​

RSADecrypt​

RSASHA1GetLastError​

RSAGetLastError​

RSASize​

ECSHASign​

ECSHAVerify​

ECGetLastError​

X509GetField​

X509VerifyCertChain​

CreateEncryptionKey​

KMSCreateEncryptionKey​

ActivateEncryptionKey​

ListEncryptionKeys​

DeactivateEncryptionKey​

OpenSSLVersion​

SHA3HashStream​

HMACSHA3​

HMACSHA3Stream​

SHA3Hash​

RSASHA3Sign​

RSASHA3Verify​

SHA3HashInput​

SHA3HashResult​

Methods

AESGCMEncrypt

AESGCMEncryptInit

AESGCMEncryptUpdate

AESGCMEncryptResult

AESGCMDecrypt

AESGCMDecryptInit

AESGCMDecryptUpdate

AESGCMDecryptValidate

AESCBCEncrypt

AESCBCDecrypt

AESCBCEncryptStream

AESCBCDecryptStream

AESCBCManagedKeyEncrypt

AESCBCManagedKeyDecrypt

AESCBCManagedKeyEncryptStream

AESCBCManagedKeyDecryptStream

AESDecode

AESEncode

AESCRCEncode

AESCRCDecode

AESBase64Encode

AESBase64Decode

Base32Encode

Base32Decode

Base32HexEncode

Base32HexDecode

Base64Encode

Base64Decode

GenCryptRand

GenCryptToken

LuhnCheckSum

LuhnValidate

HOTP

TOTP

TOTPValidate

MD5Encode

MD5Hash

SHA1Hash

SHAHash

HMACMD5

HMACSHA1

HMACSHA

HMACSHAStream

PBKDF2

AESKeyWrap

AESKeyUnwrap

SHA1HashStream

SHA1HashInput

SHA1HashResult

SHAHashStream

MD5HashStream

RSASHA1Sign

RSASHA1Verify

RSASHASign

RSASHAVerify

RSAEncrypt

RSADecrypt

RSASHA1GetLastError

RSAGetLastError

RSASize

ECSHASign

ECSHAVerify

ECGetLastError

X509GetField

X509VerifyCertChain

CreateEncryptionKey

KMSCreateEncryptionKey

ActivateEncryptionKey

ListEncryptionKeys

DeactivateEncryptionKey

OpenSSLVersion

SHA3HashStream

HMACSHA3

HMACSHA3Stream

SHA3Hash

RSASHA3Sign

RSASHA3Verify

SHA3HashInput

SHA3HashResult