Rite

A DSL and runtime for describing, executing, and reviewing cryptographic key ceremonies.

Beta — Breaking changes between 0.x versions.

_{Guided execution with rite run, one phase of the ceremony lifecycle.}

The problem

Cryptography makes forgery mathematically hard. HSMs make key extraction physically hard. Neither answers the questions that determine whether a sensitive operation was actually performed correctly: Who authorized this? Who was present? Was every step followed?

These questions require human attestation, role separation, and an auditable record: a ceremony. The industry has learned to take them seriously, but still lacks simple, reusable ways to describe, execute, and review them.

Security Ceremonies: Why Secure Systems Are More Than Math →

Lifecycle

A ceremony unfolds in phases. The same YAML drives all of them:

1. Author — write the ceremony as YAML. Editor extensions provide diagnostics, completion, and inline navigation.
2. Validate — rite check catches missing references, undefined roles, schema errors, and step parameters no action can act on.
3. Prepare — rite script produces the printed protocol participants follow and complete by hand during the ceremony, archived alongside the digital transcript.
4. Execute — rite run walks operators and witnesses through the steps, recording every action in an append-only transcript.
5. Audit — rite verify confirms transcript integrity; rite bundle create packages the run with its definition as an evidence bundle; rite bundle disclose derives a publishable part of it; rite report produces a human-readable audit document for stakeholders.

Example

version: "0.3"
name: "Root CA Key Generation"

backends:
  openssl:
    provider: openssl

output:
  root_ca_public_key:
    type: public_key
    description: "Root CA public key for trust anchor distribution"

roles:
  crypto_officer:
    person: "Alice Smith"
  witness:
    person: "Bob Jones"

sections:
  keygen:
    role: ${role.crypto_officer}
    steps:
      generate_root_ca:
        action: generate_key
        backend: openssl
        with:
          algorithm: RSA-4096
        creates: root_ca_keypair
      export_public_key:
        action: export_public
        backend: openssl
        reads: ${artifact.root_ca_keypair}
        creates: root_ca_public_key
      attest_completion:
        action: attest
        role: ${role.witness}
        with:
          statement: "I witnessed the key generation and public key export."

Run it:

rite check  ceremony.rite.yaml   # validate
rite script ceremony.rite.yaml   # generate script, and sheets for values written by hand
rite run    ceremony.rite.yaml   # execute

Running a ceremony produces a timestamped output directory:

root-ca-key-generation-20260511T201639
├── artifacts
│   └── root_ca_public_key.pem
└── transcript.jsonl

Artifacts are written as they are produced. The transcript records every step, role, attestation, and artifact hash in an append-only JSONL file.

rite verify root-ca-key-generation-20260511T201639   # verify integrity
rite report root-ca-key-generation-20260511T201639   # generate audit report

To keep the evidence, package the run with the ceremony it ran from. rite bundle create checks the definition against the digest the transcript records, and each artifact against its own:

rite bundle create root-ca-key-generation-20260511T201639 --definition ceremony.rite.yaml -o root-ca-bundle
rite verify root-ca-bundle

To publish part of it, derive a disclosure. Every fact recorded above the level is withheld but stays committed, so the disclosure verifies to the same fingerprint as the complete record:

rite bundle disclose root-ca-bundle --level public -o root-ca-public
rite verify root-ca-public

Evidence bundles covers bundles and disclosures, and the transcript format specifies the transcript for anyone writing their own verifier.

Installation

Install with Homebrew:

brew tap rite-ly/tap
brew install rite

Run with Docker:

docker run --rm -it --init \
  -v "$PWD:/workspace" \
  ghcr.io/rite-ly/rite check ceremony.rite.yaml

Install from crates.io:

cargo install rite

Editor support

Install the official IDE extensions:

• VS Code (Visual Studio Marketplace)
• IntelliJ IDEA and other JetBrains IDEs (JetBrains Marketplace)

Both bundle the rite-ls language server. For other LSP-aware editors, run rite-ls directly from the binaries attached to each release.

Features

• Ceremony DSL — roles, steps, materials, outputs
• Guided execution — rite run
  • Interactive TUI
  • Error handling (taxonomy, operator-driven retry)
    • Ceremony resumption after interruption
    • Teardown act on abort or failure
• Cryptographic backends
  • OpenSSL: RSA, ECDSA-P256/P384, Ed25519, signing, wrapping, PKI
    • Key wrapping: CMS AuthEnvelopedData, RSA-OAEP, RSA-AES-KEY-WRAP (cloud KMS import)
    • Post-quantum: ML-DSA-44/65/87 signatures and certificates (needs OpenSSL 3.5+)
    • Post-quantum: ML-KEM-512/768/1024 key encapsulation for wrapping (needs OpenSSL 3.5+)
  • Hardware backends
    • YubiKey PIV: key generation, signing, certificate read, on-device attestation
      • Write operations (key import, PIN/PUK and management-key changes)
    • TPM 2.0
    • PKCS#11
  • Plugin system for out-of-process backends
• Evidence and verification
  • Transcript generation and rite verify
  • Evidence bundles (rite bundle create) and verifiable partial disclosure (rite bundle disclose)
  • Verifiable randomness
  • Hardware-attested execution (TPM PCR measurements and signed quotes)
  • RFC3161 trusted timestamps
• Output formats
  • Script and report generation (rite script, rite report)
  • Themeable output via template engine (not yet user-configurable)
• IDE support — VS Code, IntelliJ
  • Language server: diagnostics, completion, hover, go-to-definition, references, symbols
  • Semantic-token highlighting (initial: expressions and reference categories)
  • Inlay hints (initial: step labels)
  • Code lens for in-editor check / dry-run / run
  • Live script preview pane
  • Code actions for common diagnostics
• Isolation and deployment
  • Docker image for containerised execution
  • Bootable USB image for air-gapped ceremonies

Design

Ceremonies are human protocols with machine assistance: operators, witnesses, and physical steps are part of the protocol, not peripheral to it.

• Evidence over execution — the transcript is the product; guided execution is how you produce it
• Error modes are first-class — retries, aborts, and deviations are explicit
• Trust boundaries must be explicit — the tool distinguishes machine-verifiable facts from human attestations
• One structure, many outputs — a ceremony definition should produce guided execution, printable checklists, and verification artifacts

License

Licensing is split per crate. The rite-sdk, rite-model, and rite-resolver crates are dual-licensed under Apache-2.0 OR MIT, so backend authors and third-party tooling can integrate with Rite without GPL obligations. The runtime, stdlib, OpenSSL backend, CLI, and language server are licensed under GPL-3.0-only.