fastcert

A Rust library and CLI tool for making locally-trusted development certificates with zero configuration.

Table of Contents

• Overview
• Features
• Installation
  • Homebrew
  • Cargo
  • From Source
  • Prerequisites
  • Platform-Specific Requirements
• Library Usage
  • Basic Example
  • Advanced Example
• Quick Start
• Usage Examples
• Platform Support
• Advanced Options
• How It Works
• Testing
• Troubleshooting
• FAQ
• Security
• License

Overview

fastcert is a Rust library and command-line tool that makes it easy to create and manage locally-trusted development certificates. It works by creating a local certificate authority (CA) and then generating certificates signed by that CA. The CA certificate is installed in your system's trust store, making all certificates it signs trusted by your browsers and development tools.

Use fastcert as a library to programmatically generate certificates in your Rust applications, or as a CLI tool for quick certificate generation from the command line.

Features

• Library and CLI - Use as a Rust library or command-line tool
• Ergonomic API - Fluent builder pattern for easy certificate generation
• Zero configuration required - works out of the box
• Automatically creates and manages a local CA
• Generates certificates for multiple domains and IP addresses
• Supports wildcard certificates
• RSA key support (default, maximum compatibility)
• ECDSA key support (optional, better performance)
• Client certificate generation
• PKCS#12 format support
• Cross-platform support (macOS, Linux, Windows)
• Integrates with system trust stores
• Firefox and Java trust store support
• Certificates properly signed by CA (not self-signed)

Installation

Homebrew

brew install ozankasikci/tap/fastcert

Cargo

cargo install fastcert

From Source

1. Clone the repository:

git clone https://github.com/ozankasikci/fastcert
cd fastcert

2. Build and install:

cargo install --path .

This will install the fastcert binary to your cargo bin directory (usually ~/.cargo/bin).

For development or custom builds:

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# The binary will be in target/release/fastcert

Library Usage

fastcert can be used as a library in your Rust programs:

[dependencies]
fastcert = "0.4"

Basic Example

use fastcert::CA;

fn main() -> fastcert::Result<()> {
    // Install CA to system trust stores
    let ca = CA::load_or_create()?;
    ca.install()?;

    // Generate a certificate
    ca.issue_certificate()
        .domains(vec!["localhost".to_string()])
        .build()?;

    Ok(())
}

Advanced Example

use fastcert::{CA, KeyType};
use std::path::PathBuf;

fn main() -> fastcert::Result<()> {
    // Custom CA location
    let mut ca = CA::new(PathBuf::from("/opt/my-ca"));
    ca.init_ca()?;

    // ECDSA certificate with multiple domains
    ca.issue_certificate()
        .domains(vec![
            "example.com".to_string(),
            "*.example.com".to_string(),
            "localhost".to_string(),
        ])
        .key_type(KeyType::ECDSA)
        .cert_file("my-cert.pem")
        .key_file("my-key.pem")
        .build()?;

    Ok(())
}

See API documentation for complete details.

Prerequisites

• Rust 1.70 or later
• Cargo package manager
• Administrator/root privileges for installing CA certificates

Platform-Specific Requirements

macOS:

• No additional dependencies required
• System trust store integration works out of the box

Linux:

• For Firefox/Chrome support: certutil (NSS tools)

  # Debian/Ubuntu
  sudo apt install libnss3-tools
  
  # Fedora/RHEL
  sudo dnf install nss-tools
  
  # Arch Linux
  sudo pacman -S nss

Windows:

• Administrator privileges required for system trust store installation
• No additional dependencies needed

Quick Start

# Install local CA in system trust store
fastcert --install

# Generate certificate for a domain (RSA is the default)
fastcert example.com

# Generate certificate for multiple domains and IPs
fastcert example.com localhost 127.0.0.1 ::1

# Generate wildcard certificate
fastcert "*.example.com"

# Generate certificate with ECDSA keys (optional)
fastcert --ecdsa example.com

Note: RSA-2048 is the default key type. Use --ecdsa for ECDSA P-256 keys if needed.

Usage Examples

Basic Certificate Generation

Generate a certificate for a single domain:

fastcert example.com

This creates two files:

• example.com.pem - the certificate (signed by the CA)
• example.com-key.pem - the private key (RSA-2048)

Multiple Domains

Generate a certificate valid for multiple domains and IP addresses:

fastcert example.com localhost 127.0.0.1 ::1

The files will be named example.com+3.pem and example.com+3-key.pem (the +3 indicates 3 additional names beyond the first).

Note: Always include localhost and 127.0.0.1 if you want to access your service via localhost.

Wildcard Certificates

Generate a wildcard certificate:

fastcert "*.example.com"

Creates _wildcard.example.com.pem and _wildcard.example.com-key.pem.

Custom File Names

Specify custom output file names:

