GitHub - kunalsinghdadhwal/cutil: Comprehensive Public Key Infrastructure (PKI) toolkit for Rust,

Overview

cutil is designed for developers who need to manage their own internal PKI infrastructure. It provides both a robust Rust library and a command-line interface for certificate operations, making it suitable for development, testing, and production environments.

Features

Certificate Authority Management
- Generate self-signed root certificate authorities
- Create intermediate CAs with full chain validation
- Support for multiple signature algorithms (Ed25519, ECDSA P-256/P-384, RSA 2048/3072/4096)
- Persistent storage with PEM format support
Certificate Issuance
- Issue TLS server certificates with Subject Alternative Names (SANs)
- Issue client authentication certificates
- Dual-purpose certificates for both server and client authentication
- Custom validity periods and Distinguished Names
- Proper X.509 v3 extensions (key usage, extended key usage, basic constraints)
- CRL distribution points and OCSP responder URLs
Certificate Revocation
- Track revoked certificates with reason codes
- Generate Certificate Revocation Lists (CRLs) compliant with RFC 5280
- Support for all standard revocation reasons
Remote Certificate Inspection
- Fetch and parse certificate chains from any TLS server
- Extract detailed certificate information
- Support for both human-readable and JSON output formats
- Verify certificate chain validity
Export Formats
- PEM encoded certificates and private keys
- PKCS#12/PFX archives with password protection
- Full certificate chains
- DER encoding support

Installation

Add CUtil to your Cargo.toml:

[dependencies]
cutil = "0.1"

Quick Start

Library Usage

use cutil::ca::CertificateAuthority;
use cutil::cert::CertificateBuilder;
use cutil::types::{CertSigAlgo, DistinguishedName};
use cutil::error::Result;

fn main() -> Result<()> {
    // Create a root CA
    let subject = DistinguishedName::new("Example Root CA")
        .with_organization("Example Corp")
        .with_country("US");

    let ca = CertificateAuthority::new_root(
        subject,
        CertSigAlgo::EcdsaP256,
        3650, // 10 years
    )?;
    
    ca.save_pem("ca.pem", "ca-key.pem")?;

    // Issue a server certificate
    let mut loaded_ca = CertificateAuthority::load_pem(
        "ca.pem",
        "ca-key.pem",
        CertSigAlgo::EcdsaP256,
    )?;

    let cert = CertificateBuilder::server("example.com")
        .with_dns_san("www.example.com")
        .with_dns_san("api.example.com")
        .with_validity_days(365)
        .issue(&mut loaded_ca)?;

    cert.save_pem("server.pem", "server-key.pem")?;
    
    Ok(())
}

Command-Line Interface

# Initialize a root CA
cutil init --cn "My Root CA" --org "My Company" --country US

# Issue a server certificate
cutil cert --cn example.com --dns example.com,www.example.com --validity 365

# Fetch remote certificate chain
cutil fetch google.com:443 --format pretty

Library API Reference

Certificate Authority Operations

Creating a Root CA

use cutil::ca::CertificateAuthority;
use cutil::types::{CertSigAlgo, DistinguishedName};
use cutil::error::Result;

fn create_root_ca() -> Result<CertificateAuthority> {
    let subject = DistinguishedName::new("Example Root CA")
        .with_organization("Example Corporation")
        .with_organizational_unit("Security")
        .with_country("US")
        .with_state("California")
        .with_locality("San Francisco");

    let ca = CertificateAuthority::new_root(
        subject,
        CertSigAlgo::EcdsaP256,
        3650, // Validity in days
    )?;

    ca.save_pem("root-ca.pem", "root-ca-key.pem")?;
    Ok(ca)
}

Creating an Intermediate CA

use cutil::ca::CertificateAuthority;
use cutil::types::{CertSigAlgo, DistinguishedName};
use cutil::error::Result;

