abstract class %SYSTEM.Encryption
extends Help
This class provides class functions to perform data encryption,
Base64 encoding, hashing, and generation of message authentication codes.
|
Parameters
|
Properties
|
Methods
|
Queries
|
Indices
|
ForeignKeys
|
Triggers
|
|
|
|
45
|
|
|
|
|
• classmethod AESCBCDecrypt(ciphertext As %String, key As %String, IV As %String)
as %String
This method performs AES decryption in Cipher Block Chained (CBC) mode.
Use with AESCBCEncrypt.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Input parameters:
ciphertext - Encrypted ciphertext, as generated by AESCBCEncrypt.
key - Input key material.
Key material 16, 24, or 32 characters long (on Unicode systems, with all character values < 256) is used directly.
Otherwise, Password-Based Key Derivation Function #2 (PBKDF2)
is used with HMAC-SHA-1,
no salt, and one iteration
to generate an AES key of the next larger valid size (up to 32 bytes).
(See RSA Laboratories Public-Key Cryptography Standards #5 for more information.)
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 - Input key material.
Key material 16, 24, or 32 characters long (on Unicode systems, with all character values < 256) is used directly.
Otherwise, Password-Based Key Derivation Function #2 (PBKDF2)
is used with HMAC-SHA-1,
no salt, and one iteration
to generate an AES key of the next larger valid size (up to 32 bytes).
(See RSA Laboratories Public-Key Cryptography Standards #5 for more information.)
IV - Initialization vector (optional).
If this argument is present it must be 16 characters long (on Unicode systems, with all character values < 256).
If this argument is omitted (or is an empty string), a null initialization vector is used.
• classmethod AESCBCEncrypt(plaintext As %String, key As %String, IV As %String)
as %String
This method performs AES encryption in Cipher Block Chained (CBC) mode.
Use with AESCBCDecrypt.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Input parameters:
plaintext - String to be encrypted.
This is padded before encryption to the next mutiple of 16 bytes, using
reversible block padding.
(See Internet Engineering Task Force Request for Comments 2040 and
RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
key - Input key material.
Key material 16, 24, or 32 characters long (on Unicode systems, with all character values < 256) is used directly.
Otherwise, Password-Based Key Derivation Function #2 (PBKDF2)
is used with HMAC-SHA-1,
no salt, and one iteration
to generate an AES key of the next larger valid size (up to 32 bytes).
(See RSA Laboratories Public-Key Cryptography Standards #5 for more information.)
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 - Input key material.
Key material 16, 24, or 32 characters long (on Unicode systems, with all character values < 256) is used directly.
Otherwise, Password-Based Key Derivation Function #2 (PBKDF2)
is used with HMAC-SHA-1,
no salt, and one iteration
to generate an AES key of the next larger valid size (up to 32 bytes).
(See RSA Laboratories Public-Key Cryptography Standards #5 for more information.)
IV - Initialization vector (optional).
If this argument is present it must be 16 characters long (on Unicode systems, with all character values < 256).
If this argument is omitted (or is an empty string), a null initialization vector is used.
• classmethod AESCBCManagedKeyDecrypt(Ciphertext As %String)
as %String
This method performs AES decryption in Cipher Block Chained (CBC) mode.
Use with AESCBCManagedKeyEncrypt.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Input parameter:
Ciphertext - Encrypted ciphertext, as generated by AESCBCManagedKeyEncrypt.
The key used for encryption must currently be activated.
Return value: Decrypted original plaintext, with block padding removed.
• classmethod AESCBCManagedKeyDecryptStream(Ciphertext As %Stream.Object, Plaintext As %Stream.Object)
as %Status
This method performs AES decryption in Cipher Block Chained (CBC) mode on Streams.
Use with AESCBCManagedKeyEncryptStream.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Input parameters:
Ciphertext - Stream to be decrypted, as generated by AESCBCManagedKeyEncryptStream.
The key used for encryption must currently be activated.
Plaintext - Decrypted Stream, with block padding removed.
• classmethod AESCBCManagedKeyEncrypt(Plaintext As %String, KeyID As %String)
as %String
This method performs AES encryption in Cipher Block Chained (CBC) mode
using keys managed by Cache and securely stored in shared memory.
A random initialization vector is generated for each encryption operation.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Use with AESCBCManagedKeyDecrypt.
Input parameters:
Plaintext - String to be encrypted.
This is padded before encryption to the next mutiple of 16 bytes, using
reversible block padding.
(See Internet Engineering Task Force Request for Comments 2040 and
RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
KeyID - Key identifier. The specified key must currently be activated.
Return value: Encrypted ciphertext with embedded key identifier and initialization vector.
NOTE: To AES-CBC encrypt and Base64 encode Unicode strings that may contain wide
characters, UTF-8 encode the string first:
Set text=$ZCONVERT(plaintext,"O","UTF8")
Set text=$SYSTEM.Encryption.AESCBCManagedKeyEncrypt(text,key)
Set ciphertext=$SYSTEM.Encryption.Base64Encode(text)
To decode and decrypt, perform these operations in the reverse order:
Set text=$SYSTEM.Encryption.Base64Decode(ciphertext)
Set text=$SYSTEM.Encryption.AESCBCManagedKeyDecrypt(text,key)
Set plaintext=$ZCONVERT(text,"I","UTF8")
• classmethod AESCBCManagedKeyEncryptStream(Plaintext As %Stream.Object, Ciphertext As %Stream.Object, KeyID As %String)
as %Status
This method performs AES encryption in Cipher Block Chained (CBC) mode on Streams
using keys managed by Cache and securely stored in shared memory.
A random initialization vector is generated for each encryption operation.
(See Federal Information Processing Standards Publication 197
and NIST Special Publication 200-38A
for more information.)
Use with AESCBCManagedKeyDecryptStream.
Input parameters:
Plaintext - Stream to be encrypted.
The input is padded to the next mutiple of 16 bytes, using
reversible block padding.
(See Internet Engineering Task Force Request for Comments 2040 and
RSA Laboratories Public-Key Cryptography Standards #7 for more information.)
Ciphertext - Encrypted Stream.
KeyID - Key identifier. The specified key must currently be activated.
• classmethod ActivateEncryptionKey(File As %String, Username As %String, Password As %String)
as %Status
This method activates an encryption key for use with data element encryption for applications.
Note: Must be run from the system namespace.
Input parameters:
File - Name of the key file to use.
Username - Name of an encryption key administrator for this key file.
Password - Password of this encryption key administrator for this key file.
This value should always be obtained from a user prompt, never embedded in application code.
Return value: Return status.
• classmethod Base64Decode(text As %String)
as %String
This method performs Base64 decoding.
Use with Base64Encode.
(See Internet Engineering Task Force Request for Comments 2045 for more information.)
Input parameter:
text - Encoded string, as generated by Base64Encode.
Return value: Decoded original string.
• classmethod Base64Encode(text As %String)
as %String
This method performs Base64 encoding.
Use with Base64Decode.
(See Internet Engineering Task Force Request for Comments 2045 for more information.)
Input parameter:
text - String to be encoded
Return value: Encoded string.
• 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.
• classmethod DeactivateEncryptionKey(KeyID As %String)
as %Status
This method deactivates an encryption key currently
activated for use with data element encryption for applications.
Note: Must be run from the system namespace.
Input parameter:
KeyID - Key identifier of key to deactivate.
Return value: Return status.
• classmethod GenCryptRand(Length As %Integer, RequireBestEntropy As %Boolean)
as %String
This is a deterministic cryptographic pseudorandom number generator compliant with
FIPS PUB 140-2 "Security Requirements for Cryptographic Modules"
Annex C "Approved Random Number Generators" and
FIPS PUB 186-2 "Digital Signature Standard (DSS)" Change Notice 1
Appendix 3.1 "Algorithm for Computing m values of x" and
Appendix 3.3 "Constructing the function G from the SHA-1".
It is useful for generating secure encryption keys and salt.
(See
Federal Information Processing Standards Publications 140-2 Annex C, 180-2, and 186-2
for more information.)
Input parameters:
Length - Length of random string to generate.
RequireBestEntropy - Require best entropy source for initialization (optional).
If this parameter equals 1, the function will return an error unless the
generator's internal state has been seeded using the best source of true entropy (OS dependent).
Return value: Random string. (On Unicode systems all values are < 256.)
• classmethod GenCryptToken()
as %String
GenCryptToken() generates a random eight character numeric string which is to be used as a one-shot security token.
The user has only one attempt to enter this token after which it must be discarded. It is composed of numerics only
as it was found that users often made errors entering alphanumeric tokens.
Return value: 8-character numeric security token
• classmethod HMACMD5(text As %String, key As %String)
as %String
This method generates a 16-byte keyed hash-based message authentication code
using the MD5 message digest algorithm.
(See Federal Information Processing Standards Publication 198 and
Internet Engineering Task Force Request for Comments 1321 and 2104
for more information.)
Input parameters:
text - String for which to generate message authentication code.
key - Key.
Return value: 16-byte authentication code.
• classmethod HMACSHA(bitlength As %Integer, text As %String, key As %String)
as %String
This method generates a keyed hash-based message authentication code
using one of the U.S. Secure Hash Algorithms.
(See Federal Information Processing Standards Publications 180-2 and 198 and
Internet Engineering Task Force Request for Comments 2104, 3174, and 4634
for more information.)
Input parameters:
bitlength - Length in bits of the desired message authentication code. Legal values are:
160 (SHA-1)
224 (SHA-224)
256 (SHA-256)
384 (SHA-384)
512 (SHA-512)
text - String for which to generate message authentication code.
key - Key.
Return value: String containing message authentication code, one byte per character.
• classmethod HMACSHA1(text As %String, key As %String)
as %String
This method generates a 20-byte keyed hash-based message authentication code
using U.S. Secure Hash Algorithm 1 (SHA-1).
(See Federal Information Processing Standards Publications 180-2 and 198 and
Internet Engineering Task Force Request for Comments 2104 and 3174
for more information.)
Input parameters:
text - String for which to generate message authentication code.
key - Key.
Return value: 20-byte authentication code.
• classmethod ListEncryptionKeys()
as %String
This method returns a comma-separated list of the key identifiers of encryption keys
currently activated for use with data element encryption for applications.
Note: Must be run from the system namespace.
Return value: Comma-separated list of key identifiers.
• classmethod MD5Hash(text As %String)
as %String
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.
• classmethod MD5HashStream(input As %Stream.Object)
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.
• classmethod PBKDF2(Password As %String, Iterations As %Integer, Salt As %String, KeyLength As %Integer)
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-1.
(See
RSA Laboratories Public-Key Cryptography Standards #5,
Federal Information Processing Standards Publications 180-2 and 198, and
Internet Engineering Task Force Request for Comments 2104
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
Return value: Encryption key
• classmethod RSADecrypt(Ciphertext As %String, Key As %String, Password As %String, Encoding As %Integer)
as %String
This method performs RSA decryption as specified in
PKCS #1 v2.1: RSA Cryptography Specifications, section 7 Encryption Schemes.
This is intended primarily for encryption of temporary symmetric encryption keys.
Input parameters:
Ciphertext - Data to be decrypted.
Key - RSA private key corresponding to the RSA public key that was used for encryption, PEM encoded.
Password - Private key password (optional).
Encoding - PKCS #1 v2.1 encoding method (optional):
1 = OAEP (default)
2 = PKCS1-v1_5
Return value: Plaintext.
• classmethod RSAEncrypt(Plaintext As %String, Certificate As %String, CAfile As %String, CRLfile As %String, Encoding As %Integer)
as %String
This method performs RSA encryption as specified in
PKCS #1 v2.1: RSA Cryptography Specifications, section 7 Encryption Schemes.
Input parameters:
Plaintext - Data to be encrypted.
Certificate - An X.509 certificate containing the RSA public key to be used for encryption,
in PEM encoded or binary DER 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.
• 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.
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.
• 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.
• 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 - 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 5-argument usage, where the fourth and fifth arguments
are the RSA public key modulus and exponent in binary format.
• classmethod RSASize(Input As %String, Password As %String)
as %Integer
This method returns the length of the modulus of an RSA key.
Intended for use with RSAEncrypt().
Input parameters:
Input - An X.509 digital certificate containing an RSA public key, in PEM encoded or binary DER format,
or an RSA private key, PEM encoded.
Password - Private key password (optional).
Return value: The length of the modulus of the RSA key, in bytes.
• classmethod SHA1Hash(text As %String)
as %String
This method generates a 20-byte hash using U.S. Secure Hash Algorithm 1 (SHA-1).
(See Federal Information Processing Standards Publication 180-2
and Internet Engineering Task Force Request for Comments 3174
for more information.)
Input parameter:
text - String to be hashed.
Return value: 20-byte SHA-1 hash.
• classmethod SHA1HashStream(input As %Stream.Object)
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.
• classmethod SHAHash(bitlength As %Integer, text As %String)
as %String
This method generates a hash using one of the U.S. Secure Hash Algorithms.
(See Federal Information Processing Standards Publication 180-2
and Internet Engineering Task Force Request for Comments 3174 and 4634
for more information.)
Input parameters:
bitlength - Length in bits of the desired hash. Legal values are:
160 (SHA-1)
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)
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.
• 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
"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
Return value: The value of the field.
