PKCS#12

Kurzdefinition

PKCS#12 ist ein binäres Dateiformat aus der Public-Key Cryptography Standards-Reihe der RSA Laboratories, später übernommen in RFC 7292. Eine PKCS#12-Datei bündelt typischerweise:

• einen privaten Schlüssel
• das zugehörige End-Entity-Zertifikat
• optional die Zertifikats­kette bis zur Wurzel-CA

…alles in einer einzigen, passwortgeschützten Datei. Die üblichen Endungen sind .p12 und .pfx (beide technisch identisch; .pfx stammt aus der Microsoft-Welt).

Für die PDF-Signatur per PAdES ist PKCS#12 der De-facto-Standard, weil fast jede Signatur-Bibliothek und jedes Betriebssystem das Format versteht.

Was drinsteckt

Ein PKCS#12-Container ist ASN.1/DER-kodiert und besteht aus SafeBags — kleinen Tüten mit typisiertem Inhalt:

• keyBag / pkcs8ShroudedKeyBag — privater Schlüssel
• certBag — Zertifikat (X.509)
• crlBag — Sperrliste (selten genutzt)
• secretBag — beliebiges Geheimnis
• safeContentsBag — Verschachtelung

Der Inhalt wird mit PBE (Password-Based Encryption, meist PBES2 mit AES-256 in modernen Tools) verschlüsselt. Die Integrität des Containers wird durch einen HMAC mit dem Passwort abgesichert.

Erzeugen mit OpenSSL

# Zertifikat + Key in eine .p12 verpacken
openssl pkcs12 -export \
  -inkey private.key \
  -in signatur.crt \
  -certfile ca-chain.crt \
  -out signatur.p12 \
  -name "Dokmatiq Signing" \
  -passout pass:GeheimesPasswort

Moderne OpenSSL-Versionen (≥ 3.0) nutzen dabei standardmäßig starke Algorithmen; ältere Tools erzeugen noch RC2/3DES und sollten vermieden werden.

Typischer Aufbau einer Signatur­pipeline

1. Zertifikat beziehen bei einer CA (qualifizierte Signatur: Trust-Service-Provider aus der EU Trusted List)
2. Privaten Schlüssel sicher erzeugen — idealerweise auf einem HSM oder einer Smart Card
3. Export als PKCS#12 mit starker Passphrase für den Transport in die Produktivumgebung
4. Hinterlegen in einer Secret-Management-Lösung (Vault, Cloud KMS, Docker Secret)
5. Nutzen bei jedem PAdES-Signatur-Call

Mit der Dokmatiq-API nutzen

curl -X POST https://api.dokmatiq.com/v1/pdf/sign \
  -H "Authorization: Bearer $DOKMATIQ_KEY" \
  -F "document=@rechnung.pdf" \
  -F "certificate=@signatur.p12" \
  -F "passphrase=GeheimesPasswort" \
  -F "profile=PAdES-B-LT" \
  -o signiert.pdf

Die API liest die PKCS#12-Datei, entschlüsselt sie mit der Passphrase im Speicher, signiert und verwirft den Schlüssel danach — er wird nicht persistiert.

PKCS#12 vs. PEM

	PKCS#12 (.p12/.pfx)	PEM (.pem/.crt/.key)
Kodierung	binär (DER)	ASCII (Base64 mit Headern)
Enthält	Key + Zert + Kette	meist nur eines davon pro Datei
Passwort­schutz	integriert	extern (oder per -aes256 am Key)
Bevorzugt von	Java, .NET, Windows	OpenSSL, Unix-Stacks

Für PDF-Signatur-Libraries (iText, PDFBox, Signature-APIs) ist PKCS#12 der kürzeste Weg — alles, was man zum Signieren braucht, liegt in einer Datei.

Häufige Stolpersteine

1. Schwache Algorithmen — alte .p12-Dateien nutzen RC2/3DES; manche Java-Versionen werfen Invalid keystore format. Lösung: mit openssl pkcs12 -export -legacy neu exportieren oder auf PBES2/AES upgraden
2. Fehlende Zertifikats­kette — ohne Zwischen-CAs in der .p12 kann der Empfänger die Signatur nicht bis zur Wurzel validieren
3. Falsches Passwort für Key vs. Container — PKCS#12 kennt separates Passwort für den integrierten Key; beide müssen gleich sein, wenn man sie nicht getrennt pflegt
4. Ablauf vergessen — PKCS#12 selbst läuft nicht ab, aber das eingebettete Zertifikat. Monitoring einrichten