# apple/swift-crypto architecture

> Architecture diagram of the GitHub repository apple/swift-crypto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apple/swift-crypto
- Repository: https://github.com/apple/swift-crypto

## Overview

##### Project Type and Purpose
- This is an open‐source Swift library (“Swift Crypto”) that re‐implements Apple’s CryptoKit API for cross‐platform use (particularly Linux).
- It exposes a unified public API (`Crypto` module) that at runtime either re‐exports the platform’s CryptoKit (on Apple platforms) or calls into a vendored BoringSSL (`libcrypto`) implementation (on Linux).

##### File‐Structure Highlights & Architectural Patterns
- Top‐level manifests & build scripts
- Package.swift (SwiftPM)
- CMakeLists.txt + cmake/modules (for building CCryptoBoringSSL)
- scripts/ (gyb code‐generation, vendoring BoringSSL, etc.)
- Sources/
- CCryptoBoringSSL/… (C++/C sources & headers for a vendored BoringSSL)
- Crypto/… (pure Swift API surfaces and Swift‐only primitive implementations)
- CryptoBoringWrapper/… (Swift wrappers around BoringSSL shims)
- _CryptoExtras/… (additional algorithms not in core CryptoKit)
- Conditional compilation pattern (“apple vs. linux mode”)
- Swift code is shared (API + primitives)
- Platform‐specific code marked `_boring` or in `BoringSSL` directories
- Tests/ & Benchmarks/ target each layer (Swift API, wrapper, BoringSSL integration).

##### Key Components
a. Public API Layer
- `Crypto` Swift module (mirrors CryptoKit)
- Optional staging & server namespaces
b. Implementation Layer
- On Apple: direct re‐export to system CryptoKit framework
- On Linux: Swift wrappers → `CCryptoBoringSSL` module → BoringSSL C code
c. Build System
- SwiftPM driving the Swift build
- CMake driving the C build of CCryptoBoringSSL
- gyb templates → generated Swift sources
d. External Dependencies & Tools
- Apple CryptoKit (on Apple)
- BoringSSL vendored sources
- Swift 5.7+ compiler, Swift Package Manager
- GyB code generator
- GitHub Actions workflows for CI

##### Relationships & Interactions
- Build-time
- SwiftPM invokes CMake to build CCryptoBoringSSL → static `.a` library + modulemap
- gyb scripts generate Swift files from `.gyb` templates
- SwiftPM compiles Swift modules, linking with CCryptoBoringSSL on Linux, or linking CocoaCryptoKit on Apple
- Runtime
- Application code → `import Crypto` → public API
- Public API calls into one of two backends:
– Apple platform: CryptoKit dynamic framework
– Linux: Swift wrapper calls into BoringSSL via CCryptoBoringSSL bridging

