PKCS#12

Short definition

PKCS#12 is a binary file format from the Public-Key Cryptography Standards series by RSA Laboratories, later codified as RFC 7292. A PKCS#12 file typically bundles:

• a private key
• the matching end-entity certificate
• optionally the certificate chain up to the root CA

…all inside a single, password-protected file. The common extensions are .p12 and .pfx (technically identical; .pfx comes from the Microsoft world).

For PDF signing via PAdES, PKCS#12 is the de-facto standard — almost every signing library and operating system understands the format.

What’s inside

A PKCS#12 container is ASN.1/DER-encoded and consists of SafeBags — small typed envelopes:

• keyBag / pkcs8ShroudedKeyBag — private key
• certBag — certificate (X.509)
• crlBag — revocation list (rarely used)
• secretBag — arbitrary secret
• safeContentsBag — nesting

Content is encrypted with PBE (Password-Based Encryption, usually PBES2 with AES-256 in modern tooling). The container’s integrity is secured by an HMAC using the same password.

Creating one with OpenSSL

# Bundle certificate + key into a .p12
openssl pkcs12 -export \
  -inkey private.key \
  -in signing.crt \
  -certfile ca-chain.crt \
  -out signing.p12 \
  -name "Dokmatiq Signing" \
  -passout pass:MySecretPassword

Modern OpenSSL versions (≥ 3.0) use strong algorithms by default; older tools still emit RC2/3DES and should be avoided.

A typical signing pipeline

1. Obtain a certificate from a CA (for qualified signatures: a Trust Service Provider listed in the EU Trusted List)
2. Generate the private key securely — ideally on an HSM or smart card
3. Export as PKCS#12 with a strong passphrase for transfer to the production environment
4. Store it in a secret-management system (Vault, cloud KMS, Docker secret)
5. Use it on every PAdES signing call

Using it with the Dokmatiq API

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

The API loads the PKCS#12 file, decrypts it in memory using the passphrase, signs, and discards the key afterwards — it is never persisted.

PKCS#12 vs. PEM

	PKCS#12 (.p12/.pfx)	PEM (.pem/.crt/.key)
Encoding	binary (DER)	ASCII (Base64 with headers)
Contains	key + cert + chain	usually one of them per file
Password protection	built in	external (or via -aes256 on the key)
Preferred by	Java, .NET, Windows	OpenSSL, Unix stacks

For PDF signing libraries (iText, PDFBox, signing APIs), PKCS#12 is the shortest path — everything needed for signing sits in one file.

Common pitfalls

1. Weak algorithms — old .p12 files use RC2/3DES; some Java versions throw Invalid keystore format. Fix: re-export with openssl pkcs12 -export -legacy or upgrade to PBES2/AES
2. Missing certificate chain — without intermediate CAs in the .p12, the recipient cannot validate the signature up to the root
3. Wrong password for key vs. container — PKCS#12 allows a separate passphrase for the embedded key; keep them aligned unless you manage them explicitly
4. Forgotten expiry — PKCS#12 itself does not expire, but the embedded certificate does. Monitor it