YOUSEFUL / DELPHI / COMPONENTS

`TCngAlgorithm`

Low-level wrapper of a Windows CNG algorithm provider handle, used by the other units; applications rarely need it.

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

Description

Atlas.Crypto.Cng holds the bcrypt.dll declarations that Atlas Crypto is built on, written from the public Windows SDK documentation because Delphi ships none: the BCrypt... functions, the parameter records (TBCryptAuthInfo, TBCryptOaepInfo, TBCryptPssInfo, TBCryptBuffer, TBCryptBufferDesc), constants, the CngCheck procedure that turns a failed NTSTATUS into EAtlasCryptoError with the message <operation> failed (Windows status XXXXXXXX), and BytesPtr, which returns nil for an empty TBytes. TCngAlgorithm opens an algorithm provider once and closes it when freed.

Use this unit only to call a CNG feature the higher units do not cover, and prefer the higher units whenever they do: they validate arguments and never return unauthenticated data. This unit is also the only one a non-Windows back end would replace.

Members

Member	Kind	What it does
`Create`	constructor	Opens the CNG provider for `AlgorithmId` (a CNG algorithm name such as `SHA256`, `AES` or `ECDSA_P256`) with `Flags` (for example `BCRYPT_ALG_HANDLE_HMAC_FLAG`).
`Destroy`	destructor	Closes the provider handle.
`ULongProperty`	method	Reads a 32-bit property of the provider by its CNG name, for example `BlockLength`.
`SetStringProperty`	method	Sets a string property of the provider, for example `ChainingMode` to `ChainingModeGCM`.
`Handle`	property	The provider handle, for passing to `BCrypt...` functions.

Constructors

`Create` constructor

constructor Create(const AlgorithmId: string; Flags: ULONG = 0);

Opens the CNG provider for AlgorithmId (a CNG algorithm name such as SHA256, AES or ECDSA_P256) with Flags (for example BCRYPT_ALG_HANDLE_HMAC_FLAG). An unknown name raises EAtlasCryptoError (Opening NOPE failed (Windows status C0000225)).

Algorithm := TCngAlgorithm.Create('AES');

Destructors

`Destroy` destructor

destructor Destroy; override;

Closes the provider handle.

Properties

`Handle` property

property Handle: BCRYPT_HANDLE read FHandle;

The provider handle, for passing to BCrypt... functions. Owned by the object: do not close it yourself.

Methods

`ULongProperty` method

function ULongProperty(const Name: string): ULONG;

Reads a 32-bit property of the provider by its CNG name, for example BlockLength. Raises EAtlasCryptoError if CNG refuses.

Size := Algorithm.ULongProperty('BlockLength');

`SetStringProperty` method

procedure SetStringProperty(const Name, Value: string);

Sets a string property of the provider, for example ChainingMode to ChainingModeGCM. Raises EAtlasCryptoError if CNG refuses.

Algorithm.SetStringProperty('ChainingMode', 'ChainingModeGCM');

Examples

Read a property of the AES provider

Prints 16, the AES block length in bytes.

uses System.SysUtils, Atlas.Crypto.Cng;

procedure ShowAesBlockLength;
var
  Algorithm: TCngAlgorithm;
begin
  Algorithm := TCngAlgorithm.Create('AES');
  try
    WriteLn(Algorithm.ULongProperty('BlockLength'));
  finally
    Algorithm.Free;
  end;
end;

EAtlasCryptoError · TAtlasHash · TAtlasAesGcm

Also in Atlas Crypto

TAtlasHashCalculator · TAtlasFileProtector

TCngAlgorithm