fn create_intermediate_ca() -> Result<CertificateAuthority> {
    // Load the parent (root) CA
    let parent_ca = CertificateAuthority::load_pem(
        "root-ca.pem",
        "root-ca-key.pem",
        CertSigAlgo::EcdsaP256,
    )?;

    // Create intermediate CA subject
    let subject = DistinguishedName::new("Example Intermediate CA")
        .with_organization("Example Corporation")
        .with_organizational_unit("Security");

    // Create the intermediate CA
    let intermediate_ca = CertificateAuthority::new_intermediate(
        subject,
        CertSigAlgo::EcdsaP256,
        1825, // 5 years
        &parent_ca,
    )?;

    intermediate_ca.save_pem("intermediate-ca.pem", "intermediate-ca-key.pem")?;
    Ok(intermediate_ca)
}

Loading an Existing CA

use cutil::ca::CertificateAuthority;
use cutil::types::CertSigAlgo;
use cutil::error::Result;

fn load_ca() -> Result<CertificateAuthority> {
    let ca = CertificateAuthority::load_pem(
        "ca.pem",
        "ca-key.pem",
        CertSigAlgo::EcdsaP256,
    )?;
    Ok(ca)
}

Certificate Issuance

Server Certificates

use cutil::cert::CertificateBuilder;
use cutil::types::{CertSigAlgo, DistinguishedName};
use cutil::ca::CertificateAuthority;
use cutil::error::Result;

fn issue_server_certificate(ca: &mut CertificateAuthority) -> Result<()> {
    let cert = CertificateBuilder::server("example.com")
        .with_dns_san("example.com")
        .with_dns_san("www.example.com")
        .with_dns_san("api.example.com")
        .with_dns_san("*.internal.example.com")
        .with_validity_days(365)
        .with_algorithm(CertSigAlgo::EcdsaP256)
        .issue(ca)?;

    cert.save_pem("server.pem", "server-key.pem")?;
    Ok(())
}

Server Certificates with Custom Subject

use cutil::cert::CertificateBuilder;
use cutil::types::{CertType, DistinguishedName};
use cutil::ca::CertificateAuthority;
use cutil::error::Result;

fn issue_server_with_custom_subject(ca: &mut CertificateAuthority) -> Result<()> {
    let subject = DistinguishedName::new("example.com")
        .with_organization("Example Corporation")
        .with_organizational_unit("Web Services")
        .with_locality("San Francisco")
        .with_state("California")
        .with_country("US");

    let cert = CertificateBuilder::new("example.com".to_string(), CertType::Server)
        .with_subject(subject)
        .with_dns_san("example.com")
        .with_dns_san("www.example.com")
        .with_validity_days(365)
        .issue(ca)?;

    cert.save_pem("server.pem", "server-key.pem")?;
    Ok(())
}

Client Certificates

use cutil::cert::CertificateBuilder;
use cutil::ca::CertificateAuthority;
use cutil::error::Result;

fn issue_client_certificate(ca: &mut CertificateAuthority) -> Result<()> {
    let cert = CertificateBuilder::client("user@example.com")
        .with_email_san("user@example.com")
        .with_validity_days(365)
        .issue(ca)?;

    cert.save_pem("client.pem", "client-key.pem")?;
    Ok(())
}

Certificates with IP SANs

use cutil::cert::CertificateBuilder;
use cutil::ca::CertificateAuthority;
use cutil::error::Result;
use std::net::IpAddr;

fn issue_certificate_with_ip_sans(ca: &mut CertificateAuthority) -> Result<()> {
    let cert = CertificateBuilder::server("internal-service")
        .with_dns_san("internal-service.local")
        .with_ip_san("192.168.1.100".parse::<IpAddr>().unwrap())
        .with_ip_san("10.0.0.50".parse::<IpAddr>().unwrap())
        .with_validity_days(365)
        .issue(ca)?;

    cert.save_pem("internal-service.pem", "internal-service-key.pem")?;
    Ok(())
}

Certificates with CRL and OCSP URLs

use cutil::cert::CertificateBuilder;
use cutil::ca::CertificateAuthority;
use cutil::error::Result;

fn issue_certificate_with_revocation_urls(ca: &mut CertificateAuthority) -> Result<()> {
    let cert = CertificateBuilder::server("example.com")
        .with_dns_san("example.com")
        .with_crl_distribution_point("http://crl.example.com/ca.crl")
        .with_ocsp_server("http://ocsp.example.com")
        .with_validity_days(365)
        .issue(ca)?;

    cert.save_pem("server.pem", "server-key.pem")?;
    Ok(())
}

