User Guides¶

This guide covers all certboy features for managing a local PKI hierarchy: Root CA → Intermediate CA → TLS certificates.

Table of Contents¶

1. Root CA
2. Intermediate CA
3. TLS Certificates
4. Check & Renewal
5. Import & Export
6. Revoke
7. Shell Completion
8. Context
9. Key Algorithm
10. CLI Reference
11. Develop

Root CA¶

A Root Certificate Authority (CA) is the trust anchor in a PKI hierarchy. It is self-signed and used to sign Intermediate CAs and TLS certificates.

Create a Root CA¶

certboy --domain example.com --cn "Example Organization" --root-ca

Parameters:

Examples¶

Basic Root CA (ECDSA)¶

certboy --domain example.com --cn "Example Organization" --root-ca

Root CA with Different CN and Organization¶

In enterprise PKI, the Common Name (CN) often differs from the organization name:

certboy --domain corp.local --cn "Corporate Root CA" --root-ca

Root CA with RSA¶

certboy --domain example.com --cn "Example Organization" --root-ca --key-algorithm rsa

Root CA with Custom Expiration¶

# 10 years (3650 days)
certboy --domain example.com --cn "Example Organization" --root-ca --expiration 3650

Encrypted Private Key¶

certboy --domain example.com --cn "Example Organization" --root-ca --encrypt-key

This creates a pass.key file containing the passphrase for the encrypted private key.

Context Structure¶

After creating a Root CA, the context directory contains:

~/.local/state/certboy/
└── example.com/
    ├── meta.json          # CA metadata (algorithm, created date)
    ├── crt.pem            # Public certificate
    ├── key.pem            # Private key (encrypted if --encrypt-key)
    ├── pass.key           # Encryption passphrase (if applicable)
    ├── intermediates.d/   # Intermediate CAs directory
    └── certs.d/           # TLS certificates directory

Intermediate CA¶

An Intermediate CA is a certificate issued by a Root CA, used for delegated certificate signing. This allows you to have multiple signing authorities with different trust policies.

Create an Intermediate CA¶

certboy --domain ops.example.com --ca example.com --cn "Ops Division"

Parameters:

Domain Ownership Validation¶

An ICA can only sign certificates within its domain subtree. This is a security feature.

Example:

• ICA: ops.example.com
• Allowed: ops.example.com, grafana.ops.example.com, a.b.ops.example.com
• Not allowed: example.com, dev.example.com, other.com

Examples¶

Basic ICA¶

certboy --domain ops.example.com --ca example.com --cn "Ops Division"

ICA with Different CN and Organization¶

certboy --domain engineering.corp.local --ca corp.local --cn "Engineering PKI"

ICA with Custom Expiration¶

# 5 years
certboy --domain services.example.com --ca example.com --cn "Services" --expiration 1825

Nested ICA (ICA signing ICA)¶

# Create a second-level ICA
certboy --domain team.ops.example.com --ca ops.example.com --cn "Team Services"

TLS Certificates¶

TLS certificates (also called server certificates) are end-entity certificates used by websites and services to enable HTTPS.

Issue a TLS Certificate¶

certboy --ca example.com -d www.example.com

Parameters:

Examples¶

Single Domain¶

certboy --ca example.com -d www.example.com

Multiple SANs (Subject Alternative Names)¶

certboy --ca example.com \
  --domain api.example.com \
  --domain '*.example.com' \
  --domain 192.168.1.100

Multiple Domains with Wildcard and IP¶

certboy --ca example.com \
  --domain multi.example.io \
  --domain '*.multi.example.io' \
  --domain api.multi.example.io \
  --domain 10.0.0.1

Wildcard Certificate¶

certboy --ca example.com -d '*.example.com'

Force Re-sign¶

If a certificate already exists and you need to re-issue it:

certboy --ca example.com -d www.example.com --force

Encrypted Private Key¶

certboy --ca example.com -d www.example.com --encrypt-key

Certificate Chain¶

TLS certificates issued by an ICA include the full certificate chain in fullchain.crt:

fullchain.crt
├── TLS certificate (www.example.com)
├── Intermediate CA certificate (ops.example.com)
└── Root CA certificate (example.com)

Expiration¶

Default expiration periods:

Check & Renewal¶

Check Certificates¶

certboy check

Show detailed information including DNS names and IP addresses:

certboy check --detail

Expiration Alert Threshold¶

By default, certificates expiring within 14 days are flagged. Customize:

# 30 day threshold
certboy check --expiration-alert 30

Renew Expiring Certificates¶

certboy check --renew

This will renew certificates that are: - Within the expiration alert threshold - Not yet expired

Auto-fix¶

The --auto-fix flag detects and fixes common certificate issues:

# Interactive mode (prompts before each fix)
certboy check --auto-fix

# Automatic mode (applies fixes without prompting)
certboy check --auto-fix --yes

Auto-fix can address: - Wrong fullchain.crt order (ICA-signed certificates) - Duplicate or zero serial numbers - Certificates needing re-signing due to structural issues

Verify Certificate Key Match¶

Verify that the private key matches the certificate using OpenSSL:

certboy check --verify-openssl

Remote Certificate Check¶

Compare remote TLS certificate with local:

certboy check --remote

This performs: 1. DNS resolution check with resolved IPs 2. TCP connect to port 443 3. SSL handshake and cert fetch 4. Serial comparison with local certificate

Import & Export¶

Certboy provides import and export functionality to work with certificates outside the default context.

Export¶

Export a TLS certificate and key to the current directory:

certboy export www.example.com
# Outputs: www.example.com.crt and www.example.com.key

Import¶

Import an existing Root CA or ICA folder into a new context:

certboy import /path/to/ca-folder --context /path/to/new-context

Import Requirements: - crt.pem - Public certificate

