# 密钥管理器

## 概述

密钥管理器（KeyManager）负责存储和管理签名密钥。Server 和 Agent 都需要配置密钥管理器。

## Disk

将密钥存储在磁盘文件中。

### Server 配置

```hcl
plugins {
    KeyManager "disk" {
        plugin_data {
            # 密钥文件路径
            keys_path = "/opt/spire/data/server/keys.json"
        }
    }
}
```

### Agent 配置

```hcl
plugins {
    KeyManager "disk" {
        plugin_data {
            # 密钥目录
            directory = "/opt/spire/data/agent"
        }
    }
}
```

### 安全建议

:::{admonition} 注意
:class: warning

- 确保密钥文件权限为 `600`
- 密钥目录权限为 `700`
- 定期备份密钥文件
- 考虑使用加密文件系统
:::

## Memory

将密钥存储在内存中，重启后丢失。

### 配置

```hcl
plugins {
    KeyManager "memory" {
        plugin_data {}
    }
}
```

### 使用场景

- 开发和测试环境
- 无状态部署（如 Kubernetes，配合 `join_token`）
- 短期运行的 Agent

:::{admonition} 警告
:class: danger

不要在生产环境使用 `memory` 密钥管理器，除非可以接受重启后需要重新证明。
:::

## AWS KMS

使用 AWS Key Management Service 管理密钥。

### Server 配置

```hcl
plugins {
    KeyManager "aws_kms" {
        plugin_data {
            # AWS 区域
            region = "us-west-2"
            
            # KMS 密钥 ID（签名密钥）
            key_identifier = "alias/spire-server-signing-key"
            
            # 访问密钥（可选，推荐使用 IAM 角色）
            # access_key_id = "AKIAIOSFODNN7EXAMPLE"
            # secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
            
            # 使用 FIPS 端点
            # use_fips_endpoint = true
        }
    }
}
```

### IAM 策略

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:CreateKey",
                "kms:DescribeKey",
                "kms:GetPublicKey",
                "kms:Sign",
                "kms:ScheduleKeyDeletion"
            ],
            "Resource": "*"
        }
    ]
}
```

### 创建 KMS 密钥

```bash
# 创建非对称签名密钥
aws kms create-key \
    --key-usage SIGN_VERIFY \
    --key-spec ECC_NIST_P256 \
    --description "SPIRE Server Signing Key"

# 创建别名
aws kms create-alias \
    --alias-name alias/spire-server-signing-key \
    --target-key-id <key-id>
```

## GCP Cloud KMS

使用 Google Cloud KMS 管理密钥。

### Server 配置

```hcl
plugins {
    KeyManager "gcp_kms" {
        plugin_data {
            # 密钥环路径
            key_ring = "projects/my-project/locations/global/keyRings/spire-keyring"
            
            # 服务账户密钥文件（可选，推荐使用工作负载身份）
            # service_account_file = "/path/to/service-account.json"
        }
    }
}
```

### IAM 权限

需要以下权限：

- `cloudkms.cryptoKeys.create`
- `cloudkms.cryptoKeys.get`
- `cloudkms.cryptoKeyVersions.create`
- `cloudkms.cryptoKeyVersions.destroy`
- `cloudkms.cryptoKeyVersions.get`
- `cloudkms.cryptoKeyVersions.useToSign`
- `cloudkms.cryptoKeyVersions.viewPublicKey`

### 创建密钥环

```bash
# 创建密钥环
gcloud kms keyrings create spire-keyring \
    --location=global

# SPIRE 会自动在密钥环中创建密钥
```

## Azure Key Vault

使用 Azure Key Vault 管理密钥。

### Server 配置

```hcl
plugins {
    KeyManager "azure_keyvault" {
        plugin_data {
            # Key Vault URI
            key_vault_uri = "https://my-vault.vault.azure.net/"
            
            # 租户 ID（可选，使用托管身份时）
            # tenant_id = "..."
            
            # 客户端 ID（可选）
            # client_id = "..."
            
            # 客户端密钥（可选）
            # client_secret = "..."
        }
    }
}
```

### 权限配置

Key Vault 访问策略需要以下权限：

- Keys: Get, List, Create, Delete, Sign, Verify

## 密钥轮换

### 轮换流程

```{mermaid}
sequenceDiagram
    participant CM as CA 管理器
    participant KM as 密钥管理器
    participant DS as 数据存储
    
    Note over CM: TTL 到达阈值
    CM->>KM: 生成新密钥
    KM-->>CM: 新密钥就绪
    CM->>DS: 保存新密钥状态
    Note over CM: 开始使用新密钥签名
    Note over CM: 旧密钥继续验证
    Note over CM: 旧密钥过期后删除
```

### 配置轮换参数

```hcl
server {
    # CA TTL（影响轮换频率）
    ca_ttl = "24h"
    
    # SVID TTL
    default_x509_svid_ttl = "1h"
}
```

## 备份和恢复

### Disk KeyManager 备份

```bash
# 备份密钥
cp /opt/spire/data/server/keys.json /backup/keys.json.$(date +%Y%m%d)

# 恢复密钥
cp /backup/keys.json.20260203 /opt/spire/data/server/keys.json
chmod 600 /opt/spire/data/server/keys.json
```

### KMS 备份

云 KMS 服务通常提供内置的备份和恢复机制：

- **AWS KMS**: 自动备份，可创建密钥副本
- **GCP Cloud KMS**: 支持密钥版本恢复
- **Azure Key Vault**: 支持软删除和恢复

## 选择建议

| 环境 | 推荐 KeyManager |
|------|-----------------|
| 开发/测试 | `disk` 或 `memory` |
| 生产（AWS）| `aws_kms` |
| 生产（GCP）| `gcp_kms` |
| 生产（Azure）| `azure_keyvault` |
| 生产（其他）| `disk` + 加密存储 |

:::{admonition} 最佳实践
:class: tip

1. **生产使用 HSM**: 优先使用云 KMS 服务
2. **定期轮换**: 配置适当的 CA TTL
3. **备份密钥**: 定期备份并测试恢复
4. **监控密钥使用**: 设置告警
5. **最小权限**: IAM 策略最小化
:::