Swift Crypto Documentation

Swift Crypto provides a Swift library for common cryptographic operations, built on top of BoringSSL. It is distributed as two main libraries:

• Crypto: An open-source implementation of a substantial portion of the Apple CryptoKit API. It is designed for use on Linux platforms and enables cross-platform or server applications to use CryptoKit-style APIs.
• CryptoExtras: A collection of additional cryptographic primitives and utilities not included in CryptoKit but useful in server environments.

Swift Crypto aims to stay in lockstep with Apple's CryptoKit. To manage APIs that are not yet in the main CryptoKit release, the library uses two specific namespaces:

• Staging namespace: A temporary home for APIs expected to be added to Apple's CryptoKit in the future. Once an API becomes generally available in CryptoKit, it is deprecated in Staging and moved to the main Swift Crypto namespace.
• Server namespace: A permanent home for APIs that are useful for server-side use cases but do not meet the criteria for inclusion in the general CryptoKit library. APIs in this namespace are not expected to move.

Swift Crypto behaves differently depending on the target platform:

1. Apple Platforms (macOS, iOS, etc.): Swift Crypto acts as a transparent wrapper. It compiles its API surface down to nothing and re-exports the native CryptoKit API. All work is delegated to the OS-level CryptoKit implementation.
2. Linux and Windows: Swift Crypto builds a full implementation. It includes a vendored copy of BoringSSL's libcrypto, a vendored copy of XKCP's libXKCP, and the common API surface that calls into these libraries.

Note on CryptoExtras: If you depend on CryptoExtras (which provides server-centric cryptographic APIs not found in CryptoKit), you will bundle the BoringSSL/XKCP implementation in your application regardless of the platform.

Swift Crypto is available as a Swift Package Manager package. To use it, add the package dependency to your Package.swift using a version range that covers your required version up to the next major version. It is recommended to allow a wide range of versions (e.g., 1.x through 4.x) as they are largely API compatible.

To use the library in your code, add Crypto to your target's dependencies and use import Crypto.

// swift-crypto 1.x, 2.x, 3.x, and 4.x are almost API compatible, so most clients
// should allow any of them
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "5.0.0"),

Swift Crypto provides several categories of cryptographic operations. The following primitives are available:

Cryptographically secure hashes

• HashFunction
• SHA512
• SHA384
• SHA256

Message authentication codes

• HMAC
• SymmetricKey
• SymmetricKeySize

Ciphers

• AES
• ChaChaPoly

Public key cryptography

• Curve25519
• P521
• P384
• P256
• SharedSecret
• HPKE

Key derivation functions

• HKDF

Legacy algorithms

• Insecure

When performing cryptographic operations, you may encounter errors defined by the following types:

• CryptoKitError: General errors related to cryptographic operations.
• CryptoKitASN1Error: Errors specifically related to ASN.1 encoding/decoding.

The CryptoExtras library is organized into several functional areas:

• Ciphers: Includes AES implementations (CryptoExtras/Crypto/AES).
• Public key cryptography: Includes RSA support (_RSA).
• Key derivation functions: Includes KDF implementations (KDF).
• Legacy algorithms: Provides access to insecure or legacy algorithms (CryptoExtras/Crypto/Insecure).

The minimum supported Swift version depends on the version of Swift Crypto you are using:

The following options are available for the crypto-shasum command line tool:

Usage: crypto-shasum [OPTION]... [FILE]...
Print SHA checksums.
With no FILE, or when FILE is -, read standard input.

-a, --algorithm   256 (default), 384, 512