Net-Base Magazin

30.05.2026

AES-Verschlüsselung in Delphi: Containerformat mit Salt/IV, PBKDF2, Integrität und Streaming

Ein robuster Delphi-Source-Schnipsel für AES-Verschlüsselung als streamfähiges Containerformat: Magic/Version, Salt und IV, PBKDF2-Key-Derivation und optionaler HMAC für Integrität – inklusive Migrations- und Betriebsfallen.

30.05.2026

Vom Magazinthema zur Projektpraxis

Passende Leistungs- und Technikseiten zum Beitrag

Sie bekommen eine Support-Mail: „Export-Datei lässt sich nach Update nicht mehr importieren.“ Der Dateiname ist korrekt, das Passwort „ist sicher richtig“, und bei einem Kunden klappt es, bei einem anderen nicht. Wenn man dann in die Implementierung schaut, steht dort oft sinngemäß: Passwort → SHA256 → AES-CBC mit festem IV → Base64. Genau an diesem Punkt wird AES Verschlüsselung Delphi vom „Algorithmus-Thema“ zum Betriebsproblem: fehlende Versionierung, wiederverwendete IVs, keine Integrität und keine sauberen Parameter im Datenformat.

Dieser Refresh liefert deshalb kein „AES-String verschlüsseln“-Snippet, sondern ein kleines, belastbares Containerformat für Streams (Dateien, BLOBs, Backups). Mit Magic/Version, PBKDF2-Key-Derivation (KDF = Key Derivation Function, also Passwort-zu-Key-Ableitung), zufälligem Salt und IV – plus einem optionalen Integritätspfad (HMAC), der die typischen „Padding kaputt“-Fehlerbilder in der Praxis entschärft.

Szenarioanalyse: Wo AES in Delphi-Projekten wirklich kippt

Konstruierte, aber sehr typische Situation in individueller Unternehmenssoftware: Ein Delphi-Client exportiert tagsüber verschlüsselte Belege; ein Serverdienst (Windows- oder Windows- und Linux-Services) importiert nachts. Nach einem Rollout werden einige Dateien „unlesbar“. Die Ursachen sind selten „AES ist kaputt“, sondern:

  • IV-Wiederverwendung: CBC (Cipher Block Chaining) benötigt pro Verschlüsselung einen neuen IV (Initialisierungsvektor). Ein fester IV ist ein reales Informationsleck, gerade bei gleichartigen Dateiköpfen.
  • Kein Formatvertrag: Ohne Magic/Version/Parameter ist nicht nachvollziehbar, womit verschlüsselt wurde (Iterationszahl, Modus, Salt-Länge, Padding).
  • Keine Integrität: AES-CBC schützt Vertraulichkeit, aber nicht gegen Manipulation. Im Betrieb bedeutet das: Ein einziger Bitflip (Storage/Transfer) kann zu schwer zu diagnostizierenden Exceptions führen.
  • „Passwort ist Key“: Direktes Hashen oder Abschneiden eines Passworts als AES-Key macht Offline-Angriffe unnötig günstig.

AES Verschlüsselung Delphi als Container: Header, Salt, IV, Parameter

Der Kerntrick ist unspektakulär, aber entscheidend: Wir verschlüsseln nicht „irgendeinen String“, sondern definieren ein minimales Containerformat, das sich versionieren und debuggen lässt. Vorschlag für Version 1:

Feld Größe Zweck
Magic 4 Byte Schneller Formatcheck (z. B. „NBAE“)
Version 1 Byte Migrationspfad: „read old, write new“
Iterations 4 Byte PBKDF2-Parameter, später erhöhbar
Salt 16 Byte Einzigartig pro Container, für KDF
IV 16 Byte Einzigartig pro Container, für AES-CBC
Ciphertext variabel Streamverschlüsselte Nutzdaten
HMAC (optional) 32 Byte Integrität über Header+Ciphertext

Wichtig: Salt und IV sind nicht geheim. Sie dürfen im Header stehen. Geheim bleibt das Passwort bzw. der daraus abgeleitete Key.

Delphi-Source: Stream-Container mit PBKDF2, AES-CBC und optionalem HMAC

