%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
- AESCBCDecrypt()
- AESCBCDecryptStream()
- AESCBCEncrypt()
- AESCBCEncryptStream()
- AESCBCManagedKeyDecrypt()
- AESCBCManagedKeyDecryptStream()
- AESCBCManagedKeyEncrypt()
- AESCBCManagedKeyEncryptStream()
- AESKeyUnwrap()
- AESKeyWrap()
- ActivateEncryptionKey()
- Base32Decode()
- Base32Encode()
- Base32HexDecode()
- Base32HexEncode()
- Base64Decode()
- Base64Encode()
- CreateEncryptionKey()
- DeactivateEncryptionKey()
- GenCryptRand()
- GenCryptToken()
- HMACMD5()
- HMACSHA()
- HMACSHA1()
- HOTP()
- ListEncryptionKeys()
- LuhnCheckSum()
- LuhnValidate()
- MD5Hash()
- MD5HashStream()
- OpenSSLVersion()
- PBKDF2()
- RSADecrypt()
- RSAEncrypt()
- RSAGetLastError()
- RSASHA1Sign()
- RSASHA1Verify()
- RSASHASign()
- RSASHAVerify()
- RSASize()
- SHA1Hash()
- SHA1HashStream()
- SHAHash()
- SHAHashStream()
- TOTP()
- TOTPValidate()
- X509GetField()
- X509VerifyCertChain()
Methods
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.
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.
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.
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")
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.
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.
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.
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.
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.
This method performs AES encryption in Cipher Block Chained (CBC) mode
using keys managed by Cache and securely stored in shared memory.
A random initialization vector is generated for each encryption operation.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Use with AESCBCManagedKeyDecrypt.
Input parameters:
Plaintext - String to be encrypted. This is padded before encryption to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
KeyID - Key identifier. The specified key must currently be activated.
Return value: Encrypted ciphertext with embedded key identifier and initialization vector.
NOTE: To AES-CBC encrypt and Base64 encode Unicode strings that may contain wide characters, UTF-8 encode the string first:
Set text=$ZCONVERT(plaintext,"O","UTF8")
Set text=$SYSTEM.Encryption.AESCBCManagedKeyEncrypt(text,key)
Set ciphertext=$SYSTEM.Encryption.Base64Encode(text)
To decode and decrypt, perform these operations in the reverse order:
Set text=$SYSTEM.Encryption.Base64Decode(ciphertext)
Set text=$SYSTEM.Encryption.AESCBCManagedKeyDecrypt(text,key)
Set plaintext=$ZCONVERT(text,"I","UTF8")
Input parameters:
Plaintext - String to be encrypted. This is padded before encryption to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
KeyID - Key identifier. The specified key must currently be activated.
Return value: Encrypted ciphertext with embedded key identifier and initialization vector.
NOTE: To AES-CBC encrypt and Base64 encode Unicode strings that may contain wide characters, UTF-8 encode the string first:
Set text=$ZCONVERT(plaintext,"O","UTF8")
Set text=$SYSTEM.Encryption.AESCBCManagedKeyEncrypt(text,key)
Set ciphertext=$SYSTEM.Encryption.Base64Encode(text)
To decode and decrypt, perform these operations in the reverse order:
Set text=$SYSTEM.Encryption.Base64Decode(ciphertext)
Set text=$SYSTEM.Encryption.AESCBCManagedKeyDecrypt(text,key)
Set plaintext=$ZCONVERT(text,"I","UTF8")
classmethod AESCBCManagedKeyEncryptStream(Plaintext As %Stream.Object, Ciphertext As %Stream.Object, KeyID As %String) as %Status
This method performs AES encryption in Cipher Block Chained (CBC) mode on Streams
using keys managed by Cache and securely stored in shared memory.
A random initialization vector is generated for each encryption operation.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Use with AESCBCManagedKeyDecryptStream.
Input parameters:
Plaintext - Stream to be encrypted. The input is padded to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
Ciphertext - Encrypted Stream.
KeyID - Key identifier. The specified key must currently be activated.
Input parameters:
Plaintext - Stream to be encrypted. The input is padded to the next mutiple of 16 bytes, using reversible block padding. (See Internet Engineering Task Force Request for Comments 2040 and RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
Ciphertext - Encrypted Stream.
KeyID - Key identifier. The specified key must currently be activated.
This method uses
the Advanced Encryption Standard (AES) as a primitive to
decrypt an encrypted key using a key-encryption key (KEK).
See: "AES Key Wrap Specification", 16 November 2001. (http://csrc.nist.gov/CryptoToolkit/kms/AES_key_wrap.pdf)
Input parameters:
EncKey - Encrypted key
KEK - Key-encryption key
Return value: Plaintext key
See: "AES Key Wrap Specification", 16 November 2001. (http://csrc.nist.gov/CryptoToolkit/kms/AES_key_wrap.pdf)
Input parameters:
EncKey - Encrypted key
KEK - Key-encryption key
Return value: Plaintext key
This method uses
the Advanced Encryption Standard (AES) as a primitive to
encrypt a plaintext key using a key-encryption key (KEK).
See: "AES Key Wrap Specification", 16 November 2001. (http://csrc.nist.gov/CryptoToolkit/kms/AES_key_wrap.pdf)
Input parameters:
Key - Plaintext key
KEK - Key-encryption key
Return value: Encrypted key
See: "AES Key Wrap Specification", 16 November 2001. (http://csrc.nist.gov/CryptoToolkit/kms/AES_key_wrap.pdf)
Input parameters:
Key - Plaintext key
KEK - Key-encryption key
Return value: Encrypted key
classmethod ActivateEncryptionKey(File As %String, Username As %String, Password As %String) as %Status
This method activates an encryption key for use with data element encryption for applications.
Note: Must be run from the system namespace.
Input parameters:
File - Name of the key file to use.
Username - Name of an encryption key administrator for this 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.
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.
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.
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.
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")
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")
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.
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.
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")
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")
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.
Input parameter:
Text - Encoded string, as generated by Base64Encode.
Return value: Decoded original 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.
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")
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.
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 CreateEncryptionKey(File As %String, Username As %String, Password As %String, KeyLength As %Integer, 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.
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.
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.
Input parameter:
KeyID - Key identifier of key to deactivate.
Return value: Return status.
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.)
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
This method generates a 16-byte keyed hash-based message authentication code
using the MD5 message digest algorithm.
(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.
Input parameters:
text - String for which to generate message authentication code.
key - Key.
Return value: 16-byte authentication code.
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.
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.
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.
Input parameters:
text - String for which to generate message authentication code.
key - Key.
Return value: 20-byte authentication code.
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.
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 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.
Return value: Comma-separated list of key identifiers.
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
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
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
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
This method generates a 16-byte hash using the MD5 message digest algorithm.
(See Internet Engineering Task Force Request for Comments 1321 for more information.)
Input parameter:
text - String to be hashed.
Return value: 16-byte MD5 hash.
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.
(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.
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
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.
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 format.
Note that the length of the plaintext can not be greater than the length of the modulus of the RSA public key contained in the certificate 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.
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 format.
Note that the length of the plaintext can not be greater than the length of the modulus of the RSA public key contained in the certificate 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.
Return value: Error string.
This method generates an RSA-SHA1 digital signature as specified in
PKCS #1: RSA Cryptography Specifications, section 8.1 RSASSA-PKCS1-v1_5.
Input parameters:
Data - Data to be signed.
Key - RSA private key, PEM encoded.
Password - Private key password (optional).
Return value: Digital signature.
Input parameters:
Data - Data to be signed.
Key - RSA private key, PEM encoded.
Password - Private key password (optional).
Return value: Digital signature.
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.
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.
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 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)
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.
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 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 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 5-argument usage, where the fourth and fifth arguments are the RSA public key modulus and exponent in binary format.
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 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 5-argument usage, where the fourth and fifth arguments are the RSA public key modulus and exponent in binary format.
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.
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.
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.)
Input parameter:
text - String to be hashed.
Return value: 20-byte SHA-1 hash.
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.)
Input parameter:
input - Stream to be hashed.
Return value: 20-byte SHA-1 hash.
Input parameter:
input - Stream to be hashed.
Return value: 20-byte SHA-1 hash.
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)
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.
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)
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)
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.
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 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)
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.Validate(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="Cache-"_##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.
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.Validate(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="Cache-"_##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.
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.
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
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