fastcert --cert-file mycert.pem --key-file mykey.pem example.com

ECDSA Keys (Optional)

Generate a certificate with ECDSA keys instead of RSA:

fastcert --ecdsa example.com

ECDSA P-256 keys provide equivalent security to RSA-2048 with smaller key sizes, resulting in:

• Smaller certificates
• Faster cryptographic operations
• Better performance

Both RSA and ECDSA are fully supported.

Client Certificates

Generate a certificate for client authentication:

fastcert --client client.example.com

PKCS12 Format

Generate a PKCS12 file (.pfx) containing both certificate and key:

fastcert --pkcs12 example.com

Or specify a custom PKCS12 file path:

fastcert --p12-file mycert.pfx example.com

Certificate Signing Requests

Generate a certificate from an existing CSR:

fastcert --csr mycsr.pem --cert-file mycert.pem

Managing the CA

View the CA certificate location:

fastcert --CAROOT

Install the CA in system trust stores:

fastcert --install

Uninstall the CA from system trust stores (but keep the certificate):

fastcert --uninstall

Environment Variables

Set a custom CA location:

export CAROOT="$HOME/my-ca"
fastcert --install

Specify which trust stores to use:

export TRUST_STORES="system,firefox,java"
fastcert --install

Platform Support

• macOS 10.12+
• Linux (with certutil for Firefox/Chrome, or manual installation)
• Windows 7+ (with administrator privileges for system-wide installation)

Advanced Options

Command-Line Flags

Certificate Generation:

• --cert-file FILE - Custom path for the certificate output file
• --key-file FILE - Custom path for the private key output file
• --p12-file FILE - Custom path for PKCS12 output file
• --client - Generate a certificate for client authentication
• --ecdsa - Use ECDSA P-256 keys instead of RSA-2048 (optional)
• --pkcs12 - Generate PKCS12 format (.pfx) file
• --csr FILE - Generate certificate from an existing CSR

CA Management:

• --install - Install the local CA in system trust stores
• --uninstall - Remove the local CA from system trust stores
• --CAROOT - Print the CA certificate storage location

Output Control:

• -v, --verbose - Enable verbose output
• --debug - Enable debug output (implies verbose)
• -q, --quiet - Suppress all output except errors

Environment Variables

CAROOT: Set the directory where the CA certificate and key are stored. This allows you to maintain multiple independent CAs.

export CAROOT="$HOME/my-custom-ca"
fastcert --install

TRUST_STORES: Comma-separated list of trust stores to use. By default, fastcert auto-detects available stores.

Options:

• system - Operating system trust store
• nss - Firefox and Chrome (via NSS)
• java - Java trust store

export TRUST_STORES="system,nss"
fastcert --install

FASTCERT_VERBOSE: Enable verbose output (same as --verbose).

FASTCERT_DEBUG: Enable debug output (same as --debug).

FASTCERT_QUIET: Suppress output except errors (same as --quiet).

Certificate Validity

All certificates generated by fastcert are valid for 825 days (approximately 2 years and 3 months), which is the maximum validity period accepted by major browsers.

Key Types and Sizes

RSA (default):

• CA: RSA-3072
• Certificates: RSA-2048
• Standard and widely compatible
• Trusted by all systems

ECDSA (optional --ecdsa flag):

• Curve: P-256 (secp256r1)
• Key size: 256 bits (equivalent security to RSA-2048)
• Smaller certificates
• Faster operations
• Modern and efficient

Both key types are fully supported. Choose based on your needs:

• RSA: Maximum compatibility (default)
• ECDSA: Better performance and smaller certificates

How It Works

When you run fastcert --install, it creates a new local certificate authority and installs it in your system trust store. When you generate certificates, they are signed by this local CA, making them trusted by your system.

The CA certificate and key are stored in:

• macOS/Linux: $HOME/.local/share/fastcert
• Windows: %LOCALAPPDATA%\fastcert

You can override this location by setting the CAROOT environment variable.

Certificate Generation Process

1. Check if CA exists, create if needed (RSA-3072)
2. Parse and validate domain names/IP addresses
3. Generate a new private key (RSA-2048 by default, or ECDSA P-256 with --ecdsa)
4. Create certificate parameters with SANs
5. Sign the certificate with the CA key
6. Write certificate and key files to disk

Trust Store Integration

fastcert automatically detects and integrates with:

• System trust store (macOS Keychain, Windows Certificate Store, Linux CA certificates)
• Firefox/Chrome (via NSS)
• Java KeyStore

Testing

Running Tests

# Run all tests
cargo test

# Run specific test suite
cargo test --test integration
cargo test --test e2e
cargo test --test security

# Run with verbose output
cargo test -- --nocapture

# Generate code coverage report
cargo install cargo-tarpaulin
cargo tarpaulin --out Html --output-dir coverage

