# ndilieto/uacme architecture

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

- Interactive diagram: https://gitdiagram.com/ndilieto/uacme
- Repository: https://github.com/ndilieto/uacme

## Overview

##### Project type and purpose
- This is an open-source, Unix-style command-line ACMEv2 client (uacme) plus a companion TLS-ALPN challenge responder proxy (ualpn).
- Its goal is to automate certificate issuance and renewal via the ACME protocol, with minimal dependencies and hook‐based extensibility.

##### File structure
- Top‐level C source files (uacme.c, ualpn.c) implement two executables.
- Common modules:
- crypto.c/.h – key and certificate handling
- curlwrap.c/.h – HTTP/HTTPS calls via libcurl
- json.c/.h, jsmn.h – JSON serialization/parsing
- msg.c/.h, log.c/.h – messaging and logging
- libev/* – event loop implementation for ualpn
- hook scripts (uacme.sh, nsupdate.sh, ualpn.sh) under root
- Build infra: autotools machinery (configure.ac, makefiles, build-aux).
- Documentation under docs/ and manpages (.1 files).

##### README for additional insights
- uacme core communicates with remote ACME servers over HTTPS.
- Challenge handling is delegated to external hook scripts.
- ualpn is a standalone daemon that listens on port 443 (and a UNIX socket) and proxies connections to the real web server, handling TLS-ALPN challenges in-flight.
- Dependencies: libcurl, one TLS library (OpenSSL/GnuTLS/mbedTLS), libev.

a. Main components
- User/CLI: the uacme command‐line interface.
- Core library modules:
- ACME Client Engine (HTTP + JSON + crypto)
- Hook Manager (invokes uacme.sh, nsupdate.sh, ualpn.sh)
- ualpn Daemon:
- Event Loop (libev)
- TLS-ALPN handler
- Proxy logic
- External systems/services:
- ACME Server (Let’s Encrypt, etc.)
- Web Server (on local port 4443 or 80/443)
- DNS Server or API (for dns-01 via nsupdate.sh)
- Local filesystem: account private key, challenge tokens, cert/key store.

b. Relationships and data flows
1. User invokes “uacme” CLI →
2. ACME Client Engine builds JSON requests →
3. curlwrap sends HTTPS requests to ACME Server →
4. ACME Server responds with challenges →
5. Hook Manager invokes appropriate script (http-01 → uacme.sh; dns-01 → nsupdate.sh; tls-alpn-01 → ualpn.sh)
6. Hook script sets up challenge environment (web root, DNS record, or passes token via UNIX socket to ualpn) →
7. ACME Server probes challenge endpoint (HTTP/S/TLS-ALPN) →
8. uacme continues when verified →
9. ACME Client Engine retrieves issued certificate →
10. uacme writes cert/key to filesystem →
11. (Optionally) reload scripts update Web Server.

- Separately, ualpn daemon:
- Listens on TCP 443 and UNIX socket →
- For normal HTTPS traffic, proxies to real Web Server.
- For TLS-ALPN-01 handshakes, intercepts and serves challenge response from hook.

c. Architectural patterns and design principles
- Unix philosophy: do one thing well (uacme vs. shell scripts).
- Modular C code: separate crypto, HTTP, JSON, logging.
- Hook/plugin pattern for extensibility.
- Event-driven reactor (libev) in ualpn for high performance.
- Clean separation between CLI, core logic, and external integrations.

d. Key technologies/frameworks
- C99, Autotools build system.
- libcurl for HTTP(s).
- One TLS backend: OpenSSL, GnuTLS, or mbedTLS.
- jsmn for JSON parsing.
- libev for event loop in ualpn.
- Standard Unix shell for hooks; nsupdate, external DNS APIs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    UserCLI["User/CLI: uacme"]:::core
    click UserCLI "https://github.com/ndilieto/uacme/blob/master/uacme.c"

    %% Client Engine Subgraph
    subgraph "ACME Client Engine" 
        direction TB
        Curlwrap["HTTP Wrapper\n(curlwrap.c/.h)"] 
        JSONParser["JSON Parser\n(json.c/.h, jsmn.h)"]
        Crypto["Crypto Routines\n(crypto.c/.h)"]
        Messaging["Messaging & Logging\n(msg.c/.h, log.c/.h)"]
        FileIO["File I/O Helper\n(read-file.c/.h)"]
    end
    class Curlwrap,JSONParser,Crypto,Messaging,FileIO core
    click Curlwrap "https://github.com/ndilieto/uacme/blob/master/curlwrap.c"
    click JSONParser "https://github.com/ndilieto/uacme/blob/master/json.c"
    click Crypto "https://github.com/ndilieto/uacme/blob/master/crypto.c"
    click Messaging "https://github.com/ndilieto/uacme/blob/master/msg.c"
    click FileIO "https://github.com/ndilieto/uacme/blob/master/read-file.c"

    %% Hook Manager & Scripts
    subgraph "Hook Manager & Scripts"
        direction TB
        HookManager["Hook Orchestration\n(uacme.c)"]:::core
        subgraph "Scripts"
            direction TB
            UacmeSh["uacme.sh"]:::hooks
            NsupdateSh["nsupdate.sh"]:::hooks
            UalpnSh["ualpn.sh"]:::hooks
        end
    end
    click HookManager "https://github.com/ndilieto/uacme/blob/master/uacme.c"
    click UacmeSh "https://github.com/ndilieto/uacme/blob/master/uacme.sh"
    click NsupdateSh "https://github.com/ndilieto/uacme/blob/master/nsupdate.sh"
    click UalpnSh "https://github.com/ndilieto/uacme/blob/master/ualpn.sh"

    %% ualpn Daemon
    subgraph "ualpn Daemon" 
        direction TB
        EventLoop["Event Loop\n(libev/)"] 
        TLSHandler["TLS-ALPN Handler\n(ualpn.c)"]
        ProxyLogic["Proxy Logic\n(ualpn.c)"]
    end
    class EventLoop,TLSHandler,ProxyLogic daemon
    click EventLoop "https://github.com/ndilieto/uacme/tree/master/libev/"
    click TLSHandler "https://github.com/ndilieto/uacme/blob/master/ualpn.c"
    click ProxyLogic "https://github.com/ndilieto/uacme/blob/master/ualpn.c"

    %% External Services
    subgraph "External Services"
        direction TB
        ACMEServer["ACME Server"]:::external
        WebServer["Web Server\n(port 80/443/4443)"]:::external
        DNSAPI["DNS API/Server"]:::external
    end

    %% Local Storage
    CertStore[/"Filesystem\n(cert/key store, tokens)"/]:::storage

    %% Connections
    UserCLI -->|"invoke CLI"| HookManager
    HookManager -->|"calls Client Engine"| Curlwrap
    HookManager -->|invokes| UacmeSh
    HookManager -->|invokes| NsupdateSh
    HookManager -->|invokes| UalpnSh

    Curlwrap -->|"HTTPS JSON requests"| ACMEServer
    ACMEServer -->|"JSON responses & challenges"| Curlwrap

    UacmeSh -->|"http-01 files"| WebServer
    NsupdateSh -->|"dns-01 record updates"| DNSAPI
    UalpnSh -->|"send token via UNIX socket"| EventLoop

    ACMEServer -->|"challenge probe HTTP/S"| WebServer
    ACMEServer -->|"challenge probe TLS-ALPN"| TLSHandler

    TLSHandler -->|proxies normal traffic| ProxyLogic
    ProxyLogic -->|forwards to| WebServer

    ACMEServer -->|"verification success"| HookManager
    HookManager -->|"retrieve certificate"| Curlwrap
    Curlwrap -->|"certificate data"| CertStore
    HookManager -->|"optional reload"| UacmeSh

    %% Classes
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef hooks fill:#FFA500,stroke:#333,stroke-width:1px
    classDef daemon fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#F0E68C,stroke:#333,stroke-width:1px
```