Examples¶

Import a Root CA¶

certboy import /path/to/root-ca-example.com --context ~/.local/state/certboy

Import an ICA¶

certboy import /path/to/ica.ops.example.com --context ~/.local/state/certboy

Import Multiple CAs¶

certboy import /path/to/ca1 /path/to/ca2 --context /path/to/context

Use Cases¶

Backup and Restore¶

# Export
certboy export www.example.com --context /backup/context

# Import to new location
certboy import /backup/context/example.com --context /new/context

Migration¶

# On old system
certboy export www.example.com

# Copy files to new system, then import
certboy import /path/to/www.example.com --context /new/context

Consolidation¶

certboy import /path/to/ca-a --context /consolidated
certboy import /path/to/ca-b --context /consolidated

Revoke¶

The revoke command removes certificates from the context. This operation is irreversible.

Revoke a TLS Certificate¶

certboy revoke www.example.com

Revoke Multiple Certificates¶

certboy revoke www.example.com api.example.com

Revoke an ICA¶

When revoking an ICA, all TLS certificates signed by that ICA are affected:

certboy revoke ops.example.com

Skip Confirmation¶

certboy revoke ops.example.com --yes

Revocation Behavior¶

Safety¶

This operation is permanent. Always export certificates before revoking:

# Export first
certboy export www.example.com

# Then revoke
certboy revoke www.example.com

Shell Completion¶

Certboy can generate shell completion scripts for bash, zsh, fish, and PowerShell.

Generate Completion¶

certboy completion bash
certboy completion zsh
certboy completion fish
certboy completion powershell

Bash¶

System-wide:

sudo certboy completion bash > /etc/bash_completion.d/certboy

User-specific:

mkdir -p ~/.local/share/certboy/completions
certboy completion bash > ~/.local/share/certboy/completions/certboy

Add to ~/.bashrc:

source ~/.local/share/certboy/completions/certboy

Zsh¶

certboy completion zsh > ~/.zsh/completions/_certboy

Fish¶

certboy completion fish > ~/.config/fish/completions/certboy.fish

PowerShell¶

certboy completion powershell >> $PROFILE

Context¶

A context is a directory that stores all certificate authorities and TLS certificates managed by certboy.

Default Context¶

~/.local/state/certboy/

This location is used when: - No --context flag is provided - No CERTBOY_CONTEXT environment variable is set

Override Context¶

Command-line:

certboy --context /path/to/context check

Environment Variable:

export CERTBOY_CONTEXT=/path/to/context

Directory Structure¶

~/.local/state/certboy/
├── example.com/              # Root CA
│   ├── meta.json
│   ├── crt.pem
│   ├── key.pem
│   ├── intermediates.d/     # Intermediate CAs
│   └── certs.d/             # TLS certificates
└── another.com/             # Another Root CA

Use Cases¶

Separate Environments:

# Production
certboy --context ~/.local/state/certboy-prod ...

# Development
certboy --context ~/.local/state/certboy-dev ...

Project-specific:

certboy --context ./certs --domain example.com --root-ca

Key Algorithm¶

Certboy supports two key algorithms: ECDSA and RSA.

Specify Algorithm¶

# ECDSA (default)
certboy --domain example.com --cn "Example" --root-ca

# RSA
certboy --domain example.com --cn "Example" --root-ca --key-algorithm rsa

Algorithm Inheritance¶

All certificates issued under a Root CA inherit the same algorithm:

Root CA (ECDSA)
├── ICA (inherits ECDSA)
│   └── Certificate (inherits ECDSA)
└── Certificate (inherits ECDSA)

Comparison¶

CLI Reference¶

Complete reference for all certboy commands.

Global Options¶

These options apply to all commands:

Common Expiration Values¶

Environment Variables¶

Develop¶

This page covers local development workflow, testing, and contribution guidelines.

Quickstart¶

Clone and build:

git clone https://github.com/audricsun/certboy.git
cd certboy
cargo build --release

Run locally:

cargo run -- --help

Testing¶

Run All Tests:

make test

Run Tests Without Coverage:

cargo test

Run Clippy (Linting):

make clippy

Security Audit:

make audit

Makefile Targets¶

GitHub Actions¶

• ci-tests.yml: Runs on every push and PR
• ci-build.yml: Runs on tag push - builds multi-platform binaries (Linux gnu/musl, Darwin, ARM Linux)
• ci-publish.yml: Runs after ci-build completes - creates GitHub Release and publishes to crates.io
• ci-pages.yml: Builds and deploys documentation
• ci-bumpversion.yml: Auto-bumps version on main branch pushes (dev builds)
• ci-git-tag.yml: Creates git tags when VERSION file changes

Release Workflow¶

Releases are automated via GitHub Actions:

1. Version Bump (automatic): When VERSION file changes on main, ci-bumpversion.yml bumps the version and commits
2. Tag Creation: ci-git-tag.yml creates a git tag (v{version}) when VERSION changes
3. Build: ci-build.yml triggers on tag push, building for multiple platforms:
4. x86_64-unknown-linux-gnu
5. x86_64-unknown-linux-musl
6. aarch64-apple-darwin
7. aarch64-unknown-linux-gnu
8. aarch64-unknown-linux-musl
9. Publish: ci-publish.yml creates a GitHub Release with all artifacts and publishes to crates.io

Trigger a Release:

# Update VERSION file to release version (removes -devN suffix)
echo "2026.4.1" > VERSION
git add VERSION
git commit -m "release: 2026.4.1"
git push origin main

Version Scheme:

Documentation¶

Serve documentation locally:

make doc-dev

Build docs for production:

zensical build --clean

Contributing¶

1. Run make test and make clippy before submitting PR
2. Ensure all tests pass
3. Update documentation if needed