Skip to content

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;
You can create new keys using the same object by calling 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.