YOUSEFUL / DELPHI / COMPONENTS

`TAtlasAesGcm`

Raw AES in Galois/Counter Mode with a 12-byte nonce and a 16-byte tag. Prefer TAtlasSecretBox.

Class Unit Atlas.Crypto · Inherits TObject · Product Atlas Crypto

Description

The primitive under every Atlas Crypto container, exposed for matching an existing format and for test vectors. The caller chooses the nonce, and a nonce must never be used twice with the same key: a repeat reveals the XOR of the two messages and lets an attacker forge tags. TAtlasSecretBox generates nonces for you and is what applications should use.

Keys are 16, 24 or 32 bytes (AES-128, -192, -256). AssociatedData is authenticated but not encrypted or returned; pass nil when there is none. Decryption returns nothing unless the tag matches. The results match GCM specification test cases 1, 2 and 4 in the tests.

Members

Member	Kind	What it does
`NonceSize`	field	The nonce length in bytes.
`TagSize`	field	The tag length in bytes.
`Encrypt`	method	Returns the ciphertext, the same length as `Plain`, and sets `Tag` to the 16-byte authentication tag.
`Decrypt`	method	Returns the plaintext when key, nonce, ciphertext, associated data and tag all match.

Methods

`Encrypt` method

class function Encrypt(const Key, Nonce, Plain, AssociatedData: TBytes; out Tag: TBytes): TBytes; static;

Returns the ciphertext, the same length as Plain, and sets Tag to the 16-byte authentication tag. Raises EAtlasCryptoError for a key that is not 16, 24 or 32 bytes or a nonce that is not 12 bytes.

Cipher := TAtlasAesGcm.Encrypt(Key, Nonce, Plain, Aad, Tag);

`Decrypt` method

class function Decrypt(const Key, Nonce, Cipher, AssociatedData, Tag: TBytes): TBytes; static;

Returns the plaintext when key, nonce, ciphertext, associated data and tag all match. Otherwise raises EAtlasCryptoError (Decryption failed: wrong key, or the data was altered) and no plaintext reaches the caller. A tag that is not 16 bytes is refused.

Plain := TAtlasAesGcm.Decrypt(Key, Nonce, Cipher, Aad, Tag);

Fields

`NonceSize` field

const NonceSize = 12;

The nonce length in bytes. Other lengths raise EAtlasCryptoError.

`TagSize` field

const TagSize = 16;

The tag length in bytes. Shorter tags are refused rather than checked weakly.

Examples

Reproduce a published GCM test case

GCM specification test case 2: zero key, zero nonce, one zero block. Prints 0388dace60b6a392f328c2b971b2fe78 ab6e47d42cec13bdf53a67b21257bddf, then 16.

uses System.SysUtils, Atlas.Crypto;

procedure GcmKnownAnswer;
var
  Key, Nonce, Plain, Tag, Cipher: TBytes;
begin
  SetLength(Key, 16);   // new dynamic arrays are filled with zeros
  SetLength(Nonce, TAtlasAesGcm.NonceSize);
  SetLength(Plain, 16);
  Cipher := TAtlasAesGcm.Encrypt(Key, Nonce, Plain, nil, Tag);
  WriteLn(TAtlasBytes.ToHex(Cipher), ' ', TAtlasBytes.ToHex(Tag));
  WriteLn(Length(TAtlasAesGcm.Decrypt(Key, Nonce, Cipher, nil, Tag)));
end;

TAtlasSecretBox · TAtlasStreamCrypt · TAtlasRandom

Also in Atlas Crypto

TAtlasHashCalculator · TAtlasFileProtector

TAtlasAesGcm