Der Code ist absichtlich so geschrieben, dass Sie darunter Ihre Crypto-Library (z. B. DEC oder eine interne CNG/OpenSSL-Anbindung) austauschen können. Das Wertvolle ist das Format, das Streaming-Pattern und die Fehlerdisziplin.

Delphi
unit Nb.AesContainer;

interface

uses
  System.SysUtils, System.Classes;

type
  ENbCryptoError = class(Exception);

  TNbAesContainer = class
  public
    class procedure EncryptStreamToStream(const AIn, AOut: TStream;
      const APassword: string; const AIterations: Cardinal = 200000;
      const AWithHmac: Boolean = True);

    class procedure DecryptStreamToStream(const AIn, AOut: TStream;
      const APassword: string; const AExpectHmac: Boolean = True);
  end;

implementation

const
  CMagic: array[0..3] of AnsiChar = ('N','B','A','E');
  CVersionV1: Byte = 1;
  CSaltLen = 16;
  CIvLen   = 16;
  CHmacLen = 32; // HMAC-SHA-256

type
  TNbHeaderV1 = packed record
    Magic: array[0..3] of AnsiChar;
    Version: Byte;
    Flags: Byte; // Bit0: HMAC vorhanden
    Iterations: Cardinal;
    Salt: array[0..CSaltLen-1] of Byte;
    IV: array[0..CIvLen-1] of Byte;
  end;

// --- Bibliotheksabhängige Primitive (Platzhalter) ---

procedure FillRandomBytes(var B: TBytes);
begin
  // MUSS OS-CSPRNG sein, kein Random().
  // Windows: BCryptGenRandom; Linux: getrandom()/urandom.
  raise ENbCryptoError.Create('FillRandomBytes: CSPRNG nicht angebunden');
end;

function PBKDF2_HMAC_SHA256(const APassword: string; const ASalt: TBytes;
  const AIterations, AKeyLen: Cardinal): TBytes;
begin
  // Liefert AKeyLen Bytes. Für AES(32) + HMAC(32) z. B. 64.
  raise ENbCryptoError.Create('PBKDF2_HMAC_SHA256: nicht angebunden');
end;

procedure AES256_CBC_EncryptStream(const AKey, AIV: TBytes; const AIn, AOut: TStream);
begin
  // Stream-Implementierung mit PKCS#7 Padding.
  raise ENbCryptoError.Create('AES256_CBC_EncryptStream: nicht angebunden');
end;

procedure AES256_CBC_DecryptStream(const AKey, AIV: TBytes; const AIn, AOut: TStream);
begin
  raise ENbCryptoError.Create('AES256_CBC_DecryptStream: nicht angebunden');
end;

function HMAC_SHA256_Stream(const AKey: TBytes; const AIn: TStream;
  const AFromPos, AToPosExclusive: Int64): TBytes;
begin
  // HMAC über einen Streambereich; muss die Position danach wiederherstellen.
  raise ENbCryptoError.Create('HMAC_SHA256_Stream: nicht angebunden');
end;

// --- Header I/O ---

procedure WriteHeaderV1(const AOut: TStream; const H: TNbHeaderV1);
begin
  if AOut.Write(H, SizeOf(H)) <> SizeOf(H) then
    raise ENbCryptoError.Create('Header konnte nicht geschrieben werden');
end;

function ReadHeaderV1(const AIn: TStream): TNbHeaderV1;
var
  H: TNbHeaderV1;
  I: Integer;
begin
  if AIn.Read(H, SizeOf(H)) <> SizeOf(H) then
    raise ENbCryptoError.Create('Header unvollständig');

  for I := 0 to 3 do
    if H.Magic[I] <> CMagic[I] then
      raise ENbCryptoError.Create('Kein gültiger Container (Magic stimmt nicht)');

  if H.Version <> CVersionV1 then
    raise ENbCryptoError.CreateFmt('Unbekannte Container-Version: %d', [H.Version]);

  // Plausibilitätsgrenzen gegen DoS durch absurde KDF-Parameter
  if (H.Iterations < 10000) or (H.Iterations > 5000000) then
    raise ENbCryptoError.Create('Iterationszahl außerhalb plausibler Grenzen');

  Result := H;
