# bpluta/cryptosuite architecture

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

- Interactive diagram: https://gitdiagram.com/bpluta/cryptosuite
- Repository: https://github.com/bpluta/cryptosuite

## Overview

##### Main Components
- Library Core (Sources/CryptoSuite): This is the heart of the library containing the key cryptographic operations and key management. Inside this, you have several functional subdivisions:
– Crypto Operations: Modules under Sources/CryptoSuite/Crypto that manage ECC operations (ECDH, ECDSA), HMAC generation/verification, and helpers for secure key conversion.
– Biometry: Located in Sources/CryptoSuite/Biometry, which handles biometric state management, authentication context workflows, and integration with Apple’s keychain and CryptoKit.
– Supporting Modules: This includes utility files such as SecureKeyGenerator, SecureKeyStorage, and SignatureManager that orchestrate key generation, storage, and signing operations.
- External Dependencies & Frameworks: The library leverages Apple’s CryptoKit, Swift Concurrency (async/await), and an external keychain integration library (Keyrmes).
- Example and Test Projects: The Example folder contains an Xcode project that demonstrates the library’s API integration, while the Tests directory provides unit tests covering extension functionalities and cryptographic operations.

##### Relationships and Interactions
- API Consumers (Client Code/Example App) → Library Core: The client integrates CryptoSuite (via SPM), imports the library and then calls into the API, triggering operations like key generation, storage, signing, and biometric authentication.
- Crypto Operations Module ↔ Apple CryptoKit: The modules inside “Crypto” call directly into CryptoKit’s services to perform operations on various elliptic curves (NIST P-256, P-384, and P-521) and secure enclave support.
- SecureKeyStorage ↔ Keychain: This module interacts with the device keychain (using Keyrmes) to persist keys securely, with optional biometric enforcement.
- Biometry Module ↔ Local Authentication: Manages biometric contexts and state verification, ensuring that key access is properly authenticated.
- SignatureManager bridges between cryptographic operations and client requests (e.g., generating and verifying digital signatures).

##### Highlighting Architectural Patterns & Design Principles
- Modularization: The clear separation into “Crypto,” “Biometry,” and supporting modules indicates a modular architecture.
- Abstraction via Protocols: The project uses Swift protocols (found under Sources/CryptoSuite/Crypto/Protocols) to define contract behaviors for keys and cryptographic operations.
- Concurrency: The use of Swift’s async/await API throughout the library is a design choice to ensure thread-safe cryptographic operations while interfacing with potentially blocking operations such as biometric authentication.

##### Relevant Technologies & Frameworks
- Swift 6 & Swift Package Manager – as the core language and package management system.
- Apple’s CryptoKit – provides the underpinning cryptographic functions.
- LocalAuthentication Framework – used for handling biometric modalities.
- Keyrmes – for keychain integration.
- Xcode for building and testing the library (as seen from the Example directory structure).

##### Elements
- From Client Code → SecureKeyGenerator / SignatureManager for key generation and signing operations.
- From SecureKeyStorage → Keychain Services (external dependency).
- From Biometry Module → LocalAuthentication Framework (for biometric validations).
- From Crypto Operations → Apple CryptoKit (for ECC and HMAC operations).
- Internal modules (e.g., rounded rectangles for core components)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Outer container for CryptoSuite Library
    subgraph "CryptoSuite Library"
        LibraryCore("CryptoSuite Library"):::internal

        subgraph "Internal Modules"
            %% Cryptographic Operations subgraph
            subgraph "Cryptographic Operations"
                ECC("ECC Operations"):::internal
                HMAC("HMAC & MAC Generation"):::internal
                Protocols("Crypto Protocols"):::internal
                Helpers("Helpers"):::internal
                Support("Support"):::internal
            end

            %% Secure Key Management subgraph
            subgraph "Secure Key Management"
                KeyGen("SecureKeyGenerator"):::internal
                KeyStore("SecureKeyStorage"):::internal
                Signature("SignatureManager"):::internal
            end

            %% Biometry subgraph
            subgraph "Biometry"
                Biometry("Biometry Module"):::internal
            end
        end
    end

    %% External and testing nodes
    ExampleApp("Example App (API Consumer)"):::example
    UnitTests("Unit Tests"):::example
    AppleCrypto("Apple CryptoKit"):::external
    Keychain("Keychain Services"):::external
    LocalAuth("LocalAuthentication"):::external

    %% Relationships
    %% Client usage of the library
    ExampleApp -->|"uses"| LibraryCore
    UnitTests -->|"tests"| LibraryCore

    %% Library internal interactions
    LibraryCore -->|"coordinates"| ECC
    LibraryCore -->|"coordinates"| KeyGen
    LibraryCore -->|"coordinates"| Biometry

    %% Within Crypto Operations: external dependency on AppleCrypto
    ECC -->|"calls"| AppleCrypto
    HMAC -->|"calls"| AppleCrypto

    %% Relationship between key management and crypto operations
    Signature -->|"bridges"| ECC

    %% Secure Key Management interaction with Keychain
    KeyStore -->|"stores-to"| Keychain

    %% Biometry module interaction with LocalAuthentication
    Biometry -->|"validates-via"| LocalAuth

    %% Client direct invocations
    ExampleApp -->|"invokes"| KeyGen
    ExampleApp -->|"invokes"| Signature

    %% Class definitions for styling
    classDef internal fill:#d4f7d4,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#f7d4d4,stroke:#c62828,stroke-width:2px;
    classDef example fill:#fff4cc,stroke:#ffb300,stroke-width:2px;

    %% Click Events for component mappings
    click LibraryCore "https://github.com/bpluta/cryptosuite/tree/main/Sources/CryptoSuite"
    click ECC "https://github.com/bpluta/cryptosuite/tree/main/Sources/CryptoSuite/Crypto"
    click Helpers "https://github.com/bpluta/cryptosuite/tree/main/Sources/CryptoSuite/Crypto/Helpers"
    click Support "https://github.com/bpluta/cryptosuite/tree/main/Sources/CryptoSuite/Crypto/Support"
    click Protocols "https://github.com/bpluta/cryptosuite/tree/main/Sources/CryptoSuite/Crypto/Protocols"
    click Biometry "https://github.com/bpluta/cryptosuite/tree/main/Sources/CryptoSuite/Biometry"
    click KeyGen "https://github.com/bpluta/cryptosuite/blob/main/Sources/CryptoSuite/SecureKeyGenerator.swift"
    click KeyStore "https://github.com/bpluta/cryptosuite/blob/main/Sources/CryptoSuite/SecureKeyStorage.swift"
    click Signature "https://github.com/bpluta/cryptosuite/blob/main/Sources/CryptoSuite/SignatureManager.swift"
    click ExampleApp "https://github.com/bpluta/cryptosuite/tree/main/Example/CryptoSuiteExample"
    click UnitTests "https://github.com/bpluta/cryptosuite/tree/main/Tests/CryptoSuiteTests"
```
