ML-KEM and ML-DSA in Swift: what they are, how they compare, and CryptoKit examples

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 its decapsulate is consuming, so the compiler enforces single use. Use MLKEM768.PrivateKey when you need to persist the key.
  • Hardware-backed keys are available as SecureEnclave.MLKEM768.PrivateKey() / SecureEnclave.MLKEM1024.PrivateKey(). The Secure Enclave doesn't support OneTimePrivateKey.

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

  1. Inventory where you use ECDH and ECDSA/Ed25519, and how long the protected data or signatures need to stay secure.
  2. Key exchange first: move custom protocols to X-Wing HPKE, and check that your servers negotiate X25519MLKEM768 in TLS 1.3.
  3. Budget for size: check message limits (QR, BLE, headers, tokens) before adopting ML-DSA.
  4. Make algorithms negotiable in your wire formats (crypto agility), so you can change parameter sets later without a breaking protocol change.
  5. Use the Secure Enclave for long-lived private keys where possible.

References:

Corrections welcome, especially from anyone who has shipped these in production or measured the size impact on real protocols.

1 Like