end;

class procedure TNbAesContainer.EncryptStreamToStream(const AIn, AOut: TStream;
  const APassword: string; const AIterations: Cardinal; const AWithHmac: Boolean);
var
  H: TNbHeaderV1;
  Salt, IV, KeyMaterial, AesKey, HmacKey: TBytes;
  StartPos, EndPos: Int64;
  Mac: TBytes;
  Flags: Byte;
begin
  if APassword = '' then
    raise ENbCryptoError.Create('Passwort darf nicht leer sein');

  SetLength(Salt, CSaltLen);
  SetLength(IV, CIvLen);
  FillRandomBytes(Salt);
  FillRandomBytes(IV);

  Flags := 0;
  if AWithHmac then
    Flags := Flags or $01;

  Move(CMagic[0], H.Magic[0], 4);
  H.Version := CVersionV1;
  H.Flags := Flags;
  H.Iterations := AIterations;
  Move(Salt[0], H.Salt[0], CSaltLen);
  Move(IV[0], H.IV[0], CIvLen);

  WriteHeaderV1(AOut, H);

  // Key Separation: aus PBKDF2 64 Bytes ableiten und aufteilen.
  KeyMaterial := PBKDF2_HMAC_SHA256(APassword, Salt, AIterations, 64);
  SetLength(AesKey, 32);
  SetLength(HmacKey, 32);
  Move(KeyMaterial[0], AesKey[0], 32);
  Move(KeyMaterial[32], HmacKey[0], 32);

  StartPos := AOut.Position; // Ciphertext startet hier
  AES256_CBC_EncryptStream(AesKey, IV, AIn, AOut);
  EndPos := AOut.Position;

  // Optional: HMAC über Header+Ciphertext.
  if AWithHmac then
  begin
    // HMAC-Range: von 0 (Header) bis EndPos (exklusive), danach Mac anhängen.
    Mac := HMAC_SHA256_Stream(HmacKey, AOut, 0, EndPos);
    if Length(Mac) <> CHmacLen then
      raise ENbCryptoError.Create('HMAC-Länge unerwartet');
    if AOut.Write(Mac[0], Length(Mac)) <> Length(Mac) then
      raise ENbCryptoError.Create('HMAC konnte nicht geschrieben werden');
  end;
end;

class procedure TNbAesContainer.DecryptStreamToStream(const AIn, AOut: TStream;
  const APassword: string; const AExpectHmac: Boolean);
var
  H: TNbHeaderV1;
  Salt, IV, KeyMaterial, AesKey, HmacKey: TBytes;
  HasHmac: Boolean;
  DataEndPos, MacPos: Int64;
  StoredMac, CalcMac: TBytes;
