eneros-trust

eneros-trust 实现 EnerOS 零信任安全模型的根基：内置 CA、mTLS 双向认证、证书自动轮转。系统内所有服务间通信默认强制 mTLS，无明文传输。这是 EnerOS 满足 NERC CIP / IEC 62443 / 等保 2.0 等合规要求的关键基础。

职责描述

eneros-trust 承担以下核心职责：

• 内部 CA：签发服务证书，支持 ECDSA P-256（推荐）与 RSA 4096 两种密钥算法
• mTLS 接受器：替代标准 TLS 接受器，强制客户端证书校验，拒绝无证书连接
• 证书自动轮转：到期前 30 天自动轮转，零停机，新旧证书平滑过渡
• 证书撤销列表（CRL）：支持主动撤销与 OCSP 装订，及时封禁失窃证书
• 信任锚（Trust Anchor）：根证书分发与更新，跨区域信任建立
• 证书存储：基于文件系统的安全存储，权限 600，所有权隔离
• 密钥归档：历史密钥归档与合规审计

关键类型与接口

CaManager

use rcgen::{Certificate, PrivateKey};
use std::path::Path;

pub struct CaManager {
    ca_cert: Certificate,
    ca_key: PrivateKey,
    validity_days: u32,
    algorithm: KeyAlgorithm,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum KeyAlgorithm {
    EcdsaP256,
    Rsa4096,
}

impl Default for KeyAlgorithm {
    fn default() -> Self {
        Self::EcdsaP256
    }
}

impl CaManager {
    pub fn initialize(common_name: &str) -> Result<Self> {
        let params = rcgen::CertificateParams::new(vec![common_name.to_string()]);
        let mut params = params;
        params.distinguished_name = rcgen::DistinguishedName::new();
        params.distinguished_name.push(
            rcgen::DnType::CommonName,
            common_name,
        );
        params.is_ca = rcgen::IsCa::Ca(rcgen::BasicConstraints::Constrained(5));
        params.key_pair = Some(rcgen::KeyPair::generate(&rcgen::PKCS_ECDSA_P256_SHA256)?);

        let ca_cert = rcgen::Certificate::from_params(params)?;
        let ca_key = ca_cert.serialize_private_key_der();

        Ok(Self {
            ca_cert,
            ca_key: PrivateKey(ca_key),
            validity_days: 3650,
            algorithm: KeyAlgorithm::EcdsaP256,
        })
    }

    pub fn save_to_dir(&self, dir: impl AsRef<Path>) -> Result<()> {
        let dir = dir.as_ref();
        std::fs::create_dir_all(dir)?;
        let cert_path = dir.join("ca.crt");
        let key_path = dir.join("ca.key");

        let cert_pem = self.ca_cert.serialize_pem()?;
        std::fs::write(&cert_path, cert_pem)?;
        set_permissions_600(&cert_path)?;

        std::fs::write(&key_path, &self.ca_key.0)?;
        set_permissions_600(&key_path)?;

        Ok(())
    }

    pub fn load_from_dir(dir: impl AsRef<Path>) -> Result<Self> {
        let dir = dir.as_ref();
        let cert_pem = std::fs::read_to_string(dir.join("ca.crt"))?;
        let key_der = std::fs::read(dir.join("ca.key"))?;
        // 解析并重建 CA
        Self::parse(&cert_pem, &key_der)
    }

    fn parse(cert_pem: &str, key_der: &[u8]) -> Result<Self> {
        // 实际实现使用 rustls-pemfile / x509-parser 解析
        unimplemented!()
    }

    pub fn issue(&self, subject: &str) -> Result<(Certificate, PrivateKey)> {
        let mut params = rcgen::CertificateParams::new(vec![subject.to_string()]);
        params.distinguished_name.push(
            rcgen::DnType::CommonName,
            subject,
        );
        params.key_pair = Some(rcgen::KeyPair::generate(&rcgen::PKCS_ECDSA_P256_SHA256)?);

        let cert = rcgen::Certificate::from_params(params)?;
        let signed = cert.serialize_pem_with_signer(&self.ca_cert)?;
        let key = cert.serialize_private_key_der();

        Ok((cert, PrivateKey(key)))
    }

    pub fn revoke(&self, cert: &Certificate) -> Result<()> {
        // 将证书序列号加入 CRL
        Ok(())
    }

    pub fn trust_anchor(&self) -> TrustAnchor {
        TrustAnchor {
            cert_pem: self.ca_cert.serialize_pem().unwrap(),
        }
    }
}

fn set_permissions_600(path: &Path) -> Result<()> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = std::fs::metadata(path)?.permissions();
        perms.set_mode(0o600);
        std::fs::set_permissions(path, perms)?;
    }
    Ok(())
}

CertManager

use std::time::Duration;
use tokio::time::interval;

pub struct CertManager {
    ca: CaManager,
    rotation_threshold: Duration,
    current_cert: Option<Certificate>,
    current_key: Option<PrivateKey>,
}

impl CertManager {
    pub fn new(ca: CaManager) -> Self {
        Self {
            ca,
            rotation_threshold: Duration::from_secs(30 * 24 * 3600),
            current_cert: None,
            current_key: None,
        }
    }

    pub fn rotation_threshold(mut self, threshold: Duration) -> Self {
        self.rotation_threshold = threshold;
        self
    }

    pub async fn start_rotation_loop(&self) {
        let mut ticker = interval(Duration::from_secs(3600));
        loop {
            ticker.tick().await;
            if let Some(cert) = &self.current_cert {
                if self.should_rotate(cert) {
                    self.rotate().await;
                }
            }
        }
    }

    fn should_rotate(&self, cert: &Certificate) -> bool {
        // 检查证书有效期是否即将到期
        let expires_at = cert.get_expiration_time();
        let remaining = expires_at - chrono::Utc::now();
        remaining < self.rotation_threshold
    }

    async fn rotate(&self) {
        // 1. 签发新证书
        // 2. 平滑切换（新旧证书并行接受）
        // 3. 旧证书加入 CRL
        // 4. 通知所有依赖服务
    }

    pub fn current_cert(&self) -> Option<&Certificate> {
        self.current_cert.as_ref()
    }

    pub fn issue_for(&self, subject: &str) -> Result<(Certificate, PrivateKey)> {
        self.ca.issue(subject)
    }
}

MtlsAcceptor

use tokio::net::TcpStream;
use rustls::ServerConfig;

pub struct MtlsAcceptor {
    trust_anchor: TrustAnchor,
    server_config: ServerConfig,
    verify_client: bool,
    min_protocol: TlsVersion,
    max_protocol: TlsVersion,
}

#[derive(Debug, Clone, Copy)]
pub struct TlsVersion {
    pub major: u8,
    pub minor: u8,
}

impl TlsVersion {
    pub const TLS_1_3: Self = Self { major: 3, minor: 4 };
    pub const TLS_1_2: Self = Self { major: 3, minor: 3 };
}

#[derive(Debug, Clone)]
pub struct TrustAnchor {
    pub cert_pem: String,
}

pub struct MtlsAcceptorBuilder {
    trust_anchor: Option<TrustAnchor>,
    server_cert: Option<Certificate>,
    server_key: Option<PrivateKey>,
    verify_client: bool,
    min_protocol: TlsVersion,
    max_protocol: TlsVersion,
}

impl MtlsAcceptorBuilder {
    pub fn new() -> Self {
        Self {
            trust_anchor: None,
            server_cert: None,
            server_key: None,
            verify_client: true,
            min_protocol: TlsVersion::TLS_1_2,
            max_protocol: TlsVersion::TLS_1_3,
        }
    }

    pub fn trust_anchor(mut self, ta: TrustAnchor) -> Self {
        self.trust_anchor = Some(ta);
        self
    }

    pub fn server_cert(mut self, cert: Certificate, key: PrivateKey) -> Self {
        self.server_cert = Some(cert);
        self.server_key = Some(key);
        self
    }

    pub fn verify_client(mut self, verify: bool) -> Self {
        self.verify_client = verify;
        self
    }

    pub fn min_protocol(mut self, v: TlsVersion) -> Self {
        self.min_protocol = v;
        self
    }

    pub fn build(self) -> Result<MtlsAcceptor> {
        let trust_anchor = self.trust_anchor.ok_or_else(|| {
            EnerOSError::Internal("trust_anchor required".into())
        })?;
        let server_cert = self.server_cert.ok_or_else(|| {
            EnerOSError::Internal("server_cert required".into())
        })?;
        let server_key = self.server_key.ok_or_else(|| {
            EnerOSError::Internal("server_key required".into())
        })?;

        let server_config = Self::build_server_config(
            &server_cert,
            &server_key,
            &trust_anchor,
            self.verify_client,
        )?;

        Ok(MtlsAcceptor {
            trust_anchor,
            server_config,
            verify_client: self.verify_client,
            min_protocol: self.min_protocol,
            max_protocol: self.max_protocol,
        })
    }

    fn build_server_config(
        cert: &Certificate,
        key: &PrivateKey,
        anchor: &TrustAnchor,
        verify_client: bool,
    ) -> Result<ServerConfig> {
        let mut roots = rustls::RootCertStore::empty();
        roots.add(anchor.cert_pem.as_bytes())?;

        let client_auth = if verify_client {
            rustls::server::AllowAnyAuthenticatedClient::new(roots).boxed()
        } else {
            rustls::server::AllowAnyAnonymousOrAuthenticatedClient::new(roots).boxed()
        };

        let server_config = ServerConfig::builder()
            .with_safe_defaults()
            .with_client_cert_verifier(client_auth)
            .with_single_cert(
                vec![rustls::Certificate(cert.serialize_der()?)],
                rustls::PrivateKey(key.0.clone()),
            )?;

        Ok(server_config)
    }
}

impl MtlsAcceptor {
    pub fn builder() -> MtlsAcceptorBuilder {
        MtlsAcceptorBuilder::new()
    }

    pub async fn accept(&self, stream: TcpStream) -> Result<TlsStream> {
        let acceptor = tokio_rustls::TlsAcceptor::from(
            std::sync::Arc::new(self.server_config.clone())
        );
        let tls_stream = acceptor.accept(stream).await?;
        Ok(TlsStream { inner: tls_stream })
    }
}

pub struct TlsStream {
    inner: tokio_rustls::server::TlsStream<TcpStream>,
}

CRL / 撤销

pub struct CrlManager {
    revoked: std::collections::HashSet<SerialNumber>,
    last_update: chrono::DateTime<chrono::Utc>,
}

#[derive(Debug, Clone, Hash, PartialEq, Eq)]
pub struct SerialNumber(pub String);

impl CrlManager {
    pub fn new() -> Self {
        Self {
            revoked: std::collections::HashSet::new(),
            last_update: chrono::Utc::now(),
        }
    }

    pub fn revoke(&mut self, serial: SerialNumber) {
        self.revoked.insert(serial);
        self.last_update = chrono::Utc::now();
    }

    pub fn is_revoked(&self, serial: &SerialNumber) -> bool {
        self.revoked.contains(serial)
    }

    pub fn to_pem(&self) -> String {
        let mut lines = vec!["-----BEGIN X509 CRL-----".to_string()];
        for serial in &self.revoked {
            lines.push(serial.0.clone());
        }
        lines.push(format!("last_update: {}", self.last_update));
        lines.push("-----END X509 CRL-----".to_string());
        lines.join("\n")
    }
}

核心 API

使用示例

初始化 CA

use eneros_trust::{CaManager, CertManager};
use std::time::Duration;

let ca = CaManager::initialize("eneros-ca")?;
ca.save_to_dir("/var/lib/eneros/ca")?;

let cert_mgr = CertManager::new(ca)
    .rotation_threshold(Duration::from_secs(30 * 24 * 3600));

// 启动自动轮转后台任务
tokio::spawn(async move {
    cert_mgr.start_rotation_loop().await;
});

服务端启用 mTLS

use eneros_trust::MtlsAcceptor;
use axum::Server;

let acceptor = MtlsAcceptor::builder()
    .trust_anchor(ca.trust_anchor())
    .server_cert(server_cert, server_key)
    .verify_client(true)
    .min_protocol(eneros_trust::TlsVersion::TLS_1_2)
    .build()?;

let listener = tokio::net::TcpListener::bind("0.0.0.0:8443").await?;
loop {
    let (stream, _) = listener.accept().await?;
    let acceptor = acceptor.clone();
    tokio::spawn(async move {
        match acceptor.accept(stream).await {
            Ok(tls_stream) => {
                tracing::info!("mTLS 连接已建立");
                // 处理 tls_stream
            }
            Err(e) => tracing::warn!("mTLS 握手失败: {}", e),
        }
    });
}

签发客户端证书

use eneros_trust::CaManager;

let ca = CaManager::load_from_dir("/var/lib/eneros/ca")?;

let (cert, key) = ca.issue("agent-01.eneros.local")?;
cert.write_pem("agent-01.crt")?;
key.write_pem("agent-01.key")?;

println!("已为 agent-01 签发证书，有效期 {} 天", 90);

撤销证书

use eneros_trust::{CaManager, CrlManager, SerialNumber};

let mut crl = CrlManager::new();
crl.revoke(SerialNumber("agent-05".into()));

let ca = CaManager::load_from_dir("/var/lib/eneros/ca")?;
ca.revoke(&stolen_cert)?;

println!("CRL PEM:");
println!("{}", crl.to_pem());

客户端使用 mTLS 连接

use eneros_trust::{MtlsConnector, TrustAnchor};

let connector = MtlsConnector::builder()
    .trust_anchor(server_trust_anchor)
    .client_cert(client_cert, client_key)
    .server_name("api.eneros.local")
    .build()?;

let stream = tokio::net::TcpStream::connect("api.eneros.local:8443").await?;
let tls_stream = connector.connect(stream).await?;
println!("mTLS 客户端连接已建立");

证书生命周期

签发 (issue)
  ↓
分发 (distribute) — 写入 /var/lib/eneros/certs/<subject>.{crt,key}
  ↓
使用 (active) — 服务启动加载证书
  ↓
到期前 30 天 (rotation_threshold)
  ↓
自动轮转 (rotate) — 签发新证书 + 平滑切换
  ↓
旧证书加入 CRL (revoke)
  ↓
归档 (archive) — 历史密钥归档至 WORM 存储

配置参数表

[trust] 配置段

KeyAlgorithm 算法

TlsVersion 支持矩阵

性能指标

测试环境：4 核 / 8GB / Ubuntu 22.04 / Rust 1.78 release build。

依赖关系

自身依赖

[dependencies]
eneros-core = { path = "../core", version = "0.47.0" }
rcgen = "0.13"
rustls = "0.23"
tokio-rustls = "0.26"
rustls-pemfile = "2"
x509-parser = "0.16"
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
tracing = "0.1"
chrono = { version = "0.4", features = ["serde"] }

被依赖

eneros-trust 是所有网络服务的安全根基，被以下 crate 依赖：

• eneros-gateway — 网关 mTLS 鉴权
• eneros-api — API 服务 mTLS 接受器
• eneros-scada — SCADA 通道 mTLS
• eneros-edge — 边缘节点与中心节点 mTLS
• eneros-multiregion — 跨区域信任建立
• eneros-protocol-mqtt — MQTT broker mTLS
• eneros-protocol-iccp — ICCP/TASE.2 mTLS

合规对应

版本与兼容性

相关文档

• 零信任与安全增强 — 能力详解
• 零信任架构 — 合规视角
• eneros-gateway — 网关鉴权
• eneros-audit — 审计链
• eneros-compliance — 合规自动化
• Crate 索引 — 完整列表