Certificate Export Formats

Exporting Certificate Chains

use cutil::ca::{CertificateAuthority, IssuedCertificate};
use cutil::error::Result;

fn export_certificate_chain(cert: &IssuedCertificate) -> Result<()> {
    // Save full certificate chain (cert + CA chain)
    cert.save_chain("fullchain.pem")?;
    Ok(())
}

Exporting as PKCS#12

use cutil::ca::IssuedCertificate;
use cutil::error::Result;

fn export_pkcs12(cert: &IssuedCertificate) -> Result<()> {
    let p12_data = cert.export_pkcs12(
        "secure_password_123",
        "My Server Certificate",
    )?;
    
    std::fs::write("certificate.p12", p12_data)?;
    Ok(())
}

Certificate Revocation

Revoking a Certificate

use cutil::ca::CertificateAuthority;
use cutil::types::RevocationReason;
use cutil::error::Result;

fn revoke_certificate(ca: &mut CertificateAuthority, serial: Vec<u8>) -> Result<()> {
    ca.revoke_certificate(serial, RevocationReason::KeyCompromise)?;
    Ok(())
}

Generating a Certificate Revocation List (CRL)

use cutil::ca::CertificateAuthority;
use cutil::error::Result;

fn generate_crl(ca: &CertificateAuthority) -> Result<()> {
    let crl_pem = ca.generate_crl()?;
    std::fs::write("ca.crl", crl_pem)?;
    
    println!("CRL generated with {} revoked certificates", 
             ca.revoked_certificates().len());
    Ok(())
}

Checking Revoked Certificates

use cutil::ca::CertificateAuthority;
use cutil::error::Result;

fn list_revoked_certificates(ca: &CertificateAuthority) -> Result<()> {
    for revoked in ca.revoked_certificates() {
        println!("Serial: {:?}", revoked.serial_number);
        println!("Revocation Date: {}", revoked.revocation_date);
        println!("Reason: {:?}", revoked.reason);
        println!("---");
    }
    Ok(())
}

Remote Certificate Inspection

Fetching Certificate Chains

use cutil::fetch::fetch_certificate_chain;
use cutil::error::Result;

fn fetch_remote_chain() -> Result<()> {
    let chain = fetch_certificate_chain("google.com", 443)?;
    
    println!("Server: {}", chain.server);
    println!("Number of certificates: {}", chain.certificates.len());
    
    for (i, cert) in chain.certificates.iter().enumerate() {
        println!("\nCertificate {}:", i);
        println!("  Subject: {}", cert.subject);
        println!("  Issuer: {}", cert.issuer);
        println!("  Valid from: {}", cert.not_before);
        println!("  Valid until: {}", cert.not_after);
        println!("  Is CA: {}", cert.is_ca);
    }
    
    Ok(())
}

Displaying Certificate Chain Information

use cutil::fetch::{fetch_certificate_chain, display_certificate_chain, OutputFormat};
use cutil::error::Result;

fn display_remote_chain_pretty() -> Result<()> {
    let chain = fetch_certificate_chain("github.com", 443)?;
    let output = display_certificate_chain(&chain, OutputFormat::Pretty)?;
    println!("{}", output);
    Ok(())
}

fn display_remote_chain_json() -> Result<()> {
    let chain = fetch_certificate_chain("github.com", 443)?;
    let output = display_certificate_chain(&chain, OutputFormat::Json)?;
    println!("{}", output);
    Ok(())
}

Saving Certificate Chain to File

use cutil::fetch::{fetch_certificate_chain, display_certificate_chain, OutputFormat};
use cutil::error::Result;

fn save_chain_info(host: &str, port: u16, output_file: &str) -> Result<()> {
    let chain = fetch_certificate_chain(host, port)?;
    let output = display_certificate_chain(&chain, OutputFormat::Json)?;
    std::fs::write(output_file, output)?;
    Ok(())
}

Signature Algorithms

CUtil supports multiple signature algorithms with varying security levels and performance characteristics:

