Apple's CryptoKit (iOS 26 / macOS 26 and later) and swift-crypto now ship the two NIST post-quantum standards. They solve different problems and are easy to mix up, so here's a summary of what each one is for, how they compare with the classical algorithms they replace, and how to use them from Swift.
The short version
- ML-KEM (FIPS 203, formerly Kyber) is a key encapsulation mechanism. It replaces ECDH (X25519 / P-256 key agreement): two parties end up with the same 32-byte shared secret.
- ML-DSA (FIPS 204, formerly Dilithium) is a digital signature scheme. It replaces ECDSA / Ed25519: sign with a private key, verify with the public key.
You don't choose one over the other. A protocol that needs both confidentiality and authentication uses ML-KEM for key establishment and ML-DSA for signatures, just as it would use ECDH plus ECDSA today.
Why the urgency differs
- Key exchange is urgent now because of "harvest now, decrypt later": traffic recorded today can be decrypted once a large quantum computer exists. That's why ML-KEM is being rolled out first, and why iOS 26 enables hybrid X25519MLKEM768 key exchange in TLS 1.3 for URLSession and Network.framework.
- Signatures are less urgent for short-lived data, since forging a signature later doesn't help an attacker in the past. They matter most for long-lived trust: firmware and software signing, root keys, documents that must stay verifiable for years.
Sizes compared with classical algorithms
Key encapsulation (bytes):
| Public key | Private key | Ciphertext | Shared secret | NIST category | |
|---|---|---|---|---|---|
| X25519 (ECDH) | 32 | 32 | 32 (ephemeral key) | 32 | none (classical) |
| ML-KEM-768 | 1,184 | 2,400 | 1,088 | 32 | 3 |
| ML-KEM-1024 | 1,568 | 3,168 | 1,568 | 32 | 5 |
Signatures (bytes):
| Public key | Private key | Signature | NIST category | |
|---|---|---|---|---|
| Ed25519 | 32 | 32 | 64 | none (classical) |
| P-256 ECDSA | 64 | 32 | 64 (raw) | none (classical) |
| ML-DSA-65 | 1,952 | 4,032 | 3,309 | 3 |
| ML-DSA-87 | 2,592 | 4,896 | 4,627 | 5 |
Speed is rarely the problem: ML-KEM is in the same range as X25519, and ML-DSA verification is fast, though signing is slower than Ed25519. The cost is size. A 3.3 KB signature instead of 64 bytes matters for things like JWTs, QR codes, BLE payloads, push notification bodies and per-message signatures.
Which parameter set? ML-KEM-768 and ML-DSA-65 (category 3) are the usual defaults. Use the 1024 / 87 variants when a policy requires category 5 (e.g. CNSA 2.0).
ML-KEM in CryptoKit
import CryptoKit
// Recipient: create a key pair and publish the public key.
let privateKey = try MLKEM768.PrivateKey()
let publicKey = privateKey.publicKey
// Sender: encapsulate against the recipient's public key.
let result = try publicKey.encapsulate()
let senderSecret = result.sharedSecret // use this locally
let ciphertext = result.encapsulated // send this to the recipient
// Recipient: recover the same secret.
let recipientSecret = try privateKey.decapsulate(ciphertext)
// Never use the raw secret directly as a key; derive one.
let key = recipientSecret.withUnsafeBytes {
HKDF<SHA256>.deriveKey(
inputKeyMaterial: SymmetricKey(data: Data($0)),
info: Data("my-app v1 session".utf8),
outputByteCount: 32)
}
Notes:
- For ephemeral (forward-secret) exchanges use
MLKEM768.OneTimePrivateKey. It can't be saved or re-imported, and in swift-crypto 5 itsdecapsulateisconsuming, so the compiler enforces single use. UseMLKEM768.PrivateKeywhen you need to persist the key. - Hardware-backed keys are available as
SecureEnclave.MLKEM768.PrivateKey()/SecureEnclave.MLKEM1024.PrivateKey(). The Secure Enclave doesn't supportOneTimePrivateKey.
Prefer hybrid: X-Wing with HPKE
ML-KEM is new, and implementation bugs are a bigger practical risk than the maths. The common recommendation is a hybrid that combines ML-KEM with X25519, so an attacker has to break both. CryptoKit ships X-Wing (ML-KEM-768 + X25519) as an HPKE ciphersuite, which also gives you authenticated encryption in one step:
let recipientKey = try XWingMLKEM768X25519.PrivateKey()
let suite = HPKE.Ciphersuite.XWingMLKEM768X25519_SHA256_AES_GCM_256
let info = Data("my-app v1".utf8)
// Sender
var sender = try HPKE.Sender(recipientKey: recipientKey.publicKey,
ciphersuite: suite, info: info)
let sealed = try sender.seal(Data("hello".utf8),
authenticating: Data("header".utf8))
let encapsulatedKey = sender.encapsulatedKey // send with the ciphertext
// Recipient
var recipient = try HPKE.Recipient(privateKey: recipientKey, ciphersuite: suite,
info: info, encapsulatedKey: encapsulatedKey)
let plaintext = try recipient.open(sealed, authenticating: Data("header".utf8))
If you're designing a new protocol on Apple platforms, this is the easiest place to start.
ML-DSA in CryptoKit
let signingKey = try MLDSA65.PrivateKey()
let message = Data("release-1.4.2.zip sha256=ā¦".utf8)
let signature = try signingKey.signature(for: message)
let ok = signingKey.publicKey.isValidSignature(signature: signature, for: message)
Hardware-backed: SecureEnclave.MLDSA65.PrivateKey() and SecureEnclave.MLDSA87.PrivateKey().
Hybrid signatures
The same "break both" reasoning applies to signatures. Sign with ML-DSA and a classical key, and require both to verify:
struct HybridSignature {
let mldsa: Data
let ecdsa: Data
}
func sign(_ message: Data,
pq: SecureEnclave.MLDSA65.PrivateKey,
classical: SecureEnclave.P256.Signing.PrivateKey) throws -> HybridSignature {
HybridSignature(
mldsa: try pq.signature(for: message),
ecdsa: try classical.signature(for: message).rawRepresentation)
}
func verify(_ message: Data, _ sig: HybridSignature,
pq: MLDSA65.PublicKey, classical: P256.Signing.PublicKey) -> Bool {
guard let ecdsa = try? P256.Signing.ECDSASignature(rawRepresentation: sig.ecdsa)
else { return false }
// Both must pass; never accept "either".
return pq.isValidSignature(signature: sig.mldsa, for: message)
&& classical.isValidSignature(ecdsa, for: message)
}
In a real wire format, include an algorithm identifier and bind both signatures to it, so an attacker can't strip one signature and present the other alone.
Side-by-side summary
| ML-KEM | ML-DSA | |
|---|---|---|
| Standard | FIPS 203 | FIPS 204 |
| Replaces | ECDH (X25519, P-256 key agreement) | ECDSA, Ed25519 |
| Gives you | shared secret (confidentiality) | signature (authenticity, integrity) |
| Threat it addresses | harvest now, decrypt later | future forgery of long-lived signatures |
| Priority | now | for long-lived keys and artifacts |
| CryptoKit types | MLKEM768, MLKEM1024, XWingMLKEM768X25519 |
MLDSA65, MLDSA87 |
| Secure Enclave | yes (not one-time keys) | yes |
| Recommended use | hybrid via X-Wing HPKE | hybrid with ECDSA / Ed25519 |
Cross-platform (Linux, server-side Swift)
swift-crypto provides the same API outside Apple platforms, backed by BoringSSL. swift-crypto 5 aligns its API surface with the CryptoKit that ships in Xcode 27, requires Swift 6.2, and adds the KEMOneTimePrivateKey protocol with consuming func decapsulate(_:). That means the same code can run on an iOS client and a Linux server.
Practical checklist
- Inventory where you use ECDH and ECDSA/Ed25519, and how long the protected data or signatures need to stay secure.
- Key exchange first: move custom protocols to X-Wing HPKE, and check that your servers negotiate X25519MLKEM768 in TLS 1.3.
- Budget for size: check message limits (QR, BLE, headers, tokens) before adopting ML-DSA.
- Make algorithms negotiable in your wire formats (crypto agility), so you can change parameter sets later without a breaking protocol change.
- Use the Secure Enclave for long-lived private keys where possible.
References:
- Apple: Enhancing your app's privacy and security with quantum-secure workflows
- NIST FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA)
- apple/swift-crypto releases
Corrections welcome, especially from anyone who has shipped these in production or measured the size impact on real protocols.