# cloudflare/gokeyless architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/gokeyless
- Repository: https://github.com/cloudflare/gokeyless

## Overview

##### Project Type and Purpose
- This project is a security-focused network service that implements Keyless SSL in Go.
- It acts as a TLS server that performs mutual authentication with clients and supports a range of key storage backends (directory keys, PKCS#11 HSM, Azure Key Vault, Google Cloud KMS).

##### File Structure for Architectural Clues
- Top-level directories like “server”, “client”, “protocol”, “internal”, and “cmd” suggest clear separation:
- The “server” directory contains the core server code including TLS handling, error reporting, metrics, and key store integration.
- The “client” directory likely contains test or utility code to simulate or interact with the keyless server.
- The “protocol” folder defines communication protocols and logic for encoding/decoding messages.
- The “internal” directory houses provider-specific modules for HSM integrations (e.g., Azure, Google) and RFC7512 support for PKCS#11 URIs.
- The “cmd” directory includes entry points for various binaries (production server, benchmarking tools, CLI testing).
- Other directories for package installation (pkg) and tests (tests) further emphasize the production-readiness and diverse deployment modes (including Docker support).

##### Key Components
a. Server Component:
- The main server binary (gokeyless) that starts a TLS server.
- Configuration handling via “gokeyless.yaml” found in cmd/gokeyless and configuration fallback paths.
- Integration with key management: it reads keys either from a file system directory or uses HSM protocols (PKCS#11, Azure, Google).
- Internal modules for RSA and other crypto operations (located in server/internal, internal/rfc7512, certmetrics).
b. Client Component:
- A client library (in the “client” directory) that facilitates keyless communication and testing.
- Test utilities (from tests/ and client/testdata) that simulate connections and validate the protocol.
c. Communication & Protocol Layer:
- The “protocol” directory, which defines how messages are formatted, parsed, and transmitted between client and server.
- The “conn” directory, which likely manages the low-level connection (including RPC style calls).
d. Key Store Abstraction:
- Several components in the configuration and README specify different key store types (local directory, PKCS#11-based HSM, Azure Key Vault, Google Cloud KMS).
- The internal HSM integrations under “internal/azure”, “internal/google”, and “internal/rfc7512”.
e. External Dependencies:
- Docker-related files (Dockerfile, docker-compose.example.yaml) which hint at containerized deployment.
- Workflow definitions (.github/workflows) that show continuous integration aspects which, while not part of runtime, are part of the project lifecycle.

##### Relationships and Interactions
- The server binary loads configuration (via configuration files or env variables) and initializes key stores.
- It then establishes a TLS server that listens for incoming client connections.
- Communication between the keyless client and server uses the defined protocol, with the corresponding protocol handler managing message formats.
- When cryptographic operations are needed, server components hand off operations to modules managing keys (either in-memory or via external HSM/cloud providers).
- The client, whether a test utility or a production caller, interacts with the server for mutual TLS authentication and cryptographic validation.

##### Architectural Patterns & Design Principles Highlighted
- Separation of Concerns: clear segregation between client, server, protocol handling, and key management.
- Modular Design: vendor-specific integrations are isolated within “internal” folders.
- Extensibility: support for multiple key store types, with configuration-driven behavior.
- Testing & Validation: a large set of tests and test data directories indicate a robust testing strategy.

##### Final Recommendation for the Principal Software Engineer
— Server Binary (gokeyless) that initiates TLS connections.
— Client libraries/utilities that interact with the Server.
— Protocol layer that governs communication.
— Pluggable key management modules (local, HSM, Azure, Google).
- Clearly label every component and show how configuration is injected into the system.
— Client initiates connection → Server authenticates via mutual TLS.
— Server uses protocol handlers to process requests.
— Server makes calls to key management services (locally or via HSM/cloud API).
- Employ additional annotations to highlight:
— The role of “cmd” directories in providing multiple entry points.
— Testing components and how they verify the behavior.
— Docker deployment (from Dockerfile and docker-compose) as an operational aspect.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Management
    subgraph "Configuration Management"
        CONFIG["Configuration File (pkg/gokeyless.yaml)"]:::config
        INIT["Initialization (cmd/gokeyless/initialize.go)"]:::config
    end

    %% Server Component
    subgraph "Server Component"
        SERVER_BINARY["Server Binary (cmd/gokeyless/gokeyless.go)"]:::server
        TLS_SERVER["TLS Server (server/server.go)"]:::server
        KEYSTORE["Key Store Handler (server/keystore.go)"]:::server
        ERRORS["Error Handling (server/errors.go)"]:::server
        METRICS["Metrics (server/metrics.go)"]:::server
        CRYPTO["Crypto Operations (server/internal/rsa/rsa.go)"]:::server
        CERTMETRICS["Certificate Metrics (certmetrics/metrics.go)"]:::server
    end

    %% Protocol & Communication Layer
    subgraph "Protocol & Communication"
        PROTOCOL["Protocol Definitions (protocol/protocol.go)"]:::protocol
        PROTOCOL_CONN["Connection Handler (protocol/conn.go)"]:::protocol
        CONN_LOW["Low-level Connection (conn/conn.go)"]:::protocol
        CONN_RPC["RPC Handler (conn/rpc.go)"]:::protocol
    end

    %% Key Store Abstraction
    subgraph "Key Store Abstraction"
        LOCAL_KEY["Local Key Directory"]:::keystore
        PKCS11A["PKCS#11 Key (server/pkcs11.go)"]:::keystore
        PKCS11B["Alternate PKCS#11 (server/nopkcs11.go)"]:::keystore
        AZURE["Azure Integration (internal/azure/azure.go)"]:::keystore
        GOOGLE["Google Cloud KMS (internal/google/google.go)"]:::keystore
        RFC7512A["RFC7512 (internal/rfc7512/rfc7512.go)"]:::keystore
        RFC7512B["PKCS#11 URI (internal/rfc7512/uri.go)"]:::keystore
    end

    %% Client Component
    subgraph "Client Component"
        CLIENT_LIB["Keyless Client (client/client.go)"]:::client
        CLIENT_KEYS["Client Key Ops (client/keys.go)"]:::client
        CLIENT_REMOTE["Remote Client (client/remote.go)"]:::client
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        DOCKERFILE["Dockerfile"]:::deployment
        DOCKER_COMPOSE["Docker Compose (docker-compose.example.yaml)"]:::deployment
        GITHUB_ACTIONS["GitHub Workflows (.github/workflows)"]:::deployment
        GORELEASER["Release Config (.goreleaser.yml)"]:::deployment
    end

    %% Connections from Configuration to Server
    CONFIG --> SERVER_BINARY
    INIT --> SERVER_BINARY
    SERVER_BINARY --> TLS_SERVER

    %% Server Internal Flows
    TLS_SERVER --> KEYSTORE
    TLS_SERVER --> ERRORS
    TLS_SERVER --> METRICS
    TLS_SERVER --> PROTOCOL
    TLS_SERVER --> CRYPTO
    CRYPTO --> CERTMETRICS

    %% Protocol Flow
    PROTOCOL --> PROTOCOL_CONN
    PROTOCOL_CONN --> CONN_LOW
    CONN_LOW --> CONN_RPC

    %% Key Store Integration
    KEYSTORE --> LOCAL_KEY
    KEYSTORE --> PKCS11A
    KEYSTORE --> PKCS11B
    KEYSTORE --> AZURE
    KEYSTORE --> GOOGLE
    KEYSTORE --> RFC7512A
    KEYSTORE --> RFC7512B

    %% Client to Server and Protocol Interaction
    CLIENT_LIB --> TLS_SERVER
    CLIENT_LIB --> PROTOCOL
    CLIENT_KEYS --> CLIENT_LIB
    CLIENT_REMOTE --> CLIENT_LIB

    %% Deployment Connectivity (Containerization & CI/CD)
    TLS_SERVER --> DOCKERFILE
    DOCKERFILE --> DOCKER_COMPOSE
    DOCKER_COMPOSE --> GITHUB_ACTIONS
    GITHUB_ACTIONS --> GORELEASER

    %% Click Events
    click CONFIG "https://github.com/cloudflare/gokeyless/blob/master/pkg/gokeyless.yaml"
    click INIT "https://github.com/cloudflare/gokeyless/blob/master/cmd/gokeyless/initialize.go"
    click SERVER_BINARY "https://github.com/cloudflare/gokeyless/blob/master/cmd/gokeyless/gokeyless.go"
    click TLS_SERVER "https://github.com/cloudflare/gokeyless/blob/master/server/server.go"
    click KEYSTORE "https://github.com/cloudflare/gokeyless/blob/master/server/keystore.go"
    click ERRORS "https://github.com/cloudflare/gokeyless/blob/master/server/errors.go"
    click METRICS "https://github.com/cloudflare/gokeyless/blob/master/server/metrics.go"
    click CRYPTO "https://github.com/cloudflare/gokeyless/blob/master/server/internal/rsa/rsa.go"
    click CERTMETRICS "https://github.com/cloudflare/gokeyless/blob/master/certmetrics/metrics.go"
    click PROTOCOL "https://github.com/cloudflare/gokeyless/blob/master/protocol/protocol.go"
    click PROTOCOL_CONN "https://github.com/cloudflare/gokeyless/blob/master/protocol/conn.go"
    click CONN_LOW "https://github.com/cloudflare/gokeyless/blob/master/conn/conn.go"
    click CONN_RPC "https://github.com/cloudflare/gokeyless/blob/master/conn/rpc.go"
    click PKCS11A "https://github.com/cloudflare/gokeyless/blob/master/server/pkcs11.go"
    click PKCS11B "https://github.com/cloudflare/gokeyless/blob/master/server/nopkcs11.go"
    click AZURE "https://github.com/cloudflare/gokeyless/blob/master/internal/azure/azure.go"
    click GOOGLE "https://github.com/cloudflare/gokeyless/blob/master/internal/google/google.go"
    click RFC7512A "https://github.com/cloudflare/gokeyless/blob/master/internal/rfc7512/rfc7512.go"
    click RFC7512B "https://github.com/cloudflare/gokeyless/blob/master/internal/rfc7512/uri.go"
    click CLIENT_LIB "https://github.com/cloudflare/gokeyless/blob/master/client/client.go"
    click CLIENT_KEYS "https://github.com/cloudflare/gokeyless/blob/master/client/keys.go"
    click CLIENT_REMOTE "https://github.com/cloudflare/gokeyless/blob/master/client/remote.go"
    click DOCKERFILE "https://github.com/cloudflare/gokeyless/tree/master/Dockerfile"
    click DOCKER_COMPOSE "https://github.com/cloudflare/gokeyless/blob/master/docker-compose.example.yaml"
    click GITHUB_ACTIONS "https://github.com/cloudflare/gokeyless/tree/master/.github/workflows"
    click GORELEASER "https://github.com/cloudflare/gokeyless/blob/master/.goreleaser.yml"

    %% Style Definitions
    classDef config fill:#FFEECC,stroke:#333,stroke-width:2px;
    classDef server fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef protocol fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef keystore fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef client fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef deployment fill:#E0E0E0,stroke:#333,stroke-width:2px;
```
