How ndilieto/uacme works
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.