Getting Started

This guide walks you through installing Trinity, initializing a Root CA, and signing your first certificate.

Prerequisites

For Trinity Authority (CLI)

Go 1.24+ — Download Go
Make — Standard build tool (pre-installed on macOS/Linux)
An air-gapped machine is recommended for production use, but not required for testing.

For Trinity Passport (Desktop App)

Go 1.23+
Wails v2 — Install with: go install github.com/wailsapp/wails/v2/cmd/wails@latest
Node.js — For the frontend build
Linux users need WebKit development headers:
- Ubuntu 22.04+: sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
- Older Ubuntu: sudo apt install libgtk-3-dev libwebkit2gtk-4.0-dev

Step 1: Clone the Repository

git clone https://github.com/trinity-pki/trinity-pki.git
cd trinity-pki

The repository is a monorepo with the following structure:

Directory	Component	Description
`authority/`	Authority CLI	Offline Root CA tool
`passport/`	Passport Desktop	Identity vault (Wails app)
`spirit/`	Spirit Gateway	Cloudflare Worker relay
`connect/`	Connect Server	Self-hosted Go server

Step 2: Build the Authority CLI

cd authority
make build

This produces a single binary: ./trinity

Step 3: Initialize the Root CA

./trinity init --name "My Root CA" --org "My Organization"

You will be prompted for a passphrase. This passphrase protects your Root CA private key with AES-256 encryption. Do not lose it.

What gets generated: The init command creates an Ed25519 Root CA key pair plus a Kyber-1024 transport key pair for post-quantum "Blind Drop" support. All private keys are passphrase-encrypted at rest.

The following files are created in the safe/ directory:

File	Description
`root.key`	Root CA private key (AES-256 encrypted)
`root.crt`	Root CA self-signed certificate
`transport.pub`	Kyber-1024 public key (for Blind Drops)
`transport.key`	Kyber-1024 private key (encrypted)

Security: Private key files are automatically set to chmod 0400. The Authority CLI will refuse to load keys with incorrect permissions.

Step 4: Sign a Certificate

Interactive Mode (Recommended)

./trinity sign

This launches an interactive TUI where you can review the CSR details before signing.

Headless Mode

cat request.csr | ./trinity sign > cert.crt

Blind Drop Mode (Encrypted CSR)

cat drop.enc | ./trinity sign --transport-key safe/transport.key > response.enc

In Blind Drop mode, the CSR is encrypted with Kyber-1024. The Authority decrypts it, signs the certificate, and re-encrypts the response with the client's ephemeral key.

Step 5: Verify a Certificate

./trinity verify --cert user.crt

This checks the certificate chain against the Root CA and the Certificate Revocation List (CRL).

Step 6: Set Up Passport (Optional)

If you want the desktop identity vault for end-users:

cd ../passport

# Development mode
wails dev -tags webkit2_41    # Linux
wails dev                      # macOS / Windows

# Production build
wails build -tags webkit2_41

Whitelabeling: Edit passport/config.json to customize the app title, company name, colors, and admin email for your organization.

Next Steps

Self-Hosting Guide — Deploy the Connect server or Spirit gateway
Authority Reference — Full CLI command reference
Blind Drops Protocol — How post-quantum encryption works
Architecture — System design and data flows