Cryptography with CryptoKit — AEAD, ECDH, signatures, HPKE, ML-KEM

cs · folio

In one line: Symmetric AEAD (AES-GCM, ChaCha20-Poly1305) encrypts and authenticates bulk data under one key and a nonce never repeated under that key; asymmetric keys agree on that key (ECDH → HKDF, or a KEM inside HPKE) and sign (ECDSA, Ed25519, ML-DSA). CryptoKit ships vetted primitives with safe defaults — the job is choosing them, managing keys and nonces, and never inventing a primitive, mode or protocol.

Download PDF Print view LaTeX source

Cryptography with CryptoKit — AEAD, ECDH, signatures, HPKE, ML-KEM — figure 1

How it works

  • AEAD = confidentiality + integrity + authenticity; open throws on any flipped bit or wrong AAD. AES-GCM: 128/192/256-bit key. ChaCha20-Poly1305: 256-bit key, ∼3× faster than AES on chips without AES hardware. Both: 12-byte nonce, 16-byte tag.
  • Nonce reuse under one key: C1 ⊕C2 = P1 ⊕P2, and GCM gives away its hash key → trivial forgeries under that key (Poly1305: the one-time key repeats). A repeated nonce on decrypt is harmless.
  • ECDH output is not uniformly random: HKDF extract (salt; none = zeros), then expand with info — one purpose per key, ≤255 × hash length. Ephemeral pairs, discarded → forward secrecy.
  • ECDSA s = (h + x r)/k: the same k twice gives k = (h1 - h2)/(s1 - s2), then the private key x = (s k - h)/r. RFC 6979 k and EdDSA are deterministic — CryptoKit randomizes both: new bytes every call for the same key + message.
  • HPKE (RFC 9180) = KEM → KDF → AEAD to a public key; nonce = base nonce XOR sequence number, so open in the order sealed: no loss or reordering, no replay protection, no forward secrecy if the recipient key leaks.

AEAD limits per key

constructionper (key, nonce)random nonces
AES-256-GCM∼64 GB232 messages
ChaCha20-Poly1305 (IETF)256 GB232 messages
XChaCha20 (not in CryptoKit)∼264 Bno practical limit

1 MB messages, 2-32 attack chance: AES-GCM ∼232 encryptions per key, ChaCha 248. Then rekey; chunk huge messages.

Security strength — equal rows

bitsAESelliptic curveRSAhash
128AES-128P-256, X25519, Ed255193072SHA-256
192AES-192P-3847680SHA-384
256AES-256P-52115360SHA-512

ML-DSA-44 / 65 / 87 = NIST levels 2 / 3 / 5 (3 ≈ AES-192, 5 ≈ AES-256). No RSA in CryptoKit → SecKey.

Example — the CryptoKit calls

let mine = Curve25519.KeyAgreement.PrivateKey()        // ephemeral
let key = try mine.sharedSecretFromKeyAgreement(with: theirPub)
  .hkdfDerivedSymmetricKey(using: SHA256.self, salt: salt,
     sharedInfo: Data("chat v1".utf8), outputByteCount: 32)
let box = try AES.GCM.seal(msg, using: key, authenticating: hdr)
let wire = box.combined!        // random 12 B nonce | ct | tag
let plain = try AES.GCM.open(.init(combined: wire), using: key,
                             authenticating: hdr)
let signer = P256.Signing.PrivateKey()  // SecureEnclave.P256: same
let sig = try signer.signature(for: msg)  // SHA-256, randomized
let ok = signer.publicKey.isValidSignature(sig, for: msg)
let jws = sig.rawRepresentation         // r|s 64 B; X.509: DER
// HPKE, hybrid post-quantum (iOS 26)
let suite = HPKE.Ciphersuite.XWingMLKEM768X25519_SHA256_AES_GCM_256
let sk = try XWingMLKEM768X25519.PrivateKey()
var tx = try HPKE.Sender(recipientKey: sk.publicKey,
                         ciphersuite: suite, info: info)
let c1 = try tx.seal(m1)       // send tx.encapsulatedKey once
var rx = try HPKE.Recipient(privateKey: sk, ciphersuite: suite,
                 info: info, encapsulatedKey: tx.encapsulatedKey)
let p1 = try rx.open(c1)       // open in the order sealed

Storing keys: P-256/384/521 → SecKey via x963Representation; Curve25519 and SymmetricKey bytes → a generic-password Keychain item.

CryptoKit by release

iOSadded
13SymmetricKey(size:) · AES.GCM · ChaChaPoly · SHA256/384/512 · HMAC · Curve25519, P256/384/521 agreement + signing · SecureEnclave.P256 · Insecure.MD5 / .SHA1 (the namespace is the warning)
14HKDF: extract, expand, deriveKey
15AES.KeyWrap (RFC 3394)
17HPKE (Sender, Recipient; 4 classical suites), KEM
26MLKEM768/1024, MLDSA65/87, XWingMLKEM768X25519 (+ HPKE suite), SHA-3; the ML types also under SecureEnclave
27one-time ML-KEM / X-Wing private keys; seal/open(inPlace:) on spans

Secure Enclave

Key types: P256 (signing, agreement), since iOS 26 also MLKEM768/1024 and MLDSA65/87 — nothing symmetric, no one-time keys. Born inside, never leaves: dataRepresentation is an encrypted block only the same SE can restore (store it in the Keychain). Default access control AfterFirstUnlockThisDeviceOnly, no flags.

Post-quantum — why, and the cost

Ciphertext recorded today can fall to a future quantum computer, so key agreement moves first: FIPS 203 (ML-KEM), 204 (ML-DSA), August 2024. A KEM encapsulates to a public key → (secret, ciphertext); only the private key decapsulates, in CryptoKit straight to a SymmetricKey. Hybrid = classical + PQ, safe while either holds: X-Wing = ML-KEM-768 + X25519 (aims at 128-bit, 768 for margin); signatures: ML-DSA ‖ ECDSA, verify both.

Cryptography with CryptoKit — AEAD, ECDH, signatures, HPKE, ML-KEM — figure 2

One-time ML-KEM / X-Wing keys (iOS 27): faster, consumed by decapsulate, never saved.

Traps

  • ECB (equal blocks → equal ciphertext); CBC without a MAC → padding oracles. Use AEAD.
  • Fixed or reset nonce (a counter restarting after reinstall; two devices, one key). seal(inPlace:) has no random default.
  • Hard-coded keys — strings finds them. Password as a key → slow KDF first: CCKeyDerivationPBKDF (OWASP ≥600 000 × HMAC-SHA256) or Argon2id.
  • Tag compared after conversion to Data / [UInt8] / hex String with == — early exit leaks timing. swift-crypto’s MAC == and isValidAuthenticationCode are constant-time.
  • Signature bytes as an ID or test oracle — they differ every call; verify instead. ES256 JWS = the 64-byte raw form, not DER.
  • One key, two jobs → separate HKDF info. Unauthenticated ECDH = agreeing with the attacker.
  • Key bytes from GameplayKit (“not cryptographically robust”) or a seeded test RNG.

Remember

Agree (ECDH or KEM) → derive (HKDF) → seal (AEAD, unique nonce) → sign what must be proven; hybrid PQ for secrets that must outlive a quantum computer. Never roll your own.

Report a problem ·Discuss this folio