Troubleshooting

Certificate Not Trusted

Problem: Browser shows "Not Secure" or certificate warning.

Solutions:

1. Make sure you ran fastcert --install before generating certificates
2. Restart your browser completely (quit and reopen) after installing the CA
3. Verify the certificate includes the domain you're accessing:
   • Include localhost 127.0.0.1 if accessing via localhost
   • Example: fastcert myapp.dev localhost 127.0.0.1 ::1
4. On Linux, you may need to manually trust the CA certificate
5. Verify the certificate is signed by the CA:

   openssl verify -CAfile "$(fastcert --CAROOT)/rootCA.pem" yourcert.pem

Permission Denied

Problem: Error installing CA certificate.

Solutions:

• macOS: The system will prompt for your password
• Linux: Run with sudo if installing system-wide
• Windows: Run as Administrator

Firefox Not Trusting Certificates

Problem: Firefox shows certificate error even though system trusts it.

Solutions:

1. Install NSS tools (certutil):

   # Debian/Ubuntu
   sudo apt install libnss3-tools
   
   # macOS
   brew install nss

2. Run fastcert --install again
3. Restart Firefox

Java Applications Not Trusting Certificates

Problem: Java applications reject certificates.

Solutions:

1. Make sure Java is installed
2. Run fastcert --install to add CA to Java trust store
3. Restart Java applications

CA Already Exists

Problem: Want to recreate the CA.

Solution:

# Uninstall from trust stores
fastcert --uninstall

# Find CA location
fastcert --CAROOT

# Delete the CA directory
rm -rf $(fastcert --CAROOT)

# Reinstall
fastcert --install

Wrong Domain in Certificate

Problem: Certificate generated for wrong domain.

Solution: Delete the certificate files and regenerate:

rm example.com*.pem
fastcert example.com

Multiple CAs

Problem: Need different CAs for different projects.

Solution: Use the CAROOT environment variable:

# Project 1
export CAROOT="$HOME/ca-project1"
fastcert --install
fastcert project1.local

# Project 2
export CAROOT="$HOME/ca-project2"
fastcert --install
fastcert project2.local

Certificate Expired

Problem: Certificate has expired.

Solution: Certificates are valid for 825 days. Simply regenerate:

fastcert example.com

Debugging Issues

Enable verbose or debug mode for detailed output:

fastcert --verbose example.com
fastcert --debug -install

FAQ

Is this secure for production use?

No. fastcert is designed for development and testing only. Never use these certificates in production environments. The CA key is stored locally without additional protection, making it unsuitable for production use.

Can I use this for internal services?

While technically possible, it's not recommended. For internal services, consider using a proper internal PKI solution. fastcert is best suited for local development.

Why does my browser still show a warning?

Make sure:

1. You ran fastcert --install before generating certificates
2. The certificate includes the exact domain/IP you're accessing
3. You've restarted your browser after installation
4. The certificate hasn't expired

Can I trust certificates on another machine?

Yes, but it's not recommended. You would need to copy the CA certificate to the other machine and install it manually. This defeats the purpose of a local CA and creates security risks.

What happens if I lose my CA key?

If you lose the CA key, you cannot generate new trusted certificates. You'll need to:

1. Run fastcert --uninstall on all machines that trust the old CA
2. Delete the CAROOT directory
3. Run fastcert --install to create a new CA
4. Regenerate all certificates

How long are certificates valid?

Certificates are valid for 825 days from creation. This is the maximum validity period accepted by major browsers and operating systems.

Can I use custom validity periods?

Currently, no. The validity period is fixed at 825 days to ensure browser compatibility.

Does this work with Docker?

Yes. You can mount the CA certificate into Docker containers and configure them to trust it. However, it's usually easier to use the container's hostname and generate a certificate for it.

Can I automate certificate generation?

Yes. fastcert is designed to be scriptable. Example:

#!/bin/bash
fastcert --install
for domain in app.local api.local db.local; do
    fastcert "$domain"
done

Does this support IPv6?

Yes. You can generate certificates for IPv6 addresses:

fastcert ::1 2001:db8::1

Can I revoke certificates?

No. Certificate revocation is not supported. If you need to invalidate a certificate, simply delete it and don't use it anymore.

Security

The CA key is the most sensitive file. Keep it secure and never share it. If you suspect it has been compromised, you should uninstall the CA and delete the CAROOT directory.

Best Practices:

• Never commit CA certificates or keys to version control
• Don't share the CA key with others
• Use different CAs for different trust boundaries
• Regularly rotate certificates (regenerate every few months)
• Keep the CA key file permissions restricted (600)
• Only use for local development, never production

Acknowledgments

This project was inspired by mkcert.

License

BSD 3-Clause License - see LICENSE file for details

Status

Active development - core functionality implemented