Ed25519 (Recommended for Modern Systems)

use cutil::types::CertSigAlgo;

let algorithm = CertSigAlgo::Ed25519;

Modern elliptic curve signature algorithm
Fast signing and verification
Compact signatures and keys
High security level

ECDSA with NIST Curves

use cutil::types::CertSigAlgo;

// P-256 (secp256r1) - Good balance of security and performance
let p256 = CertSigAlgo::EcdsaP256;

// P-384 (secp384r1) - Higher security level
let p384 = CertSigAlgo::EcdsaP384;

RSA

use cutil::types::CertSigAlgo;

let rsa2048 = CertSigAlgo::Rsa2048; // Minimum recommended
let rsa3072 = CertSigAlgo::Rsa3072; // Good for long-term security
let rsa4096 = CertSigAlgo::Rsa4096; // Maximum security

Algorithm Selection Guide

Ed25519: Best choice for new deployments (fast, secure, modern)
ECDSA P-256: Good compatibility, widely supported
ECDSA P-384: Higher security requirements
RSA 2048: Legacy compatibility (minimum acceptable)
RSA 3072/4096: Long-term security, regulatory compliance

Distinguished Names

Creating Distinguished Names

use cutil::types::DistinguishedName;

let dn = DistinguishedName::new("example.com")
    .with_organization("Example Corporation")
    .with_organizational_unit("IT Department")
    .with_country("US")
    .with_state("California")
    .with_locality("San Francisco");

Available Fields

Common Name (CN): Primary identifier (required)
Organization (O): Company or organization name
Organizational Unit (OU): Department or division
Country (C): Two-letter country code (ISO 3166-1 alpha-2)
State (ST): State or province
Locality (L): City or locality

Revocation Reasons

use cutil::types::RevocationReason;

let reasons = [
    RevocationReason::Unspecified,
    RevocationReason::KeyCompromise,
    RevocationReason::CACompromise,
    RevocationReason::AffiliationChanged,
    RevocationReason::Superseded,
    RevocationReason::CessationOfOperation,
];

Error Handling

CUtil uses a custom Result type for comprehensive error handling:

use cutil::error::{Result, Error};

fn handle_errors() -> Result<()> {
    match some_operation() {
        Ok(value) => {
            println!("Success: {:?}", value);
            Ok(())
        }
        Err(Error::IoError(e)) => {
            eprintln!("I/O error: {}", e);
            Err(Error::IoError(e))
        }
        Err(Error::CertificateGeneration(msg)) => {
            eprintln!("Certificate generation failed: {}", msg);
            Err(Error::CertificateGeneration(msg))
        }
        Err(e) => {
            eprintln!("Other error: {}", e);
            Err(e)
        }
    }
}

Command-Line Interface

The CUtil CLI provides a complete command-line interface for all PKI operations.

Initialize a Root CA

cutil init \
    --cn "Example Root CA" \
    --org "Example Corporation" \
    --ou "Security" \
    --country US \
    --state California \
    --locality "San Francisco" \
    --algorithm ecdsa-p256 \
    --validity 3650 \
    --cert-out root-ca.pem \
    --key-out root-ca-key.pem

Create an Intermediate CA

cutil init \
    --cn "Example Intermediate CA" \
    --org "Example Corporation" \
    --algorithm ecdsa-p256 \
    --validity 1825 \
    --intermediate \
    --parent-cert root-ca.pem \
    --parent-key root-ca-key.pem \
    --cert-out intermediate-ca.pem \
    --key-out intermediate-ca-key.pem

Issue a Server Certificate

cutil cert \
    --cn example.com \
    --cert-type server \
    --dns example.com \
    --dns www.example.com \
    --dns api.example.com \
    --org "Example Corporation" \
    --validity 365 \
    --ca-cert ca.pem \
    --ca-key ca-key.pem \
    --cert-out server.pem \
    --key-out server-key.pem \
    --chain-out fullchain.pem

Issue a Client Certificate

cutil cert \
    --cn "John Doe" \
    --cert-type client \
    --email john.doe@example.com \
    --org "Example Corporation" \
    --validity 365 \
    --ca-cert ca.pem \
    --ca-key ca-key.pem \
    --cert-out client.pem \
    --key-out client-key.pem

