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, and schema errors.
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 and recording every action in an append-only transcript.
5. Audit — rite verify confirms transcript integrity; rite report produces a human-readable audit document for stakeholders.

Example

version: "0.2"
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_keypair
        backend: openssl
        with:
          algorithm: RSA-4096
          key_usage: [key_cert_sign, crl_sign]
        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
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

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

Build from source:

cargo build --release -p rite
cargo build --release -p rite-ls   # language server for editor support

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
• Cryptographic backends
  • OpenSSL: RSA, ECDSA-P256, signing, wrapping, PKI
    • Post-quantum: ML-KEM key encapsulation
  • Hardware backends
    • YubiKey PIV
    • TPM 2.0
    • PKCS#11
  • Plugin system for out-of-process backends
• Evidence and verification
  • Transcript generation and rite verify
  • Verifiable randomness (#75)
  • 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 (#21)
• 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.