begin
  if APassword = '' then
    raise ENbCryptoError.Create('Passwort darf nicht leer sein');

  H := ReadHeaderV1(AIn);
  HasHmac := (H.Flags and $01) = $01;

  if AExpectHmac and (not HasHmac) then
    raise ENbCryptoError.Create('Container hat keinen HMAC, Integrität nicht prüfbar');

  SetLength(Salt, CSaltLen);
  SetLength(IV, CIvLen);
  Move(H.Salt[0], Salt[0], CSaltLen);
  Move(H.IV[0], IV[0], CIvLen);

  KeyMaterial := PBKDF2_HMAC_SHA256(APassword, Salt, H.Iterations, 64);
  SetLength(AesKey, 32);
  SetLength(HmacKey, 32);
  Move(KeyMaterial[0], AesKey[0], 32);
  Move(KeyMaterial[32], HmacKey[0], 32);

  // Wenn HMAC vorhanden: vor dem Decrypt prüfen.
  if HasHmac then
  begin
    DataEndPos := AIn.Size - CHmacLen;
    if DataEndPos < SizeOf(TNbHeaderV1) then
      raise ENbCryptoError.Create('Container zu klein');

    MacPos := DataEndPos;

    SetLength(StoredMac, CHmacLen);
    AIn.Position := MacPos;
    if AIn.Read(StoredMac[0], CHmacLen) <> CHmacLen then
      raise ENbCryptoError.Create('HMAC konnte nicht gelesen werden');

    CalcMac := HMAC_SHA256_Stream(HmacKey, AIn, 0, MacPos);
    if Length(CalcMac) <> CHmacLen then
      raise ENbCryptoError.Create('HMAC-Länge unerwartet');

    if not CompareMem(@StoredMac[0], @CalcMac[0], CHmacLen) then
      raise ENbCryptoError.Create('HMAC ungültig (Passwort falsch oder Daten beschädigt)');

    // Ciphertext liegt zwischen Header-Ende und MacPos
    AIn.Position := SizeOf(TNbHeaderV1);
    // Die eigentliche Stream-Decrypt-Implementierung muss bis MacPos lesen.
    // Variante: AIn in einen begrenzten Stream (RangeStream) wrappen.
  end
  else
    AIn.Position := SizeOf(TNbHeaderV1);

  // Hinweis: Für HasHmac=True sollte AES256_CBC_DecryptStream nicht bis EOF lesen,
  // sondern bis vor den HMAC. Das lösen Sie sauber mit einem RangeStream-Wrapper.
  AES256_CBC_DecryptStream(AesKey, IV, AIn, AOut);
end;

end.

Zweck: Ein Container, der im Betrieb erklärbar bleibt: Magic/Version für Diagnose, Iterationszahl für spätere Anpassungen, Salt/IV pro Datei, Stream-Verarbeitung statt RAM-Spitzen. Randbedingungen: Sie müssen (1) einen echten CSPRNG anbinden und (2) Ihre Crypto-Library streamfähig einsetzen. Stolperfallen: Der Decrypt-Pfad mit HMAC braucht eine Begrenzung („RangeStream“), damit der AES-Decrypt nicht aus Versehen den angehängten HMAC als Ciphertext interpretiert. Varianten: Statt CBC+HMAC können Sie auf AES-GCM wechseln (AEAD = Authenticated Encryption with Associated Data, also Verschlüsselung plus Authentifizierung in einem Schritt), wenn Ihre Bibliothek das stabil kann.

Warum KDF und Zufall keine Details sind (mit Quellen)

