%Wallet.SymmetricKey
persistent class %Wallet.SymmetricKey extends %Wallet.Secret
SQL Table Name: %Wallet.SymmetricKey
This %Wallet.Secret type defines storage for symmetric keys.This class supports most symmetric encryption operations defined in %SYSTEM.Encryption. In addition, the encryption key can be activated to be used with Managed Key Encryption instead of using an external keyfile. See ActivateManagedKey() and DeactivateManagedKey() for details.
// create a secret named "MySecret" with a randomly generated 32-byte key:
set status = ##class(%Wallet.SymmetricKey).Create(
"WalletTest.MySecret", {
"Length":32
})
set ciphertext = ##class(%Wallet.SymmetricKey).AESCBCEncrypt("WalletTest.MySecret", mymessage)
set plaintext = ##class(%Wallet.SymmetricKey).AESCBCDecrypt("WalletTest.MySecret", ciphertext)
Property Inventory
Method Inventory
- AESCBCDecrypt()
- AESCBCDecryptStream()
- AESCBCEncrypt()
- AESCBCEncryptStream()
- AESGCMDecrypt()
- AESGCMDecryptStream()
- AESGCMEncrypt()
- AESGCMEncryptStream()
- AESKeyUnwrap()
- AESKeyWrap()
- Create()
- HMACSHA()
- HMACSHA3()
Parameters
parameter AESCBCLengths;
Valid key lengths for AES-CBC encryption and decryption methods.
parameter AESGCMLengths;
Valid key lengths for AES-GCM encryption and decryption methods.
parameter HMACSHA3Lengths;
Valid bit lengths for HMACSHA3()
parameter HMACSHALengths;
Valid bit lengths for HMACSHA()
Properties
property KeyId as %String;
The keyId for this key. This is used when the key is activated for managed key encryption. This must be unique for this secret.
By default this is generated using $System.Util.CreateGUID().
Property methods: KeyIdDisplayToLogical(), KeyIdGet(), KeyIdGetStored(), KeyIdIsValid(), KeyIdLogicalToDisplay(), KeyIdLogicalToOdbc(), KeyIdNormalize(), KeyIdSet()
property Length as %Integer;
The length (in bytes) of the key.
Property methods: LengthDisplayToLogical(), LengthGet(), LengthGetStored(), LengthIsValid(), LengthLogicalToDisplay(), LengthNormalize(), LengthSet(), LengthXSDToLogical()
Methods
Decrypt the given ciphertext using AES-CBC, with the named key.
- name - The name of the key to use.
- ciphertext - A string containing the cipher text to be decrypted.
- iv - The initialization vector.
classmethod AESCBCDecryptStream(name As %String, ciphertext As %Stream.Object, plaintext As %Stream.Object, iv As %String)
Decrypt the given ciphertext stream using AES-CBC, with the named key.
- name - The name of the key to use.
- ciphertext - The stream containing the encrypted cipher text.
- plaintext - The stream where the decrypted plain text should be written.
- iv - The initialization vector.
Encrypt the given plaintext using AES-CBC, with the named key.
- name - The name of the key to use.
- plaintext - A string containing the plain text to be encrypted.
- iv - The initialization vector.
set message = "the quick brown fox jumped over the lazy dog."
set iv = $System.Encryption.GenCryptRand(12,1)
// do encryption:
set ciphertext = ##class(%Wallet.SymmetricKey).AESCBCEncrypt("mysecret", message, iv)
// decrypt using the ciphertext and params from AESCBCEncryptStream():
set plaintext = ##class(%Wallet.SymmetricKey).AESCBCDecrypt("mysecret", ciphertext, iv)
classmethod AESCBCEncryptStream(name As %String, plaintext As %Stream.Object, ciphertext As %Stream.Object, iv As %String)
Encrypt the given plaintext stream using AES-CBC, with the named key.
- name - The name of the key to use.
- plaintext - The stream containing the plain text to be encrypted.
- ciphertext - The stream where the encrypted cipher text will be written.
- iv - The initialization vector.
//set up streams:
set plaintext = ##class(%Stream.GlobalCharacter).%New()
set ciphertext = ##class(%Stream.GlobalBinary).%New()
set outtext = ##class(%Stream.GlobalCharacter).%New()
do plaintext.Write("the quick brown fox jumped over the lazy dog.")
set iv = $System.Encryption.GenCryptRand(12,1)
// do encryption:
do ##class(%Wallet.SymmetricKey).AESCBCEncryptStream("mysecret", plaintext, ciphertext, iv)
// decrypt using the ciphertext and params from AESCBCEncryptStream():
do ##class(%Wallet.SymmetricKey).AESCBCDecryptStream("mysecret", ciphertext, outtext, iv)
classmethod AESGCMDecrypt(name As %String, ciphertext As %String, inParams As %DynamicObject) as %String
Decrypt the given ciphertext using AES-GCM, with the named key.
- name - The name of the key to use.
- ciphertext - A string containing the cipher text to be decrypted.
- inParams - Specifies additional parameters. Possible values are:
- iv - Initialization vector.
- aad optional - Additional associated data.
- wide - Whether the initial plaintext contained wide characters. If this is incorrect the resulting plaintext will be formatted incorrectly.
- tag - A computed value used to validate the decryption.
See AESGCMEncrypt().
classmethod AESGCMDecryptStream(name As %String, ciphertext As %Stream.Object, plaintext As %Stream.Object, inParams As %DynamicObject)
Decrypt the given ciphertext stream using AES-GCM, with the named key.
- name - The name of the key to use.
- ciphertext - The stream containing the cipher text to be decrypted.
- plaintext - The stream where the decrypted plian text will be written.
- inParams - Specifies additional parameters. Possible values are:
- iv - Initialization vector.
- aad optional - Additional associated data.
- wide - Whether the initial plaintext contained wide characters. If this is incorrect the resulting plaintext will be formatted incorrectly.
- tag - A computed value used to validate the decryption.
See AESGCMEncryptStream().
classmethod AESGCMEncrypt(name As %String, plaintext As %String, inParams As %DynamicObject = {{}}, Output outParams As %DynamicObject) as %String
Encrypt the given plaintext using AES-GCM, with the named key.
- name - The name of the key to use.
- plaintext - A string containing the plain text to be encrypted.
- inParams - Specifies additional parameters. Possible values are:
- iv optional - The initialization vector. If omitted, a random 12-byte iv will be generated.
- aad optional - Additional associated data.
- outParams will contain the parameters needed to decrypt the ciphertext. This will include the input parameters, as well as "tag", which is computed during encryption.
All parameters are optional. To encrypt with default values:set message = "the quick brown fox jumped over the lazy dog." set ciphertext = ##class(%Wallet.SymmetricKey).AESGCMEncrypt("mysecret", message, { "iv":($System.Encryption.GenCryptRand(12,1)), "aad":($System.Encryption.GenCryptRand(12,1)) }, .params) set plaintext = ##class(%Wallet.SymmetricKey).AESGCMDecrypt("mysecret", ciphertext, params)set ciphertext = ##class(%Wallet.SymmetricKey).AESGCMEncrypt("mysecret", message,, .params)
classmethod AESGCMEncryptStream(name As %String, plaintext As %Stream.Object, ciphertext As %Stream.Object, inParams As %DynamicObject = {{}}, Output outParams As %DynamicObject)
Encrypt the given plaintext stream using AES-GCM, with the named key.
All parameters are optional. To encrypt with default values:
- name - The name of the key to use.
- plaintext - The stream containing the plain text to be encrypted.
- ciphertext - A stream where the encrypted cipher text will be written.
- inParams - Specifies additional parameters. Possible values are:
- iv optional - The initialization vector. If omitted, a random 12-byte iv will be generated.
- aad optional - Additional associated data.
- wide optional - Indicates whether the plaintext stream contains wide characters. If omitted, the stream will be scanned for wide characters.
- outParams will contain the parameters needed to decrypt the ciphertext stream. This will include the input parameters, as well as "tag", which is computed during encryption.
//set up streams:
set plaintext = ##class(%Stream.GlobalCharacter).%New()
set ciphertext = ##class(%Stream.GlobalBinary).%New()
set outtext = ##class(%Stream.GlobalCharacter).%New()
do plaintext.Write("the quick brown fox jumped over the lazy dog.")
// do encryption:
do ##class(%Wallet.SymmetricKey).AESGCMEncryptStream("mysecret", plaintext, ciphertext, {
"iv":($System.Encryption.GenCryptRand(12,1)),
"aad":($System.Encryption.GenCryptRand(12,1)),
"wide":false
}, .params)
// decrypt using the ciphertext and params from AESGCMEncryptStream():
do ##class(%Wallet.SymmetricKey).AESGCMDecryptStream("mysecret", ciphertext, outtext, params)
do ##class(%Wallet.SymmetricKey).AESGCMEncryptStream("mysecret", plaintext, ciphertext,, .params)
Unwrap the given wrapped key using the named secret key.
See %SYSTEM.Encryption method AESKeyUnwrap for details.
Perform AES Key wrapping on the given key using the named secret key.
See %SYSTEM.Encryption method AESKeyWrap for details.
Create a new symmetric key. The value for the key can be specified using the "Secret" property.
If "Secret" is left undefined and "Length" is defined, then a new randomly generated key of the given length will be used:
// create a secret named "WalletTest.MySecret" with a randomly generated 32-byte key:
set status = ##class(%Wallet.SymmetricKey).Create(
"WalletTest.MySecret", {
"Length":32
})
// create a secret named "WalletTest.MyOtherSecret" with an explicitly defined 16-byte key:
set key = $System.Encryption.GenCryptRand(16,1)
set status = ##class(%Wallet.SymmetricKey).Create(
"WalletTest.MyOtherSecret", {
"Secret":(key)
})
Generate a keyed hash-based message authentication code using the given SHA algorithm.
Input parameters:
See %SYSTEM.Encryption method HMACSHA for details.
Input parameters:
- name - the name of the key to use.
- bitlength - Valid values are:
- 160 (SHA-1)
- 224 (SHA-224)
- 256 (SHA-256)
- 384 (SHA-384)
- 512 (SHA-512)
- text - a string or stream containing the input text.
See %SYSTEM.Encryption method HMACSHA for details.
Generate a keyed hash-based message authentication code using the given SHA3 algorithm.
Input parameters:
See %SYSTEM.Encryption method HMACSHA3 for details.
Input parameters:
- name - the name of the key to use.
- bitlength - Valid values are:
- 224 (SHA-224)
- 256 (SHA-256)
- 384 (SHA-384)
- 512 (SHA-512)
- text - a string or stream containing the input text.
See %SYSTEM.Encryption method HMACSHA3 for details.
Indexes
index (KeyIdIndex on KeyId) [Unique];
Index methods: KeyIdIndexCheck(), KeyIdIndexCheckUnique(), KeyIdIndexDelete(), KeyIdIndexExists(), KeyIdIndexOpen(), KeyIdIndexSQLCheckUnique(), KeyIdIndexSQLExists(), KeyIdIndexSQLFindPKeyByConstraint(), KeyIdIndexSQLFindRowIDByConstraint()
Inherited Members
Inherited Properties
Inherited Methods
- %%CLASSNAMELogicalToStorage()
- %%CLASSNAMEStorageToLogical()
- %AddToSaveSet()
- %AddToSyncSet()
- %BMEBuilt()
- %BuildIndicesAsync()
- %BuildIndicesAsyncResponse()
- %CheckConstraints()
- %CheckConstraintsForExtent()
- %ClassIsLatestVersion()
- %ClassName()
- %ComposeOid()
- %ConstructClone()
- %Delete()
- %DeleteExtent()
- %DeleteId()
- %DispatchClassMethod()
- %DispatchGetModified()
- %DispatchGetProperty()
- %DispatchMethod()
- %DispatchSetModified()
- %DispatchSetMultidimProperty()
- %DispatchSetProperty()
- %Exists()
- %ExistsId()
- %Extends()
- %GUID()
- %GUIDSet()
- %GetLock()
- %GetParameter()
- %GetSwizzleObject()
- %Id()
- %InitExtentData()
- %InsertBatch()
- %IsA()
- %IsModified()
- %IsNull()
- %KillExtent()
- %KillExtentData()
- %LoadFromMemory()
- %LockExtent()
- %LockId()
- %New()
- %NormalizeObject()
- %ObjectIsNull()
- %ObjectModified()
- %Oid()
- %OnBeforeAddToSync()
- %OnDeleteFinally()
- %OnDetermineClass()
- %OnOpenFinally()
- %OnSaveFinally()
- %Open()
- %OpenId()
- %OriginalNamespace()
- %PackageName()
- %PhysicalAddress()
- %PurgeIndices()
- %Reload()
- %RemoveFromSaveSet()
- %ResolveConcurrencyConflict()
- %RollBack()
- %Save()
- %SaveDirect()
- %SaveIndices()
- %SerializeObject()
- %SetModified()
- %SortBegin()
- %SortEnd()
- %SyncObjectIn()
- %SyncTransport()
- %UnlockExtent()
- %UnlockId()
- %ValidateIndices()
- %ValidateObject()
- %ValidateTable()
- Copy()
- Delete()
- Exists()
- GetSecretValue()
- Modify()
- NameSet()
- StorageExportGet()
- StorageImportSet()
- XMLDTD()
- XMLExport()
- XMLExportToStream()
- XMLExportToString()
- XMLNew()
- XMLSchema()
- XMLSchemaNamespace()
- XMLSchemaType()
Storage
Gray indicates storage defined by superclasses.
Storage Model: Storage (%Wallet.Secret)
^|$$$SecurityMapWallet|WALLET("SecretD")(ID) |
= | %%CLASSNAME
Storage
Collection
Version
|
Storage Model: Storage (%Wallet.SymmetricKey)
^|$$$SecurityMapWallet|WALLET("SecretD")(ID,"SymmetricKey") |
= | Length
KeyId
|