TWebAESEncryption
TWebAESEncryption
is a wrapper around the Web Crypto API
. It's recommended to first
familiarize yourself with the Web Crypto API
: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API
The Web Crypto API
provides native support to create, use and store cryptographic keys
without exposing the content of private keys.
Below is a list of the most important properties, methods and events for the
TWebAESEncryption
. The supported algorithms are: AES-CBC
and AES-GCM
.
Create a key
A key is created by default when a new TWebAESEncryption
is created. This is an async process. If you want to be certain about not interfering with this key generation, wait until the OnKeyCreated
event is triggered.
procedure TForm1.AESKeyCreated(Sender: TObject);
begin
//Proceed from here
end;
procedure TForm1.WebFormCreate(Sender: TObject);
begin
aes := TWebAESEncryption.Create(aetCBC);
aes.OnKeyCreated := AESKeyCreated;
end;
GenerateKey
or GenerateKeyP
.
//Using event-based GenerateKey
procedure TForm1.AESKeyCreated(Sender: TObject);
begin
//Proceed from here
end;
procedure TForm1.WebButton1Click(Sender: TObject);
begin
aes.GenerateKey;
end;
//Using promise-based GenerateKeyP
//WebButton1Click is marked as async
procedure TForm1.WebButton1Click(Sender: TObject);
begin
Await(JSValue, aes.GenerateKey);
//Do something with the new key...
end;
Encrypting data
The available Encrypt
methods are event-based. They will trigger the OnEncrypted
event when they are ready. Use the EncryptP
promise-based functions if you need to wait for an encryption to finish.
//Encrypting with EncryptP
procedure TForm1.WebButton1Click(Sender: TObject);
var
ab: TJSArrayBuffer;
I: Integer;
res: string;
begin
for I := 0 to 9 do
begin
ab := Await(TJSArrayBuffer, aes.EncryptP(myData[I]));
//Do something with ab
//Convert to HEX for example, before sending to a server:
res := ABToHex(ab);
end;
end;
Decrypting data
The available Decrypt method is event-based. It will trigger the OnDecryptedBinary
or OnDecryptedString
event when it is ready based on which format was selected. Use the DecryptP
promise-based function if you need to wait for a decryption to finish.
//Decrypting with DecryptP
procedure TForm1.WebButton1Click(Sender: TObject);
var
I: Integer;
res: string;
begin
for I := 0 to 9 do
begin
res := Await(TJSArrayBuffer, aes.DecryptP(GetMyData(I), drtString));
//Do something with res
end;
end;
Properties for TWebAESEncryption
Property | Description |
---|---|
AESType: TAESEncryptionType | The AES encryption algorithm type. If modified, it's not applied to the current key. |
CryptoKey: TJSCryptoKey | The CryptoKey object. |
ExtractableKey: Boolean | Determines if the key is extractable. If modified, it's not applied to the current key. |
KeyLength: TAESEncryptionKeyLength | The key length. If modified, it's not applied to the current key. |
Usages | Set of key usages. If modified, it's not applied to the current key. |
Methods for TWebAESEncryption
Method | Description |
---|---|
Decrypt(AEncryptedData: TJSArrayBuffer; AResultType: TCryptoDecryptResultType) | Method to decrypt an encoded data with the class’s key. The result type can be string or binary, based on what kind of data was encoded. |
Encrypt(APlainText: string) | Method to encrypt a plain text with the class’s key |
EncryptP(APlainText: string): TJSPromise | Promise-based equivalent of Encrypt(APlainText) . Resolves with a TJSArrayBuffer value. |
Encrypt(ABinary: TJSUint8Array) | Method to encrypt binary data with the class’s key. |
EncryptP(ABinary: TJSUint8Array): TJSPromise | Promise-based equivalent of Encrypt(ABinary) . Resolves with a TJSArrayBuffer value. |
ExportKey(AFormat: TCryptoExportImportFormat) | Method to export the class’s key. Supported formats are: raw (ArrayBuffer) and jwk (JSON string) . |
GenerateKey | Generates a new key based on the current property settings. |
ImportKey(AJSON: string) | Method to import an AES key that is stored as a JSON string. |
ImportKeyP(AJSON: string): TJSPromise | Promise-based equivalent of ImportKey(AJSON) . Resolves with a True value. |
ImportKey(ABinary: TJSUint8Array) | Method to import an AES key that is stored as binary data. |
ImportKeyP(ABinary: TJSUint8Array): TJSPromise | Promise-based equivalent of ImportKey(ABinary) . Resolves with a True value. |
ImportKey(ARaw: TJSArrayBuffer) | Method to import an AES key that is stored as an array buffer. |
ImportKeyP(ARaw: TJSArrayBuffer): TJSPromise | Promise-based equivalent of ImportKey(ARaw) . Resolves with a True value. |
UnwrapKey(AImportFormat: TCryptoExportImportFormat; AKey: TJSArrayBuffer; AKeyAlgorithm: JSValue; AExtractable: Boolean; AKeyUsages: TCryptoKeyUsages) | Method to unwrap AKey with the class’s key and algorithm. AKeyAlgorithm is the algorithm of AKey. AImportFormat must be the same as what was used for wrapping. |
UnwrapKeyP(AImportFormat: TCryptoExportImportFormat; AKey: TJSArrayBuffer; AKeyAlgorithm: JSValue; AExtractable: Boolean; AKeyUsages: TCryptoKeyUsages): TJSPromise | Promise-based equivalent of UnwrapKey. Resolves with a TJSCryptoKey value. |
WrapKey(AKey: TJSCryptoKey; AExportFormat: TCryptoExportImportFormat) | Method to wrap a key with the class’s key and algorithm. |
WrapKeyP(AKey: TJSCryptoKey; AExportFormat: TCryptoExportImportFormat) | Promise-based equivalent of WrapKey . Resolves with a TJSArrayBuffer value. |
Events for TWebAESEncryption
Property | Description |
---|---|
OnDecryptedBinary | Event triggered when an encrypted data is decrypted and the format is binary. |
OnDecryptedString | Event triggered when an encrypted is decrypted and the format is string. |
OnEncrypted | Event triggered when a data is encrypted. |
OnError | Event triggered when there's a Promise rejection. |
OnKeyCreated | Event triggered when a key is created. |
OnKeyExportedJSON | Event triggered when a key is exported as a JSON string. |
OnKeyExportedRaw | Event triggered when a key is exported as an array buffer. |
OnKeyImported | Event triggered when a key is imported. |
OnKeyUnwrapped | Event triggered when a key is unwrapped. |
OnKeyWrapped | Event triggered when a key is wrapped. |