Apple CryptoKit provides a Swift-native API for cryptographic operations: hashing, message authentication, symmetric encryption, public-key signing, key agreement, HPKE, quantum-secure key encapsulation/signing, and Secure Enclave-backed keys. Most core primitives are available on iOS 13+; check availability for HPKE (iOS 17+) and SHA-3 / post-quantum APIs (iOS 26+). Prefer CryptoKit over CommonCrypto or raw Security framework APIs for new cryptographic primitive code targeting Swift 6.3+.
Contents
- Workflow
- Route by Task
- Core Decisions
- Common Mistakes
- Review Checklist
- References
Workflow
- Define the security property: hashing, authentication, authenticated encryption, signing, key agreement, or envelope encryption.
- Choose a current CryptoKit primitive and verify platform/peer interoperability before designing storage formats.
- Define key generation, persistence, rotation, access control, serialization, and deletion as one lifecycle.
- Bind context with authenticated data or a KDF and make nonce/sequence ownership impossible to reuse accidentally.
- Verify round trips, tampering, wrong keys, malformed inputs, rotation, Secure Enclave availability, and cross-platform vectors.
Route by Task
- Read core implementation details for hashes, HMAC, AEAD, signatures, key agreement, HPKE, post-quantum APIs, and Secure Enclave usage.
- Read extended CryptoKit patterns for serialization, Keychain integration, AES key wrapping, insecure legacy migration, and interoperability recipes.
Core Decisions
- Use authenticated encryption; never reuse a nonce with the same key.
- Derive keys from shared secrets instead of using raw agreement output.
- Treat authentication/tag failures as hard failures without partial plaintext use.
- Store long-lived secrets in Keychain or Secure Enclave-backed keys, not preferences.
Common Mistakes
1. Using the shared secret directly as a key
// DON'T
let badKey = sharedSecret.withUnsafeBytes { bytes in
SymmetricKey(data: Data(bytes))
}
// DO -- derive with HKDF
let goodKey = sharedSecret.hkdfDerivedSymmetricKey(
using: SHA256.self,
salt: salt,
sharedInfo: info,
outputByteCount: 32
)
2. Reusing nonces
// DON'T -- hardcoded nonce
let nonce = try AES.GCM.Nonce(data: Data(repeating: 0, count: 12))
let box = try AES.GCM.seal(data, using: key, nonce: nonce)
// DO -- let CryptoKit generate a random nonce (default behavior)
let box = try AES.GCM.seal(data, using: key)
3. Ignoring authentication tag verification
// DON'T -- manually strip tag and decrypt
// DO -- always use AES.GCM.open() or ChaChaPoly.open()
// which verifies the tag automatically
4. Using Insecure hashes for security
// DON'T -- MD5/SHA1 for integrity or security
import CryptoKit
let bad = Insecure.MD5.hash(data: data)
// DO -- use SHA256 or stronger
let good = SHA256.hash(data: data)
Insecure.MD5 and Insecure.SHA1 exist only for legacy compatibility
(checksum verification, protocol interop). Never use them for new
security-sensitive operations.
5. Storing symmetric keys in UserDefaults
// DON'T
UserDefaults.standard.set(rawKeyData, forKey: "encryptionKey")
// DO -- store in Keychain
// See references/cryptokit-patterns.md for Keychain storage patterns
6. Not checking Secure Enclave availability
// DON'T -- crash on simulator or unsupported hardware
let key = try SecureEnclave.P256.Signing.PrivateKey()
// DO
guard SecureEnclave.isAvailable else { /* fallback */ }
let key = try SecureEnclave.P256.Signing.PrivateKey()
Review Checklist
- Using CryptoKit, not CommonCrypto or raw Security framework
- SHA256+ for hashing; no MD5/SHA1 for security purposes
- HMAC verification uses
isValidAuthenticationCode(constant-time) - AES-GCM or ChaChaPoly for symmetric encryption; 256-bit keys
- Nonces are random (default) -- not hardcoded or reused
- Authenticated data (AAD) used where metadata needs integrity
- SharedSecret derived via HKDF, not used directly
- sharedInfo parameter is non-empty and context-specific
- HPKE used instead of custom ECDH+HKDF+AEAD for recipient public-key encryption on iOS 17+
- SHA-3 and post-quantum APIs guarded with iOS 26+ availability
- Secure Enclave availability checked before use
- Secure Enclave key
dataRepresentationstored in Keychain - Private keys not logged, printed, or serialized unnecessarily
- Symmetric keys stored in Keychain, not UserDefaults or files
- Encryption export compliance considered (
ITSAppUsesNonExemptEncryption)
References
- Extended patterns (key serialization, Insecure module, Keychain integration, AES key wrapping, HPKE): references/cryptokit-patterns.md
- Apple documentation: CryptoKit
- Apple documentation: HPKE
- Apple documentation: Quantum-secure workflows
- Apple sample: Performing Common Cryptographic Operations
- Apple sample: Storing CryptoKit Keys in the Keychain
- Core implementation details -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.