SuperAPI AI Directory

cryptokit

General & other

View repository

Updated 10-16 05:52

About this skill

CryptoKit

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

  1. Define the security property: hashing, authentication, authenticated encryption, signing, key agreement, or envelope encryption.
  2. Choose a current CryptoKit primitive and verify platform/peer interoperability before designing storage formats.
  3. Define key generation, persistence, rotation, access control, serialization, and deletion as one lifecycle.
  4. Bind context with authenticated data or a KDF and make nonce/sequence ownership impossible to reuse accidentally.
  5. 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 dataRepresentation stored 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