Zwei Aussagen, die in Reviews immer wieder diskutiert werden, lassen sich klar begründen:

  • Salt und IV müssen aus einem kryptografisch sicheren Zufall kommen: Ein CSPRNG (Cryptographically Secure PRNG) ist so konstruiert, dass aus beobachteten Ausgaben keine Vorhersagen möglich sind. Genau darum ist Random() oder „Hash aus Zeitstempel“ ungeeignet. Für Windows ist das in der Plattform-API über CNG abbildbar, Einstiegspunkt ist z. B. Microsofts CNG-Portal.
  • PBKDF2 ist kein Luxus, sondern Bremsklotz gegen Offline-Angriffe: Passwörter sind typischerweise schwächer als Keys; PBKDF2 erhöht gezielt die Kosten pro Passwortversuch. Die Funktionsweise ist in RFC 8018 (PKCS #5) sauber beschrieben, inklusive Parametern und Sicherheitsüberlegungen.

Migrationspfad: „read old, write new“ ohne Wartungsfenster

Wenn bereits Daten im Feld liegen, ist ein Big-Bang-Umstieg selten realistisch. Ein praxistauglicher Pfad:

  1. Erkennung: Magic+Version prüfen. Wenn kein Magic, optional Fallback auf Legacy-Heuristik (z. B. Base64-Pattern, alte Header-Länge).
  2. Lesen: Alte Formate weiterhin entschlüsseln können (nur in einem klar isolierten Modul, damit es später entfernbar bleibt).
  3. Schreiben: Ab einem Stichtag ausschließlich das neue Format erzeugen (Version 1 mit Salt/IV/KDF, optional HMAC).
  4. Lazy Migration: Beim erfolgreichen Lesen eines Legacy-Containers im Hintergrund in das neue Format re-encrypten, wenn Prozess und Performance das erlauben.

Threading, Streams und Fehlerbilder: Betrieb statt Demo

In Desktop-Clients und Services kommt AES selten allein: Export-Threads, Hintergrund-Tasks, BDE-Ablösung mit nativer Anbindung-BLOB-Streams, Upload in REST-APIs. Drei Punkte vermeiden unnötige Incidents:

  • Stream-Contract dokumentieren: Lesen/Schreiben ab aktueller Position. Vor Wiederverwendung Position explizit setzen. Das klingt banal, ist aber eine häufige Ursache für „sporadisch kaputt“.
  • Fehler nach außen neutral, intern präzise: Extern „Ungültiger Container oder Passwort falsch“. Intern unterscheiden: Magic/Version-Fehler, Iterationsgrenzen, HMAC/Tag ungültig, Decrypt/Padding-Exception.
  • Integrität zuerst prüfen: Bei CBC+HMAC erst HMAC prüfen, dann entschlüsseln. Das reduziert Side-Channel-artige Fehlermuster und spart CPU bei defekten Daten.

Grenzen und Risiken: Was dieser Ansatz nicht löst

Ein Containerformat ist kein Ersatz für Transportverschlüsselung oder Schlüsselmanagement:

  • TLS bleibt Pflicht für Datenübertragung. AES im Payload ersetzt kein sauberes HTTPS/TLS-Setup.
  • Passwortverwaltung ist ein eigenes Thema: Wenn Sie „Passwort im Code“ oder „in INI“ speichern, gewinnen Sie mit AES nur begrenzt. Für Secrets sind OS-Secret-Stores oder Vault-Konzepte oft passender.
  • Interop braucht Spezifikation: Wenn andere Sprachen konsumieren, müssen Endianness, Padding/Mode, Headerlayout und Encoding exakt dokumentiert werden (oder Sie nutzen ein etabliertes Austauschformat).

Fazit: AES Verschlüsselung Delphi ist ein Format- und Betriebsvertrag

Der Unterschied zwischen „AES läuft“ und „AES hält im Feld“ ist nicht der Algorithmus, sondern die Engineering-Umgebung: Container-Header mit Version, Salt/IV pro Objekt, PBKDF2 mit parametrisierter Iterationszahl, Stream-Verarbeitung und (für neue Daten) Integrität via HMAC oder GCM. Genau diese Disziplin macht Verschlüsselung in gewachsenen Delphi-Landschaften wartbar, migrierbar und debugbar.

Wenn Sie ein Legacy-Format ablösen müssen oder die Crypto-Schicht in einem Delphi-Client/Service sauber kapseln wollen (inklusive RangeStream, Logging und Migrationspfad), lässt sich das am schnellsten in einem kurzen Architektur-Review klären: Kontakt aufnehmen.

Für dieses Thema sind auch Aes-256-Cbc Delphi und Delphi Aes wichtig. Der Beitrag ordnet diese Aspekte verständlich ein und zeigt, worauf es im Alltag ankommt.

Projekt oder Modernisierungsvorhaben mit Net-Base besprechen.

nächster Schritt

Wenn aus dem Thema ein reales Projekt wird, sollten Architektur, Bestand und Betrieb früh zusammen betrachtet werden.

Wir unterstuetzen nicht nur bei Einzelfragen, sondern auch dann, wenn aus Source-Schnipseln, Legacy-Themen oder Portalideen ein belastbares Unternehmensprojekt werden soll.

  • Bestand, Zielbild und technische Risiken werden zusammen bewertet.
  • REST, Datenzugriff, Portale und Rollout werden nicht als Spätfolgen verschoben.
  • Sie sehen früh, welcher Weg wirtschaftlich und betrieblich tragfähig ist.

Beitrag teilen

Diesen Beitrag direkt weitergeben

LinkedIn, X, Facebook, WhatsApp und E-Mail sind sofort verfügbar. für Instagram bereiten wir Link und Kurztext direkt vor.

E-Mail

Instagram oeffnet in einem neuen Tab. Link und Kurztext werden vorher in die Zwischenablage kopiert.

Kommentar schreiben

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert