acmex

AcmeX

AcmeX is a modular, enterprise-grade ACME v2 (RFC 8555) client and server ecosystem written in Rust. It is designed for high performance, reliability, and extensibility, supporting various DNS providers, storage backends, and cryptographic libraries. AcmeX enables automated certificate lifecycle management with advanced features like OCSP verification, multi-provider DNS-01 challenges, and a RESTful management API.

🏗 Architecture

AcmeX follows a layered design to ensure separation of concerns and ease of maintenance:

Application Layer: CLI and REST API (Axum-based) entry points for user interaction.
Orchestration Layer: High-level workflow management for provisioning, validation, and renewal processes.
Scheduling Layer: Task execution and concurrency management for asynchronous operations.
Protocol Layer: Low-level ACME implementation (JWS, Nonce management, Directory handling).
Storage Tier: Pluggable backends (File, Redis, Memory, Encrypted) for persistence.
Certificate Tier: Chain verification, CSR generation, and OCSP status checking for security.

🚀 Key Features

Full ACME v2 Support: Complete implementation of RFC 8555, including all challenge types and account management.
Asynchronous Execution: Non-blocking task polling for long-running operations, ensuring responsiveness.
Multiple Challenge Types: Support for HTTP-01, DNS-01, and TLS-ALPN-01 challenges.
Extensive DNS Support: Built-in providers for Cloudflare, AWS Route53, Alibaba Cloud, Azure, Google Cloud, Huawei, Tencent, and more.
Flexible Storage: Support for local files, Redis, and encrypted storage backends.
Multi-CA Support: Integration with Let’s Encrypt, Google CA, ZeroSSL, and custom ACME servers.
Observability: Integrated metrics (Prometheus), structured logging (Tracing), and OpenTelemetry support.
Security First: Memory safety via Rust, zeroize for sensitive data, and RFC 7807 error reporting.
CLI and API: Command-line interface and RESTful API for easy integration and management.
Feature Gates: Optional dependencies for DNS providers, storage backends, and crypto libraries to keep the core lightweight.

🛠 Installation

Add AcmeX to your Cargo.toml:

[dependencies]
acmex = "0.8.0"

Feature Flags

Enable optional features as needed:

[dependencies.acmex]
version = "0.8.0"
features = ["dns-cloudflare", "redis", "cli"]

Available features:

Crypto: aws-lc-rs (default), ring-crypto
Storage: redis
DNS Providers: dns-cloudflare, dns-route53, dns-alibaba, dns-azure, dns-google, dns-huawei, dns-tencent, etc.
CAs: google-ca, zerossl-ca
Other: metrics, cli

📖 Quick Start

Basic Certificate Issuance

use acmex::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Configure the client
    let config = AcmeConfig::lets_encrypt_staging()
        .with_contact(Contact::email("admin@example.com"))
        .with_tos_agreed(true);

    let mut client = AcmeClient::new(config)?;

    // 2. Set up challenge solvers
    let mut solver_registry = ChallengeSolverRegistry::new();
    // For DNS-01 challenge with Cloudflare (enable dns-cloudflare feature)
    // solver_registry.register(Box::new(CloudflareSolver::new(api_token, zone_id)?));
    // For HTTP-01 challenge
    // solver_registry.register(Box::new(Http01Solver::new()));

    // 3. Issue a certificate
    let domains = vec!["example.com".to_string(), "www.example.com".to_string()];
    let bundle = client.issue_certificate(domains, &mut solver_registry).await?;

    // 4. Save the certificate
    bundle.save_to_files("cert.pem", "key.pem")?;

    Ok(())
}

Running the API Server

# Build and run the server
cargo run --features cli -- --config acmex.toml

Example acmex.toml:

[server]
host = "0.0.0.0"
port = 8080
api_key = "your-secret-api-key"

[storage]
backend = "file"
path = "./data"

[acme]
directory_url = "https://acme-v02.api.letsencrypt.org/directory"
contact_email = "admin@example.com"

🛠 Development

Prerequisites

Rust 1.92+
Docker (for Redis testing)

Building

cargo build

Running Tests

cargo test

Examples

Explore the examples/ directory for more usage patterns:

📄 Documentation

Detailed documentation is available in the docs directory:

API documentation: docs.rs/acmex

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

Reporting Issues

GitHub Issues
For security issues, please email housemecn@gmail.com

📜 License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

This site is open source. Improve this page.