# open-eid/esteid-pkcs11 architecture

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

- Interactive diagram: https://gitdiagram.com/open-eid/esteid-pkcs11
- Repository: https://github.com/open-eid/esteid-pkcs11

## Overview

##### Main Components
- PKCS#11 Core Implementation: The heart of the project is the PKCS#11 module. Key classes like PKCS11Context, OnePinPKCS11Context, CardManager, and EstEIDCardAdapter represent this core, which handles interactions with cryptographic tokens and smartcards.
- Utility and Helper Libraries: This includes files in the “utility” directory (e.g., asnCertificate.cpp/h, pkcs11module.cpp/h) which support certificate handling, ASN.1 parsing, and module control.
- External Cryptographic Dependencies: The project integrates OpenSSL libraries. The “include/openssl” folder indicates that OpenSSL headers are bundled for cryptographic operations. Note also that the README specifies dependencies such as libpcsclite-dev and libssl-dev.
- Unit Test Framework: The “unit tests” directory and the “esteid-pkcs11-test” directory with their tests (and GoogleMock/GTest) indicate that an extensive test suite is available. Ensure these modules are represented as part of the overall quality assurance and integration process.
- Build and Configuration Tools: Files like CMakeLists.txt, build.bat, debian packaging files, and Xcode project files show that the project supports multiple build systems and targets. These elements outline the project’s integration points with various build and deployment pipelines.
- Distribution and Installer: Although not strictly part of runtime architecture, the README mentions how official builds are provided through the official distribution point, indicating an external deployment perspective.

##### Relationships and Interactions
- The PKCS#11 core (the module’s API implementation) is the primary component that interacts with the smartcard readers (via PC/SC or similar middleware) and uses OpenSSL for cryptographic functions.
- The utilities interact with and support the core module by processing certificate and ASN.1 data.
- The unit tests and integration tests verify that all components (e.g., different context implementations and adapters) are working as expected.
- The build system (CMake, Xcode, Debian packaging) orchestrates the compilation and installation processes, integrating with external libraries where necessary.
- External dependencies (OpenSSL, PC/SC libraries) are depicted as separate blocks that the core PKCS#11 module depends on.

##### Architectural Patterns/Design Principles
- Modularity: The project is clearly separated into multiple components – core module, adapters, utilities, and tests.
- Abstraction: Classes like PKCS11Context and OnePinPKCS11Context provide layered abstraction for interacting with cryptographic tokens.
- Portability: With cross-platform support (Ubuntu, OSX, Debian packaging, Xcode projects), the design abstracts underlying operating system differences.
- Testability: The extensive unit test suite indicates a strong emphasis on component isolation and verification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Functionality
    subgraph "Core Functionality"
        CK1["PKCS11Context"]:::core
        CK2["OnePinPKCS11Context"]:::core
        CM["CardManager"]:::core
        EA["EstEIDCardAdapter"]:::core
    end

    %% Utility & Helper Libraries
    subgraph "Utility & Helper Libraries"
        UAC["asnCertificate Utility"]:::utility
        UK["pkcs11module Utility"]:::utility
    end

    %% External Dependencies
    subgraph "External Dependencies"
        OSS["OpenSSL Headers"]:::external
        PSC["Smartcard Middleware (PC/SC)"]:::external
    end

    %% Unit Test Framework
    subgraph "Unit Test Framework"
        UT1["Unit Tests"]:::test
        UT2["esteid-pkcs11 Test Suite"]:::test
    end

    %% Build & Configuration Tools
    subgraph "Build & Configuration Tools"
        B1["CMakeLists.txt"]:::build
        B2["build.bat"]:::build
        B3["Debian Packaging"]:::build
        B4["Xcode Project"]:::build
    end

    %% Relationships
    %% Core module uses external dependencies for cryptographic and smartcard operations
    CK1 -->|"crypto_calls"| OSS
    CK1 -->|"smartcard_interface"| PSC

    %% Core module utilizes utility libraries
    UAC -->|"utility_functions"| CK1
    UK -->|"utility_functions"| CK1

    %% Unit tests verify core functionality
    UT1 ---|"tests"| CK1
    UT2 ---|"tests"| CK1

    %% Build tools orchestrate build of core module
    B1 ---|"builds"| CK1
    B2 ---|"builds"| CK1
    B3 ---|"packages"| CK1
    B4 ---|"builds"| CK1

    %% Styles
    classDef core fill:#FFDDCC,stroke:#FF6600,stroke-width:2px;
    classDef utility fill:#CCE5FF,stroke:#337AB7,stroke-width:2px;
    classDef external fill:#E2F0CB,stroke:#5CB85C,stroke-width:2px;
    classDef test fill:#F7F7A9,stroke:#F0AD4E,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#6A1B9A,stroke-width:2px;

    %% Click Events for Core Functionality
    click CK1 "https://github.com/open-eid/esteid-pkcs11/blob/master/PKCS11Context.cpp"
    click CK2 "https://github.com/open-eid/esteid-pkcs11/blob/master/OnePinPKCS11Context.cpp"
    click CM "https://github.com/open-eid/esteid-pkcs11/blob/master/CardManager.h"
    click EA "https://github.com/open-eid/esteid-pkcs11/blob/master/EstEIDCardAdapter.h"

    %% Click Events for Utility & Helper Libraries
    click UAC "https://github.com/open-eid/esteid-pkcs11/blob/master/utility/asnCertificate.cpp"
    click UK "https://github.com/open-eid/esteid-pkcs11/blob/master/utility/pkcs11module.cpp"

    %% Click Event for External Dependencies
    click OSS "https://github.com/open-eid/esteid-pkcs11/tree/master/include/openssl"

    %% Click Events for Unit Test Framework
    click UT1 "https://github.com/open-eid/esteid-pkcs11/tree/master/unit tests"
    click UT2 "https://github.com/open-eid/esteid-pkcs11/tree/master/esteid-pkcs11-test"

    %% Click Events for Build & Configuration Tools
    click B1 "https://github.com/open-eid/esteid-pkcs11/blob/master/CMakeLists.txt"
    click B2 "https://github.com/open-eid/esteid-pkcs11/blob/master/build.bat"
    click B3 "https://github.com/open-eid/esteid-pkcs11/tree/master/debian"
    click B4 "https://github.com/open-eid/esteid-pkcs11/blob/master/esteid-pkcs11.xcodeproj"
```