Export Certificate as PKCS#12

cutil cert \
    --cn example.com \
    --cert-type server \
    --dns example.com \
    --ca-cert ca.pem \
    --ca-key ca-key.pem \
    --cert-out server.pem \
    --key-out server-key.pem \
    --p12-out server.p12 \
    --p12-password "secure_password"

Fetch Remote Certificate Chain

# Pretty formatted output
cutil fetch google.com:443

# JSON output
cutil fetch github.com:443 --format json

# Save to file
cutil fetch example.com:443 --format json --output example-chain.json

Revoke a Certificate

cutil revoke \
    --serial 01:02:03:04:05:06:07:08 \
    --reason key-compromise \
    --ca-cert ca.pem \
    --ca-key ca-key.pem

Available revocation reasons:

unspecified
key-compromise or keycompromise
ca-compromise or cacompromise
affiliation-changed or affiliationchanged
superseded
cessation or cessationofoperation

Generate Certificate Revocation List

cutil crl \
    --ca-cert ca.pem \
    --ca-key ca-key.pem \
    --output ca.crl

Display Certificate Chain

cutil chain server.pem

Best Practices

Development and Testing

use cutil::ca::CertificateAuthority;
use cutil::cert::CertificateBuilder;
use cutil::types::{CertSigAlgo, DistinguishedName};
use cutil::error::Result;

fn create_test_pki() -> Result<()> {
    // Create test CA
    let ca_subject = DistinguishedName::new("Test CA");
    let mut ca = CertificateAuthority::new_root(
        ca_subject,
        CertSigAlgo::EcdsaP256,
        365,
    )?;

    // Issue test certificate
    let cert = CertificateBuilder::server("localhost")
        .with_dns_san("localhost")
        .with_ip_san("127.0.0.1".parse().unwrap())
        .with_validity_days(30)
        .issue(&mut ca)?;

    cert.save_pem("test-cert.pem", "test-key.pem")?;
    Ok(())
}

Examples

Complete working examples are available in the repository:

basic_ca.rs: Create a CA and issue server/client certificates
fetch_remote.rs: Fetch and inspect remote TLS certificates

Run examples with:

cargo run --example basic_ca
cargo run --example fetch_remote

Dependencies

CUtil is built on industry-standard cryptographic libraries:

rcgen: Certificate generation and signing
rustls: TLS protocol implementation
rustls-pemfile: PEM file parsing
webpki: Web PKI certificate validation
x509-parser: X.509 certificate parsing
thiserror: Ergonomic error handling
chrono: Date and time operations
colored: Terminal output formatting
serde / serde_json: JSON serialization support
clap: Command-line argument parsing
p12: PKCS#12 archive support

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
bin		bin
examples		examples
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Overview

Features

Installation

Quick Start

Library Usage

Command-Line Interface

Library API Reference

Certificate Authority Operations

Creating a Root CA

Creating an Intermediate CA

Loading an Existing CA

Certificate Issuance

Server Certificates

Server Certificates with Custom Subject

Client Certificates

Certificates with IP SANs

Certificates with CRL and OCSP URLs

Certificate Export Formats

Exporting Certificate Chains

Exporting as PKCS#12

Certificate Revocation

Revoking a Certificate

Generating a Certificate Revocation List (CRL)

Checking Revoked Certificates

Remote Certificate Inspection

Fetching Certificate Chains

Displaying Certificate Chain Information

Saving Certificate Chain to File

Signature Algorithms

Ed25519 (Recommended for Modern Systems)

ECDSA with NIST Curves

RSA

Algorithm Selection Guide

Distinguished Names

Creating Distinguished Names

Available Fields

Revocation Reasons

Error Handling

Command-Line Interface

Initialize a Root CA

Create an Intermediate CA

Issue a Server Certificate

Issue a Client Certificate

Export Certificate as PKCS#12

Fetch Remote Certificate Chain

Revoke a Certificate

Generate Certificate Revocation List

Display Certificate Chain

Best Practices

Development and Testing

Examples

Dependencies

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages