Skip to content

Security: Nexa-Language/Nexa-net

Security

docs/SECURITY.md

Nexa-net 安全设计规范

版本: v1.0.0-draft | 最后更新: 2026-03-30

目录


1. 安全概述

1.1 安全设计原则

Nexa-net 遵循以下安全设计原则:

原则 描述 实现方式
零信任架构 不信任任何预设关系,每次通信都验证 mTLS、DID 认证
最小权限 只授予必要的最小权限 VC 权限控制
深度防御 多层安全机制 身份层 + 传输层 + 应用层
安全默认 默认配置即为安全配置 强制加密、强制认证
可审计性 所有操作可追溯 日志、签名收据

1.2 安全架构

┌─────────────────────────────────────────────────────────────┐
│                    Security Architecture                    │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Application Layer                       │   │
│  │  - 输入验证                                          │   │
│  │  - 输出编码                                          │   │
│  │  - 业务逻辑安全                                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Economy Layer                           │   │
│  │  - 预算控制                                          │   │
│  │  - 通道安全                                          │   │
│  │  - 收据验证                                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Transport Layer                         │   │
│  │  - mTLS 加密                                         │   │
│  │  - 协议协商                                          │   │
│  │  - 消息完整性                                        │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Identity Layer                          │   │
│  │  - DID 认证                                          │   │
│  │  - VC 验证                                           │   │
│  │  - 密钥管理                                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Infrastructure Layer                    │   │
│  │  - 网络隔离                                          │   │
│  │  - 访问控制                                          │   │
│  │  - 日志审计                                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.3 安全目标

目标 描述 指标
机密性 数据不被未授权方访问 全程加密
完整性 数据不被篡改 签名验证
可用性 服务持续可用 99.9% SLA
认证性 身份可验证 DID + mTLS
不可否认性 操作可追溯 数字签名

2. 威胁模型

2.1 威胁分类

2.1.1 STRIDE 威胁模型

威胁类型 描述 Nexa-net 缓解措施
Spoofing (欺骗) 冒充合法身份 DID 认证、mTLS
Tampering (篡改) 修改数据或通信 数字签名、消息认证码
Repudiation (抵赖) 否认执行过操作 签名收据、审计日志
Information Disclosure (信息泄露) 未授权访问数据 加密存储、传输加密
Denial of Service (拒绝服务) 使服务不可用 速率限制、预算控制
Elevation of Privilege (权限提升) 获取未授权权限 VC 权限控制、最小权限

2.2 攻击场景分析

2.2.1 身份攻击

┌─────────────────────────────────────────────────────────────┐
│                    Identity Attacks                         │
│                                                             │
│  攻击类型: 私钥窃取                                          │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 窃取 Agent 私钥                                     │
│  影响: 完全控制 Agent 身份                                   │
│  缓解:                                                       │
│  - 私钥加密存储 (AES-256)                                    │
│  - 密钥轮换机制                                              │
│  - 多因素认证(可选)                                        │
│  - 异常行为检测                                              │
│                                                             │
│  攻击类型: DID 劫持                                          │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 替换 DID Document                                   │
│  影响: 重定向通信到攻击者                                    │
│  缓解:                                                       │
│  - DID Document 签名验证                                     │
│  - DHT 数据完整性校验                                        │
│  - 变更通知机制                                              │
│                                                             │
│  攻击类型: VC 伪造                                           │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 伪造或篡改凭证                                      │
│  影响: 获取未授权权限                                        │
│  缓解:                                                       │
│  - VC 签名验证                                               │
│  - 信任链验证                                                │
│  - 凭证过期检查                                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2.2 通信攻击

┌─────────────────────────────────────────────────────────────┐
│                   Communication Attacks                     │
│                                                             │
│  攻击类型: 中间人攻击 (MITM)                                 │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 拦截并修改通信                                      │
│  影响: 数据泄露、篡改                                        │
│  缓解:                                                       │
│  - 强制 mTLS                                                 │
│  - 证书绑定 (Certificate Pinning)                            │
│  - DID 验证                                                  │
│                                                             │
│  攻击类型: 重放攻击                                          │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 重放历史消息                                        │
│  影响: 重复执行操作                                          │
│  缓解:                                                       │
│  - 时间戳验证                                                │
│  - Nonce 机制                                                │
│  - 序列号检查                                                │
│                                                             │
│  攻击类型: 流量分析                                          │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 分析通信模式                                        │
│  影响: 隐私泄露                                              │
│  缓解:                                                       │
│  - 流量填充                                                  │
│  - 路由随机化                                                │
│  - 元数据最小化                                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2.3 经济攻击

┌─────────────────────────────────────────────────────────────┐
│                     Economic Attacks                        │
│                                                             │
│  攻击类型: 余额伪造                                          │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 伪造收据或余额                                      │
│  影响: 非法获取 Token                                        │
│  缓解:                                                       │
│  - 收据双签名验证                                            │
│  - 序列号递增检查                                            │
│  - 余额一致性校验                                            │
│                                                             │
│  攻击类型: 死循环攻击                                        │
│  ────────────────────────────────────────────────────────  │
│  攻击者: Agent A→B→A→B... 循环调用                           │
│  影响: 资源耗尽                                              │
│  缓解:                                                       │
│  - 调用深度限制                                              │
│  - 循环检测                                                  │
│  - 预算控制                                                  │
│                                                             │
│  攻击类型: 恶意关闭                                          │
│  ────────────────────────────────────────────────────────  │
│  攻击者: 用旧余额关闭通道                                    │
│  影响: 窃取对方余额                                          │
│  缓解:                                                       │
│  - 最新收据反驳机制                                          │
│  - 争议仲裁                                                  │
│  - 时间锁                                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.3 威胁严重性评估

威胁 可能性 影响 风险等级 优先级
私钥泄露 P1
中间人攻击 P2
VC 伪造 P2
死循环攻击 P2
余额伪造 P2
重放攻击 P3
流量分析 P4

3. 身份与认证安全

3.1 DID 安全

3.1.1 密钥安全要求

# key_security.yaml
key_generation:
  algorithm: "Ed25519"  # 或 Secp256k1
  entropy_source: "secure_random"  # /dev/urandom 或硬件 RNG
  key_size: 256  # bits
  
key_storage:
  encryption: "AES-256-GCM"
  kdf: "PBKDF2"
  kdf_iterations: 100000
  storage_location: "secure_enclave"  # 优先使用安全区域
  
key_usage:
  single_purpose: true  # 一个密钥一个用途
  rotation_period: 90  # days
  backup_required: true

3.1.2 密钥生命周期管理

┌─────────────────────────────────────────────────────────────┐
│                   Key Lifecycle Management                  │
│                                                             │
│  ┌─────────┐                                               │
│  │ Generate│  安全随机生成                                  │
│  └─────────┘                                               │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────┐                                               │
│  │  Store  │  加密存储                                      │
│  └─────────┘                                               │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────┐                                               │
│  │  Use    │  内存安全使用                                  │
│  └─────────┘                                               │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────┐                                               │
│  │ Rotate  │  定期轮换                                      │
│  └─────────┘                                               │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────┐                                               │
│  │ Destroy │  安全销毁                                      │
│  └─────────┘                                               │
│                                                             │
│  安全要求:                                                   │
│  - 生成: 使用密码学安全随机数生成器                          │
│  - 存储: AES-256-GCM 加密,PBKDF2 密钥派生                   │
│  - 使用: 内存中安全处理,使用后清零                          │
│  - 轮换: 保留过渡期,确保平滑迁移                            │
│  - 销毁: 多次覆写,确保不可恢复                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

3.2 认证安全

3.2.1 mTLS 配置

# mtls_config.yaml
tls:
  version: "TLSv1.3"  # 仅支持 TLS 1.3
  
  cipher_suites:
    # 推荐密码套件
    - TLS_AES_256_GCM_SHA384
    - TLS_CHACHA20_POLY1305_SHA256
    - TLS_AES_128_GCM_SHA256
    
  # 禁用的密码套件
  disabled:
    - TLS_RSA_*
    - TLS_ECDHE_RSA_WITH_*
    - *SHA*
    - *CBC*
    
  certificate:
    algorithm: "Ed25519"
    validity: 365  # days
    key_usage:
      - digitalSignature
      - keyEncipherment
    extended_key_usage:
      - clientAuth
      - serverAuth
      
  verification:
    mode: "require_and_verify"  # 双向认证
    depth: 3
    verify_did: true

3.2.2 会话安全

interface SessionSecurity {
  // 会话超时
  sessionTimeout: number;  // 3600 seconds
  
  // 最大会话数
  maxSessions: number;  // 100
  
  // 会话 ID 生成
  sessionIdGenerator: () => string;  // 密码学安全随机
  
  // 会话验证
  sessionValidation: {
    verifyDID: boolean;
    verifyCertificate: boolean;
    verifyTimestamp: boolean;
  };
  
  // 会话清理
  sessionCleanup: {
    onLogout: boolean;
    onTimeout: boolean;
    onIdle: number;  // seconds
  };
}

3.3 凭证安全

3.3.1 VC 安全要求

class VCSecurityValidator:
    """VC 安全验证器"""
    
    def validate_vc(self, vc: dict) -> tuple[bool, list[str]]:
        """验证 VC 安全性"""
        errors = []
        
        # 1. 验证签名
        if not self._verify_signature(vc):
            errors.append("Invalid signature")
        
        # 2. 验证过期时间
        if self._is_expired(vc):
            errors.append("VC expired")
        
        # 3. 验证签发者
        if not self._verify_issuer(vc):
            errors.append("Untrusted issuer")
        
        # 4. 验证撤销状态
        if self._is_revoked(vc):
            errors.append("VC revoked")
        
        # 5. 验证权限范围
        if not self._validate_scope(vc):
            errors.append("Invalid scope")
        
        return len(errors) == 0, errors
    
    def _verify_signature(self, vc: dict) -> bool:
        """验证签名"""
        proof = vc.get("proof", {})
        # 使用签发者公钥验证
        return verify_jws(proof.get("proofValue"), vc)
    
    def _is_expired(self, vc: dict) -> bool:
        """检查是否过期"""
        expiration = vc.get("expirationDate")
        if expiration:
            return datetime.fromisoformat(expiration) < datetime.utcnow()
        return False
    
    def _verify_issuer(self, vc: dict) -> bool:
        """验证签发者"""
        issuer_did = vc.get("issuer", {}).get("id")
        return is_trusted_issuer(issuer_did)
    
    def _is_revoked(self, vc: dict) -> bool:
        """检查是否撤销"""
        vc_id = vc.get("id")
        return check_revocation_status(vc_id)

4. 通信安全

4.1 传输加密

4.1.1 加密要求

层级 加密方式 密钥长度
传输层 TLS 1.3 AES-256-GCM
应用层 端到端加密 X25519 + ChaCha20-Poly1305
存储层 静态加密 AES-256-GCM

4.1.2 端到端加密

class EndToEndEncryption:
    """端到端加密"""
    
    def __init__(self, private_key: X25519PrivateKey):
        self.private_key = private_key
    
    def encrypt_for_peer(
        self, 
        data: bytes, 
        peer_public_key: X25519PublicKey
    ) -> bytes:
        """为特定接收者加密"""
        
        # 1. 密钥协商
        shared_key = self.private_key.exchange(peer_public_key)
        
        # 2. 派生加密密钥
        salt = os.urandom(16)
        encryption_key = HKDF(
            algorithm=hashes.SHA256(),
            length=32,
            salt=salt,
            info=b"nexa-e2e-encryption"
        ).derive(shared_key)
        
        # 3. 加密
        nonce = os.urandom(12)
        cipher = ChaCha20Poly1305(encryption_key)
        ciphertext = cipher.encrypt(nonce, data, None)
        
        # 4. 组装消息
        return salt + nonce + ciphertext
    
    def decrypt_from_peer(
        self,
        encrypted_data: bytes,
        peer_public_key: X25519PublicKey
    ) -> bytes:
        """解密来自特定发送者的数据"""
        
        # 1. 解析消息
        salt = encrypted_data[:16]
        nonce = encrypted_data[16:28]
        ciphertext = encrypted_data[28:]
        
        # 2. 密钥协商
        shared_key = self.private_key.exchange(peer_public_key)
        
        # 3. 派生加密密钥
        encryption_key = HKDF(
            algorithm=hashes.SHA256(),
            length=32,
            salt=salt,
            info=b"nexa-e2e-encryption"
        ).derive(shared_key)
        
        # 4. 解密
        cipher = ChaCha20Poly1305(encryption_key)
        return cipher.decrypt(nonce, ciphertext, None)

4.2 消息完整性

4.2.1 消息签名

def sign_message(
    message: dict,
    private_key: Ed25519PrivateKey
) -> dict:
    """签名消息"""
    
    # 1. 规范化消息
    canonical = json.dumps(message, sort_keys=True)
    
    # 2. 添加时间戳防止重放
    timestamp = int(datetime.utcnow().timestamp())
    message["timestamp"] = timestamp
    
    # 3. 签名
    signature = private_key.sign(canonical.encode())
    
    # 4. 添加签名
    message["signature"] = base64.b64encode(signature).decode()
    
    return message

def verify_message(
    message: dict,
    public_key: Ed25519PublicKey
) -> bool:
    """验证消息签名"""
    
    # 1. 提取签名
    signature = base64.b64decode(message.pop("signature"))
    
    # 2. 检查时间戳
    timestamp = message.get("timestamp", 0)
    if abs(datetime.utcnow().timestamp() - timestamp) > 300:  # 5 分钟
        return False
    
    # 3. 规范化消息
    canonical = json.dumps(message, sort_keys=True)
    
    # 4. 验证签名
    try:
        public_key.verify(signature, canonical.encode())
        return True
    except Exception:
        return False

4.3 重放攻击防护

class ReplayProtection:
    """重放攻击防护"""
    
    def __init__(self, cache_ttl: int = 300):
        self.cache = TTLCache(maxsize=10000, ttl=cache_ttl)
    
    def check_and_record(self, message_id: str, timestamp: int) -> bool:
        """检查并记录消息 ID"""
        
        # 1. 检查时间戳是否在合理范围
        now = int(datetime.utcnow().timestamp())
        if abs(now - timestamp) > 300:  # 5 分钟
            return False
        
        # 2. 检查是否已处理
        if message_id in self.cache:
            return False
        
        # 3. 记录消息 ID
        self.cache[message_id] = True
        
        return True
    
    def generate_message_id(self) -> str:
        """生成唯一消息 ID"""
        return str(uuid.uuid4())

5. 数据安全

5.1 数据分类

数据类型 敏感级别 存储要求 传输要求
私钥 极高 AES-256 加密 永不传输
DID Document 明文(公开) TLS
VC 加密存储 TLS + 签名
收据 加密存储 TLS + 签名
能力 Schema 明文 TLS
日志 脱敏处理 TLS

5.2 数据加密

5.2.1 静态数据加密

class DataEncryption:
    """数据加密管理"""
    
    def __init__(self, master_key: bytes):
        self.master_key = master_key
    
    def encrypt_data(self, data: bytes, context: str = "") -> bytes:
        """加密数据"""
        
        # 1. 生成数据加密密钥
        dek = os.urandom(32)
        
        # 2. 加密数据
        nonce = os.urandom(12)
        cipher = AESGCM(dek)
        ciphertext = cipher.encrypt(nonce, data, context.encode())
        
        # 3. 加密数据加密密钥
        kek_nonce = os.urandom(12)
        kek_cipher = AESGCM(self.master_key)
        encrypted_dek = kek_cipher.encrypt(kek_nonce, dek, None)
        
        # 4. 组装结果
        return kek_nonce + encrypted_dek + nonce + ciphertext
    
    def decrypt_data(self, encrypted_data: bytes, context: str = "") -> bytes:
        """解密数据"""
        
        # 1. 解析组件
        kek_nonce = encrypted_data[:12]
        encrypted_dek = encrypted_data[12:60]
        nonce = encrypted_data[60:72]
        ciphertext = encrypted_data[72:]
        
        # 2. 解密数据加密密钥
        kek_cipher = AESGCM(self.master_key)
        dek = kek_cipher.decrypt(kek_nonce, encrypted_dek, None)
        
        # 3. 解密数据
        cipher = AESGCM(dek)
        return cipher.decrypt(nonce, ciphertext, context.encode())

5.3 数据脱敏

class DataSanitizer:
    """数据脱敏"""
    
    def sanitize_log(self, log_entry: dict) -> dict:
        """脱敏日志条目"""
        sanitized = log_entry.copy()
        
        # 敏感字段列表
        sensitive_fields = [
            "private_key",
            "signature",
            "token",
            "password",
            "secret"
        ]
        
        for field in sensitive_fields:
            if field in sanitized:
                sanitized[field] = "***REDACTED***"
        
        # 脱敏 DID(保留前 8 位)
        if "did" in sanitized:
            did = sanitized["did"]
            sanitized["did"] = did[:20] + "..." if len(did) > 20 else did
        
        # 脱敏 IP 地址
        if "ip" in sanitized:
            ip = sanitized["ip"]
            parts = ip.split(".")
            if len(parts) == 4:
                sanitized["ip"] = f"{parts[0]}.{parts[1]}.xxx.xxx"
        
        return sanitized

6. 经济安全

6.1 通道安全

6.1.1 通道安全机制

class ChannelSecurity:
    """通道安全"""
    
    def validate_channel_open(self, request: ChannelOpenRequest) -> bool:
        """验证通道开启请求"""
        
        # 1. 验证保证金充足
        if request.deposit <= 0:
            return False
        
        # 2. 验证双方签名
        if not self._verify_signatures(request):
            return False
        
        # 3. 验证超时设置合理
        if request.timeout < 3600:  # 最少 1 小时
            return False
        
        return True
    
    def validate_receipt(self, receipt: MicroReceipt) -> bool:
        """验证收据"""
        
        # 1. 验证双方签名
        if not self._verify_receipt_signatures(receipt):
            return False
        
        # 2. 验证序号递增
        if not self._verify_sequence(receipt):
            return False
        
        # 3. 验证余额一致性
        if not self._verify_balance(receipt):
            return False
        
        return True

6.2 预算安全

class BudgetSecurity:
    """预算安全"""
    
    def __init__(self, config: BudgetConfig):
        self.config = config
        self.usage = defaultdict(int)
        self.lock = threading.Lock()
    
    def check_and_deduct(self, did: str, amount: int) -> bool:
        """检查并扣除预算"""
        with self.lock:
            # 1. 检查单次限制
            if amount > self.config.max_per_call:
                return False
            
            # 2. 检查累计限制
            if self.usage[did] + amount > self.config.max_total:
                return False
            
            # 3. 扣除预算
            self.usage[did] += amount
            return True
    
    def detect_abuse(self, did: str) -> bool:
        """检测滥用"""
        usage_rate = self.usage[did] / self.config.max_total
        return usage_rate > 0.8  # 超过 80% 使用率

7. 网络安全

7.1 网络隔离

# network_security.yaml
network:
  segmentation:
    enabled: true
    zones:
      - name: "supernode"
        cidr: "10.0.0.0/24"
        allowed_inbound:
          - port: 443
            source: "any"
          - port: 7070
            source: "edge"
          - port: 3478
            source: "any"
            protocol: "udp"
            
      - name: "edge"
        cidr: "10.1.0.0/16"
        allowed_outbound:
          - port: 443
            destination: "supernode"
          - port: 7070
            destination: "supernode"
            
  firewall:
    default_policy: "deny"
    rules:
      - action: "allow"
        protocol: "tcp"
        port: 443
      - action: "allow"
        protocol: "tcp"
        port: 7070
      - action: "allow"
        protocol: "udp"
        port: 3478

7.2 DDoS 防护

class DDoSProtection:
    """DDoS 防护"""
    
    def __init__(self, config: DDoSConfig):
        self.config = config
        self.request_counts = defaultdict(list)
    
    def check_rate_limit(self, client_id: str) -> bool:
        """检查速率限制"""
        now = time.time()
        
        # 清理过期记录
        self.request_counts[client_id] = [
            t for t in self.request_counts[client_id]
            if now - t < self.config.window_seconds
        ]
        
        # 检查是否超限
        if len(self.request_counts[client_id]) >= self.config.max_requests:
            return False
        
        # 记录请求
        self.request_counts[client_id].append(now)
        return True
    
    def detect_attack(self) -> bool:
        """检测攻击"""
        total_requests = sum(len(v) for v in self.request_counts.values())
        return total_requests > self.config.attack_threshold

7.3 入侵检测

class IntrusionDetection:
    """入侵检测"""
    
    def __init__(self):
        self.alerts = []
        self.thresholds = {
            "failed_auth": 10,  # 10 次失败认证
            "suspicious_pattern": 5,  # 5 次可疑模式
            "abnormal_traffic": 1000  # 1000 次/分钟异常流量
        }
    
    def detect_anomaly(self, event: dict) -> Optional[Alert]:
        """检测异常"""
        
        # 1. 检测认证失败
        if event.get("type") == "auth_failure":
            if self._count_recent_failures(event["source"]) > self.thresholds["failed_auth"]:
                return Alert(
                    level="high",
                    type="brute_force",
                    source=event["source"],
                    message="Potential brute force attack detected"
                )
        
        # 2. 检测可疑模式
        if self._detect_suspicious_pattern(event):
            return Alert(
                level="medium",
                type="suspicious_activity",
                source=event.get("source"),
                message="Suspicious activity pattern detected"
            )
        
        return None

8. 安全审计

8.1 审计日志

8.1.1 审计事件

事件类型 描述 日志级别
AUTH_SUCCESS 认证成功 INFO
AUTH_FAILURE 认证失败 WARN
KEY_ROTATION 密钥轮换 INFO
CHANNEL_OPEN 通道开启 INFO
CHANNEL_CLOSE 通道关闭 INFO
RECEIPT_SIGN 收据签名 DEBUG
BUDGET_EXCEEDED 预算超限 WARN
SUSPICIOUS_ACTIVITY 可疑活动 WARN
SECURITY_VIOLATION 安全违规 ERROR

8.1.2 审计日志格式

{
  "timestamp": "2026-03-30T07:00:00.000Z",
  "event_type": "AUTH_FAILURE",
  "severity": "WARN",
  "actor": {
    "did": "did:nexa:abc123...",
    "ip": "192.168.1.100",
    "user_agent": "nexa-proxy/1.0.0"
  },
  "resource": {
    "type": "channel",
    "id": "channel-xyz"
  },
  "action": "open",
  "result": "failure",
  "reason": "insufficient_balance",
  "context": {
    "attempt": 3,
    "threshold": 3
  },
  "trace_id": "trace-123"
}

8.2 安全模块实现 (v0.2.0+)

Nexa-net v0.2.0 新增了完整的安全模块,提供审计日志、密钥轮换、速率限制和加密存储功能。

8.2.1 审计日志框架

use nexa_net::security::{AuditLogger, AuditEvent, AuthMethod};

// 创建审计日志器
let audit = AuditLogger::with_logging();

// 记录认证成功
audit.log_auth_success("did:nexa:user", AuthMethod::Signature, Some("192.168.1.1"))?;

// 记录密钥轮换
audit.log_key_rotated("key-1", 1, 2)?;

// 记录安全违规
audit.log_security_violation("brute_force", "Multiple failed login attempts", "high")?;

8.2.2 密钥轮换管理

use nexa_net::security::{KeyRotator, KeyRotationPolicy};

// 配置轮换策略
let policy = KeyRotationPolicy {
    rotation_interval_days: 90,      // 每 90 天轮换
    warning_period_days: 14,         // 提前 14 天警告
    max_key_age_days: 365,           // 最大密钥年龄
    auto_rotate: true,               // 自动轮换
    min_uses_before_rotation: 100,   // 最少使用次数
};

let rotator = KeyRotator::new(policy);

// 注册密钥
rotator.register_key("key-1", "signing").await?;

// 检查是否需要轮换
if rotator.needs_rotation("key-1").await? {
    rotator.mark_rotated("key-1").await?;
}

8.2.3 速率限制

use nexa_net::security::{RateLimiter, RateLimitConfig, RateLimitKey};

// 配置速率限制
let config = RateLimitConfig {
    requests_per_minute: 60,
    requests_per_hour: 1000,
    requests_per_day: 10000,
    burst_size: 10,
    enabled: true,
};

let limiter = RateLimiter::new(config);

// 检查请求
let key = RateLimitKey::Did("did:nexa:user".to_string());
match limiter.check(&key).await? {
    RateLimitResult::Allowed => { /* 处理请求 */ }
    RateLimitResult::Denied { reason, retry_after } => {
        println!("Rate limited: {}. Retry in {}s", reason, retry_after);
    }
}

8.2.4 加密密钥存储

use nexa_net::security::SecureKeyStorage;

// 创建加密存储
let encryption_key = [42u8; 32];  // 应从安全源加载
let storage = SecureKeyStorage::new(Some(encryption_key));

// 存储密钥
storage.store_key("key-1", "signing", key_data, Some("Main signing key")).await?;

// 获取密钥
let (data, metadata) = storage.get_key("key-1").await?.unwrap();

// 轮换密钥
let new_version = storage.rotate_key("key-1", new_key_data).await?;

8.3 安全检查清单

8.2.1 部署前检查

# security_checklist.yaml
pre_deployment:
  identity:
    - [ ] 私钥安全存储
    - [ ] DID 正确注册
    - [ ] 证书有效期检查
    
  network:
    - [ ] TLS 1.3 配置正确
    - [ ] 防火墙规则配置
    - [ ] 端口最小化开放
    
  application:
    - [ ] 输入验证实现
    - [ ] 输出编码实现
    - [ ] 错误处理安全
    
  monitoring:
    - [ ] 审计日志启用
    - [ ] 告警规则配置
    - [ ] 监控仪表板部署

8.2.2 运行时检查

class SecurityHealthCheck:
    """安全健康检查"""
    
    def run_checks(self) -> dict:
        """运行安全检查"""
        results = {}
        
        # 1. 检查 TLS 配置
        results["tls"] = self._check_tls_config()
        
        # 2. 检查密钥状态
        results["keys"] = self._check_key_status()
        
        # 3. 检查证书有效期
        results["certificates"] = self._check_certificates()
        
        # 4. 检查审计日志
        results["audit"] = self._check_audit_logs()
        
        # 5. 检查网络规则
        results["network"] = self._check_network_rules()
        
        return results
    
    def _check_tls_config(self) -> dict:
        """检查 TLS 配置"""
        return {
            "status": "healthy" if self._is_tls_13() else "warning",
            "version": self._get_tls_version(),
            "cipher_suites": self._get_cipher_suites()
        }

9. 安全最佳实践

9.1 开发安全

  1. 安全编码

    • 输入验证:所有外部输入必须验证
    • 输出编码:所有输出必须编码
    • 错误处理:不泄露敏感信息
    • 日志记录:记录安全相关事件
  2. 代码审查

    • 安全相关代码必须审查
    • 使用静态分析工具
    • 定期进行安全审计
  3. 依赖管理

    • 定期更新依赖
    • 使用依赖扫描工具
    • 避免已知漏洞

9.2 运维安全

  1. 访问控制

    • 最小权限原则
    • 定期审查权限
    • 多因素认证
  2. 监控告警

    • 实时监控安全事件
    • 及时响应告警
    • 定期分析日志
  3. 应急响应

    • 制定应急响应计划
    • 定期演练
    • 事后总结改进

9.3 用户安全

  1. 密钥管理

    • 安全存储私钥
    • 定期轮换密钥
    • 备份恢复机制
  2. 权限管理

    • 最小权限原则
    • 定期审查 VC
    • 及时撤销不需要的权限
  3. 预算控制

    • 设置合理预算
    • 监控使用情况
    • 及时调整配置

10. 相关文档

架构设计

运维相关

参考资料


附录: Phase 1-12 安全层重构变更

关键安全变更

Phase 变更 说明
Phase 5 XOR → AES-256-GCM src/security/secure_storage.rs 中密钥存储加密从 XOR 简单混淆升级为 AES-256-GCM 工业级加密,使用 96-bit nonce + 128-bit tag
Phase 5 SecurityManager 协调器 src/security/mod.rs 新增统一安全协调入口,整合所有安全子系统
Phase 7 审计日志集成 src/security/audit.rs 实现结构化安全事件记录(SecurityEventType + AuditEntry),支持可追溯性
Phase 7 密钥轮换机制 src/security/key_rotation.rs 实现自动/手动密钥轮换,支持轮换策略配置和轮换历史追踪
Phase 7 速率限制 middleware src/security/rate_limit.rs Token Bucket + Sliding Window 双重速率限制,保护 API 端点免受滥用
Phase 7 安全 middleware src/security/middleware.rs 请求验证/响应加密中间件层

从错误中学习

  1. XOR 加密不安全: Phase 1-4 中使用了 XOR 简单加密存储密钥,Phase 5 识别到这是严重安全缺陷,替换为 AES-256-GCM。教训:永远不要在生产代码中使用 XOR 作为加密手段。
  2. 两种 Did 类型冲突: 早期设计中存在 Did(String)Did { method, identifier } 两种类型,导致 API 不一致。Phase 3 统一为 Did(String) + 辅助方法。

There aren't any published security advisories