# aws-samples/aws-cloudhsm-pkcs11-examples architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/aws-cloudhsm-pkcs11-examples
- Repository: https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples

## Overview

##### Project type and purpose
- This is an open-source collection of C/C++ command-line example tools demonstrating how to use the AWS CloudHSM PKCS#11 API.
- Each subdirectory under `src/` (e.g. `encrypt/`, `sign/`, `digest/`, `wrapping/`) contains a standalone example binary illustrating one or more PKCS#11 operations.

##### File structure
- Top‐level build and configuration files:
- `CMakeLists.txt` orchestrates the overall build
- `scripts/build.sh` automates build invocation
- CI and contribution metadata in `.travis.yml`, `CONTRIBUTING.md`, etc.
- Vendor interface:
- `include/pkcs11/v2.40/*.h` are the official Cryptoki headers that define the CK_* API
- Shared code:
- `src/common/` supplies command-line parsing (`gopt`), PKCS#11 module loading, session management, error handling
- Example modules:
- Each feature directory under `src/` (e.g. `generate/`, `encrypt/`, `derive/`, `wrapping/`) has its own `CMakeLists.txt` and implements a minimal `main()` that links against `common` + PKCS#11
- Non-FIPS examples and tests are grouped under `src/non_fips_examples/`
- Output binaries under `build/src/...`

##### README for additional insights
- Confirms dependencies (GCC/Clang, CMake, OpenSSL dev libs, Visual Studio on Windows)
- Build steps always produce many small executables that each load the CloudHSM PKCS#11 shared library at runtime
- Run-time input: user PIN, path to PKCS#11 vendor library, optional CloudHSM-specific flags

## Diagram (Mermaid)

```mermaid
flowchart TB
    Developer(["Developer"])
    
    subgraph "Build System"
        CMake["CMakeLists.txt"]:::build
        BuildSh["scripts/build.sh"]:::build
        Travis[".travis.yml"]:::build
        Contrib["CONTRIBUTING.md"]:::build
    end
    
    Developer -->|configure/build| CMake
    CMake --> BuildSh
    Developer -.-> Contrib
    BuildSh --> Travis
    CMake -->|"builds examples"| CLIExamplesGroup
    
    subgraph "CLI Examples"
        attr["CLI Example: Attributes"]:::example
        deriv["CLI Example: Derivation"]:::example
        destroy["CLI Example: Destroy"]:::example
        digest["CLI Example: Digest"]:::example
        encrypt["CLI Example: Encrypt"]:::example
        find["CLI Example: FindObjects"]:::example
        gen["CLI Example: Generate"]:::example
        genrand["CLI Example: GenerateRandom"]:::example
        mech["CLI Example: MechanismInfo"]:::example
        nonfips["CLI Example: NonFIPS Generate"]:::example
        session["CLI Example: Session"]:::example
        sign["CLI Example: Sign"]:::example
        wrap["CLI Example: Wrapping"]:::example
    end
    
    CMake -->|compiles| attr
    CMake -->|compiles| deriv
    CMake -->|compiles| destroy
    CMake -->|compiles| digest
    CMake -->|compiles| encrypt
    CMake -->|compiles| find
    CMake -->|compiles| gen
    CMake -->|compiles| genrand
    CMake -->|compiles| mech
    CMake -->|compiles| nonfips
    CMake -->|compiles| session
    CMake -->|compiles| sign
    CMake -->|compiles| wrap
    
    subgraph "Common Library"
        commonLib["Common Library"]:::common
        commonc["common.c / common.h"]:::common
        goptc["gopt.c / gopt.h"]:::common
        pkcs11c["pkcs11.c"]:::common
        cmkcommon["CMakeLists.txt"]:::build
        commonLib --> commonc
        commonLib --> goptc
        commonLib --> pkcs11c
        commonLib --> cmkcommon
    end
    
    attr -->|"calls common API"| commonLib
    deriv --> commonLib
    destroy --> commonLib
    digest --> commonLib
    encrypt --> commonLib
    find --> commonLib
    gen --> commonLib
    genrand --> commonLib
    mech --> commonLib
    nonfips --> commonLib
    session --> commonLib
    sign --> commonLib
    wrap --> commonLib
    
    subgraph "PKCS#11 Vendor Library"
        vendorLib["PKCS#11 Vendor Library"]:::vendor
        cryptoki["cryptoki.h"]:::vendor
        pkcs11h["pkcs11.h"]:::vendor
        pkcs11f["pkcs11f.h"]:::vendor
        pkcs11t["pkcs11t.h"]:::vendor
        vendorLib --> cryptoki
        vendorLib --> pkcs11h
        vendorLib --> pkcs11f
        vendorLib --> pkcs11t
    end
    
    commonLib -->|"dlopen / C_Initialize"| vendorLib
    vendorLib -->|"RPC calls"| HSM
    HSM["AWS CloudHSM Cluster"]:::external
    HSM -->|"returns crypto results"| vendorLib
    
    click attr "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/attributes/"
    click deriv "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/derivation/"
    click destroy "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/destroy/"
    click digest "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/digest/"
    click encrypt "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/"
    click find "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/find_objects/"
    click gen "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate/"
    click genrand "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate_random/"
    click mech "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/mechanism_info/"
    click nonfips "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/non_fips_examples/generate/"
    click session "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/session/"
    click sign "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/sign/"
    click wrap "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/wrapping/"
    click commonc "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/common/common.c"
    click goptc "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/common/gopt.c"
    click pkcs11c "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/common/pkcs11.c"
    click cmkcommon "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/common/CMakeLists.txt"
    click cryptoki "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/include/pkcs11/v2.40/cryptoki.h"
    click pkcs11h "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/include/pkcs11/v2.40/pkcs11.h"
    click pkcs11f "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/include/pkcs11/v2.40/pkcs11f.h"
    click pkcs11t "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/include/pkcs11/v2.40/pkcs11t.h"
    click CMake "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/CMakeLists.txt"
    click BuildSh "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/scripts/build.sh"
    click Travis "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/.travis.yml"
    click Contrib "https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/CONTRIBUTING.md"
    
    classDef example fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef common fill:#90EE90,stroke:#000,stroke-width:1px
    classDef vendor fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#FF6347,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
```
