acmeid

Small C library, CLI tool, and SQLite loadable extension for minting and verifying ACME Localname IDs -- short, sortable, checksummed local identifiers for the localname part of enterprise IRIs.

The format is:

[PREFIX:] TYPE _ [SLUG5] TIME4 RAND_N CHK1

• PREFIX -- optional CURIE-style prefix, e.g. ex:. Not part of the checksum; tolerated by verify.
• TYPE -- single uppercase ASCII letter, domain-owned.
• SLUG5 -- optional 5 lowercase letters derived from the label.
• TIME4 -- 4 Crockford Base32 chars: days since 2020-01-01 UTC.
• RAND_N -- N random Crockford Base32 chars (N in [2,8], default 4).
• CHK1 -- 1 Crockford Base32 check character; the full ID's character values must sum to 0 mod 32.

See docs/spec.org for the full specification and docs/recipes.org for the OTTR / spine-table workflow that motivated the SQLite extension.

Build

Requires a C11 compiler and GNU make. The SQLite loadable extension also needs the SQLite development headers (sqlite3.h / sqlite3ext.h) at build time; symbols are still resolved from the host process at load time via the extension loader contract.

Install the headers with your platform's package manager:

# Debian/Ubuntu
sudo apt install libsqlite3-dev
# Fedora/RHEL
sudo dnf install sqlite-devel
# macOS (Homebrew)
brew install sqlite
# MSYS2/mingw-w64
pacman -S mingw-w64-x86_64-sqlite3

If the headers live outside the default include path, pass their location via CPPFLAGS, e.g. make CPPFLAGS=-I/opt/homebrew/include.

make            # builds libacmeid.a, acmeid CLI, acmeid.{so|dylib|dll}
make test       # runs unit, CLI, SQL, and audit tests
make install    # /usr/local on POSIX; c:/opt/acmeid on MSYS2

CLI

acmeid mint   -t C                            # bare type
acmeid mint   -t C -p ex:                  # type + prefix
acmeid mint   -t C -p ex: -l "Pitch 1.5 mm"
acmeid mint   -t C -p ex: -l "Pitch" -n 6  # 6 random chars
acmeid verify ex:C_pitchABCD1234X
acmeid batch  -t C -p ex: < labels.txt

SQLite

.load /usr/local/lib/acmeid        -- or:  c:/opt/acmeid/acmeid
SELECT acme_mint_id('C');
SELECT acme_mint_id('C','ex:');
SELECT acme_mint_id('C','ex:','Pitch 1.5 mm');
SELECT acme_mint_id('C','ex:','Pitch',6);
SELECT acme_verify_id('ex:C_pitchABCD1234X');

acme_mint_id is registered non-deterministic on purpose, so it mints once per row in an INSERT ... SELECT. acme_verify_id is deterministic and innocuous, so it works inside CHECK constraints, generated columns, and indexes.

Security & privacy

• No network. The library and CLI never open a socket. The audit test in make test greps for socket|connect|getaddrinfo|... to enforce this.
• Cryptographic randomness: BCryptGenRandom on Windows, arc4random_buf on macOS/BSD, /dev/urandom elsewhere. No rand() / srand().
• All functions in src/acmeid.c are reentrant.

Install

Pre-built bundles for tagged releases are attached to each GitHub Release (see .github/workflows/release.yml):

• acmeid-linux-x64.tar.gz -- acmeid, acmeid.so
• acmeid-macos-x64.tar.gz -- acmeid, acmeid.dylib
• acmeid-windows-x64.zip -- acmeid.exe, acmeid.dll, install.cmd (copies both into c:\opt\acmeid\)
• SHA256SUMS -- checksums for the three bundles above

Verify and unpack, then run install.cmd on Windows or copy by hand on POSIX (acmeid to /usr/local/bin, the shared lib to /usr/local/lib).

License

GPLv3 -- see LICENSE.