##### Architectural Patterns & Principles
- Layered architecture: Public API / abstraction → platform backends → native/third‐party crypto engine
- Separation of concerns: Swift‐only API code vs. C‐based implementation
- Conditional compilation & module naming (`_boring`, `BoringSSL` directories) to isolate platform‐specific code
- Metaprogramming for boilerplate (gyb) to keep API surface in sync with CryptoKit

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        SwiftPM["Swift Package Manager\n(Package.swift)"]:::tools
        CMakeTop["CMake Top-Level\n(CMakeLists.txt)"]:::tools
        CMakeSub["CMake for CCryptoBoringSSL\n(Sources/CCryptoBoringSSL/CMakeLists.txt)"]:::tools
        GyBTemplates["GyB Templates\n(Sources/Crypto/*.gyb)"]:::tools
        GyBScripts["GyB Scripts\n(scripts/gyb.py\nscripts/generate_boilerplate_files_with_gyb.sh)"]:::tools
    end

    %% Source Layers
    subgraph "Source Layers"
        PublicAPI["Crypto Module\n(Sources/Crypto)"]:::swift
        AppleBackend["CryptoKit Re-Export\n(Sources/Crypto/CryptoKitErrors.swift)"]:::external
        subgraph "Linux Backend"
            SwiftWrappers["Swift Wrappers\n(Sources/Crypto/.../BoringSSL/AES-GCM_boring.swift)"]:::swift
            CCryptoShims["CCryptoBoringSSL Shims\n(Sources/CCryptoBoringSSLShims)"]:::c
            VendoredBoringSSL["Vendored BoringSSL C/C++\n(Sources/CCryptoBoringSSL)"]:::c
        end
        CryptoBoringWrapper["CryptoBoringWrapper\n(Sources/CryptoBoringWrapper)"]:::swift
        CryptoExtras["_CryptoExtras\n(Sources/_CryptoExtras)"]:::swift
    end

    %% Tests & CI
    subgraph "Quality & CI"
        Tests["Tests\n(Tests/**)"]:::tools
        Benchmarks["Benchmarks\n(Benchmarks/**)"]:::tools
        CI["CI Workflows\n(.github/workflows/*.yml)"]:::tools
    end

    %% Build-time Flow
    SwiftPM -->|"invokes"| CMakeTop
    CMakeTop -->|"includes"| CMakeSub
    SwiftPM -->|"runs"| GyBScripts
    GyBScripts -->|"generates"| GyBTemplates
    GyBTemplates -->|"produces Swift sources"| PublicAPI

    SwiftPM -->|"compiles Swift modules"| PublicAPI
    SwiftPM -->|"links with"| CCryptoShims
    CCryptoShims -->|"builds static lib"| VendoredBoringSSL

    %% Runtime Flow
    PublicAPI -->|"on Apple"| AppleBackend
    PublicAPI -->|"on Linux"| SwiftWrappers
    SwiftWrappers -->|"bridges to"| CCryptoShims
    CCryptoShims -->|"calls into"| VendoredBoringSSL
    PublicAPI -->|"exposes extras"| CryptoExtras
    PublicAPI -->|"exposes wrappers"| CryptoBoringWrapper

    %% Tests & CI connections
    PublicAPI --> Tests
    SwiftWrappers --> Tests
    CryptoExtras --> Tests
    CI --> Tests
    CI --> Benchmarks

    %% Click Events
    click PublicAPI "https://github.com/apple/swift-crypto/tree/main/Sources/Crypto"
    click AppleBackend "https://github.com/apple/swift-crypto/blob/main/Sources/Crypto/CryptoKitErrors.swift"
    click SwiftWrappers "https://github.com/apple/swift-crypto/blob/main/Sources/Crypto/AEADs/AES/GCM/BoringSSL/AES-GCM_boring.swift"
    click CCryptoShims "https://github.com/apple/swift-crypto/tree/main/Sources/CCryptoBoringSSLShims"
    click VendoredBoringSSL "https://github.com/apple/swift-crypto/tree/main/Sources/CCryptoBoringSSL"
    click CryptoBoringWrapper "https://github.com/apple/swift-crypto/tree/main/Sources/CryptoBoringWrapper"
    click CryptoExtras "https://github.com/apple/swift-crypto/tree/main/Sources/_CryptoExtras"
    click SwiftPM "https://github.com/apple/swift-crypto/blob/main/Package.swift"
    click CMakeTop "https://github.com/apple/swift-crypto/blob/main/CMakeLists.txt"
    click CMakeSub "https://github.com/apple/swift-crypto/blob/main/Sources/CCryptoBoringSSL/CMakeLists.txt"
    click GyBTemplates "https://github.com/apple/swift-crypto/blob/main/Sources/Crypto/AEADs/Nonces.swift.gyb"
    click GyBScripts "https://github.com/apple/swift-crypto/blob/main/scripts/generate_boilerplate_files_with_gyb.sh"
    click Tests "https://github.com/apple/swift-crypto/tree/main/Tests/CryptoTests/"
    click Benchmarks "https://github.com/apple/swift-crypto/blob/main/Benchmarks/Benchmarks/Benchmarks.swift"
    click CI "https://github.com/apple/swift-crypto/blob/main/.github/workflows/main.yml"

    %% Styles
    classDef swift fill:#cce5ff,stroke:#004085,color:#004085;
    classDef c fill:#d4edda,stroke:#155724,color:#155724;
    classDef tools fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
```
