密钥管理最佳实践#

/**
 * 密钥元数据模型
 */
public class KeyMetadata {
    
    private String keyId;           // 全局唯一标识
    private String keyType;         // 密钥类型
    private String algorithm;       // 算法（RSA-2048, AES-256 等）
    private KeyUsage usage;        // 用途（ENCRYPT/DECRYPT/SIGN）
    private int keyLength;         // 密钥长度
    private String protectionLevel; // 保护级别（HARDWARE/SOFTWARE）
    private KeyState state;        // 状态（CREATED/ACTIVE/DELETED）
    private Instant createdAt;      // 创建时间
    private Instant rotatedAt;      // 最近轮转时间
    private Instant expiresAt;      // 过期时间（可选）
    
    // 访问控制
    private List<String> allowedPrincipals;   // 允许使用的主体
    private List<String> allowedServices;      // 允许使用的服务
    private String region;                    // 所属区域
    private String environment;               // 环境（prod/staging/dev）
    
    // 审计
    private String createdBy;        // 创建者
    private String rotationPolicy;    // 轮转策略
    private int rotationPeriodDays;  // 轮转周期（天）
}

@Service
@Slf4j
public class KeyLifecycleManager {
    
    @Autowired
    private KeyRepository keyRepository;
    
    @Autowired
    private AuditService auditService;
    
    @Autowired
    private NotificationService notificationService;
    
    /**
     * 创建新密钥
     */
    @Transactional
    public Key createKey(KeyCreateRequest request) {
        
        // 1. 验证请求
        validateCreateRequest(request);
        
        // 2. 检查配额
        checkKeyQuota(request.getOwner(), request.getKeyType());
        
        // 3. 调用 HSM/KMS 生成密钥
        KeyMaterial keyMaterial = kmsClient.generateKey(
            KeyGenerationRequest.builder()
                .algorithm(request.getAlgorithm())
                .length(request.getKeyLength())
                .protectionLevel(request.getProtectionLevel())
                .build()
        );
        
        // 4. 创建密钥元数据
        Key key = Key.builder()
            .keyId(UUID.randomUUID().toString())
            .keyType(request.getKeyType())
            .algorithm(request.getAlgorithm())
            .state(KeyState.PRE_ACTIVE)
            .createdAt(Instant.now())
            .createdBy(request.getRequesterPrincipal())
            .rotationPolicy(request.getRotationPolicy())
            .rotationPeriodDays(request.getRotationPeriodDays())
            .build();
        
        // 5. 存储密钥元数据（不存储密钥材料）
        key = keyRepository.save(key);
        
        // 6. 将密钥材料存入 HSM/KMS
        kmsClient.importKeyMaterial(key.getKeyId(), keyMaterial);
        
        // 7. 激活密钥
        key.setState(KeyState.ACTIVE);
        key = keyRepository.save(key);
        
        // 8. 审计日志
        auditService.logKeyOperation(
            KeyOperation.CREATE, key.getKeyId(), request.getRequesterPrincipal());
        
        // 9. 通知
        notificationService.notifyKeyCreated(key);
        
        return key;
    }
    
    /**
     * 密钥轮转
     */
    @Transactional
    public KeyRotationResult rotateKey(String keyId) {
        
        Key currentKey = keyRepository.findByKeyId(keyId)
            .orElseThrow(() -> new KeyNotFoundException(keyId));
        
        // 1. 检查是否允许轮转
        if (currentKey.getState() != KeyState.ACTIVE) {
            throw new KeyStateException("密钥必须处于 ACTIVE 状态才能轮转");
        }
        
        // 2. 创建新版本密钥
        Key newKey = createKeyVersion(currentKey);
        
        // 3. 保留旧版本（用于解密历史数据）
        currentKey.setState(KeyState.PENDING_DELETION);
        currentKey.setReplacementKeyId(newKey.getKeyId());
        keyRepository.save(currentKey);
        
        // 4. 记录轮转
        auditService.logKeyOperation(
            KeyOperation.ROTATE, keyId, "SYSTEM");
        
        return new KeyRotationResult(currentKey, newKey);
    }
    
    /**
     * 密钥删除（软删除）
     */
    @Transactional
    public void scheduleKeyDeletion(String keyId, int pendingPeriodDays) {
        
        Key key = keyRepository.findByKeyId(keyId)
            .orElseThrow(() -> new KeyNotFoundException(keyId));
        
        // 1. 检查是否可以删除
        validateDeletion(key);
        
        // 2. 设置删除状态
        key.setState(KeyState.PENDING_DELETION);
        key.setDeletionScheduledAt(Instant.now());
        key.setDeletionEffectiveAt(
            Instant.now().plus(Duration.ofDays(pendingPeriodDays)));
        keyRepository.save(key);
        
        // 3. 通知相关方
        notificationService.notifyKeyDeletionScheduled(key, pendingPeriodDays);
        
        // 4. 安排定时任务
        scheduler.scheduleKeyDeletion(keyId, pendingPeriodDays);
        
        // 5. 审计日志
        auditService.logKeyOperation(
            KeyOperation.SCHEDULE_DELETE, keyId, getCurrentPrincipal());
    }
    
    /**
     * 密钥恢复
     */
    @Transactional
    public void recoverKey(String keyId) {
        
        Key key = keyRepository.findByKeyId(keyId)
            .orElseThrow(() -> new KeyNotFoundException(keyId));
        
        if (key.getState() != KeyState.PENDING_DELETION) {
            throw new KeyStateException("只能恢复处于 PENDING_DELETION 状态的密钥");
        }
        
        if (Instant.now().isAfter(key.getDeletionEffectiveAt())) {
            throw new KeyStateException("密钥已过期，无法恢复");
        }
        
        // 恢复密钥状态
        key.setState(KeyState.ACTIVE);
        key.setDeletionScheduledAt(null);
        key.setDeletionEffectiveAt(null);
        keyRepository.save(key);
        
        // 取消删除任务
        scheduler.cancelKeyDeletion(keyId);
        
        auditService.logKeyOperation(
            KeyOperation.RECOVER, keyId, getCurrentPrincipal());
    }
}

public class KeyIsolationStrategy {
    
    /**
     * 基于数据的隔离策略
     */
    public enum IsolationDimension {
        // 按数据类型隔离
        DATA_TYPE,      // PII、财务、健康数据分开
        
        // 按环境隔离
        ENVIRONMENT,     // dev/staging/prod
        
        // 按服务隔离
        SERVICE,         // 每个微服务独立密钥
        
        // 按租户隔离
        TENANT,          // 多租户场景下按租户隔离
        
        // 按区域隔离
        REGION          // 不同地理区域
    }
    
    /**
     * 推荐隔离策略
     */
    public static Map<IsolationDimension, String> getRecommendedIsolation(
            String useCase) {
        
        return switch (useCase) {
            case "payment" -> Map.of(
                IsolationDimension.DATA_TYPE, "FINANCIAL",
                IsolationDimension.ENVIRONMENT, "prod",
                IsolationDimension.SERVICE, "payment-service"
            );
            
            case "pii-data" -> Map.of(
                IsolationDimension.DATA_TYPE, "PII",
                IsolationDimension.ENVIRONMENT, "prod",
                IsolationDimension.TENANT, "dynamic"
            );
            
            case "general-data" -> Map.of(
                IsolationDimension.ENVIRONMENT, "dynamic",
                IsolationDimension.SERVICE, "dynamic"
            );
            
            default -> Map.of(
                IsolationDimension.ENVIRONMENT, "dynamic"
            );
        };
    }
}

/**
 * AWS KMS Java SDK
 */
public class AwsKmsExample {
    
    private final AWSKMS kms = AWSKMSClientBuilder.defaultClient();
    
    // 生成 CMK
    public String createKey() {
        CreateKeyRequest request = CreateKeyRequest.builder()
            .description("Database encryption key")
            .keyUsage(KeyUsageType.ENCRYPT_DECRYPT)
            .keySpec(KeySpec.SYMMETRIC_DEFAULT)
            .enableKeyRotation(true)
            .build();
        
        return kms.createKey(request).keyMetadata().keyId();
    }
    
    // 加密
    public byte[] encrypt(String keyId, byte[] plaintext) {
        EncryptRequest request = EncryptRequest.builder()
            .keyId(keyId)
            .plaintext(ByteBuffer.wrap(plaintext))
            .build();
        
        return kms.encrypt(request).ciphertextBlob().array();
    }
    
    // 解密
    public byte[] decrypt(String keyId, byte[] ciphertext) {
        DecryptRequest request = DecryptRequest.builder()
            .keyId(keyId)
            .ciphertextBlob(ByteBuffer.wrap(ciphertext))
            .build();
        
        return kms.decrypt(request).plaintext().array();
    }
}

/**
 * Azure Key Vault Java SDK
 */
public class AzureKeyVaultExample {
    
    private final SecretClient secretClient = new SecretClientBuilder()
        .vaultUrl("https://myvault.vault.azure.net/")
        .credential(new DefaultAzureCredential())
        .buildClient();
    
    // 设置密钥
    public void setKey(String keyName, byte[] keyMaterial) {
        KeyVaultKey key = new KeyVaultKey(keyName, 
            Base64.getEncoder().encodeToString(keyMaterial));
        secretClient.setKey(key);
    }
    
    // 获取密钥
    public byte[] getKey(String keyName) {
        KeyVaultKey key = secretClient.getKey(keyName);
        return Base64.getDecoder().decode(key.getKeyMaterial());
    }
}

/**
 * GCP Cloud KMS Java SDK
 */
public class GcpKmsExample {
    
    private final KeyManagementServiceClient kms = 
        KeyManagementServiceClient.create();
    
    // 加密
    public ByteString encrypt(String keyRingName, String cryptoKeyName, 
            ByteString plaintext) {
        
        CryptoKeyName name = CryptoKeyName.of("[PROJECT]", "[LOCATION]", 
            keyRingName, cryptoKeyName);
        
        EncryptRequest request = EncryptRequest.newBuilder()
            .setName(name.toString())
            .setPlaintext(plaintext)
            .build();
        
        return kms.encrypt(request).getCiphertext();
    }
}

@Service
@Slf4j
public class EnvelopeEncryptionService {
    
    private final AwsKmsClient kmsClient;
    private final SecretGenerator secretGenerator;
    
    /**
     * 加密数据
     */
    public EncryptedData encrypt(byte[] plaintext) throws Exception {
        
        // 1. 生成随机数据密钥
        byte[] dek = secretGenerator.generateSymmetricKey(256);
        
        // 2. 用 DEK 加密数据
        byte[] encryptedData = encryptWithDek(plaintext, dek);
        
        // 3. 用 CMK 加密 DEK
        EncryptedDek encryptedDek = kmsClient.encrypt(
            "customer-master-key-id",
            dek
        );
        
        // 4. 清除内存中的明文 DEK
        Arrays.fill(dek, (byte) 0);
        
        // 5. 返回加密数据和加密的 DEK
        return new EncryptedData(
            encryptedData,
            encryptedDek.getCiphertext(),
            encryptedDek.getKeyId()
        );
    }
    
    /**
     * 解密数据
     */
    public byte[] decrypt(EncryptedData encryptedData) throws Exception {
        
        // 1. 用 CMK 解密 DEK
        byte[] dek = kmsClient.decrypt(
            encryptedData.getKeyId(),
            encryptedData.getEncryptedDek()
        );
        
        // 2. 用 DEK 解密数据
        byte[] plaintext = decryptWithDek(
            encryptedData.getCiphertext(),
            dek
        );
        
        // 3. 清除内存中的 DEK
        Arrays.fill(dek, (byte) 0);
        
        return plaintext;
    }
    
    private byte[] encryptWithDek(byte[] data, byte[] dek) throws Exception {
        // 使用 AES-GCM 加密
        SecretKey key = new SecretKeySpec(dek, "AES");
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        GCMParameterSpec spec = new GCMParameterSpec(128, new byte[12]);
        cipher.init(Cipher.ENCRYPT_MODE, key, spec);
        return cipher.doFinal(data);
    }
}

@Service
@Slf4j
public class KeyPermissionManager {
    
    /**
     * 授予密钥使用权限
     */
    public void grantKeyUsage(String keyId, String principal, 
            KeyPermission permission) {
        
        // 1. 创建 Grant
        Grant grant = Grant.builder()
            .keyId(keyId)
            .granteePrincipal(principal)
            .operations(permission.getOperations())
            .constraints(GrantConstraints.builder()
                .encryptionContextSubset(
                    Map.of("department", permission.getDepartment()))
                .build())
            .build();
        
        // 2. 提交 Grant
        String grantToken = kmsClient.createGrant(grant);
        
        // 3. 记录授权
        auditService.logGrantCreated(keyId, principal, permission);
    }
    
    /**
     * 权限级别定义
     */
    public enum KeyPermission {
        
        ENCRYPT_DECRYPT(
            "encrypt", "decrypt", "ReEncrypt", 
            "DescribeKey", "GenerateDataKey"
        ),
        
        SIGN_VERIFY(
            "Sign", "Verify",
            "DescribeKey"
        ),
        
        KEY_ADMIN(
            "CreateKey", "DeleteKey", "UpdateKey",
            "GetKeyPolicy", "PutKeyPolicy",
            "DescribeKey", "ListKeys"
        ),
        
        KEY_USER(
            "Encrypt", "Decrypt", "ReEncrypt",
            "GenerateDataKey", "GenerateDataKeyWithoutPlaintext",
            "DescribeKey", "CreateGrant"
        );
        
        private final Set<String> operations;
        
        KeyPermission(String... ops) {
            this.operations = Set.of(ops);
        }
        
        public Set<String> getOperations() {
            return operations;
        }
    }
}

@Service
@Slf4j
public class KeyAuditService {
    
    /**
     * 记录密钥操作
     */
    public void logKeyOperation(KeyOperation operation, String keyId, 
            String performedBy) {
        
        KeyAuditEvent event = KeyAuditEvent.builder()
            .eventId(UUID.randomUUID().toString())
            .timestamp(Instant.now())
            .operation(operation)
            .keyId(keyId)
            .performedBy(performedBy)
            .ipAddress(getCurrentIpAddress())
            .userAgent(getCurrentUserAgent())
            .success(true)
            .build();
        
        // 异步写入审计日志
        auditLogPublisher.publish(event);
    }
    
    /**
     * 查询密钥操作历史
     */
    public Page<KeyAuditEvent> getKeyHistory(String keyId, 
            Instant from, Instant to, Pageable pageable) {
        
        return auditRepository.findByKeyIdAndTimestampBetween(
            keyId, from, to, pageable);
    }
    
    /**
     * 异常访问检测
     */
    public List<SecurityAlert> detectAnomalies(String keyId) {
        List<SecurityAlert> alerts = new ArrayList<>();
        
        // 1. 异常时间访问
        List<KeyAuditEvent> events = auditRepository
            .findRecentEvents(keyId, Duration.ofHours(24));
        
        if (hasUnusualTimeAccess(events)) {
            alerts.add(SecurityAlert.builder()
                .type(AlertType.UNUSUAL_TIME_ACCESS)
                .keyId(keyId)
                .description("检测到非工作时间的密钥访问")
                .severity(Severity.HIGH)
                .build());
        }
        
        // 2. 异常地点访问
        if (hasUnusualLocationAccess(events)) {
            alerts.add(SecurityAlert.builder()
                .type(AlertType.UNUSUAL_LOCATION_ACCESS)
                .keyId(keyId)
                .description("检测到异地密钥访问")
                .severity(Severity.HIGH)
                .build());
        }
        
        // 3. 批量访问
        if (hasBulkAccess(events)) {
            alerts.add(SecurityAlert.builder()
                .type(AlertType.BULK_ACCESS)
                .keyId(keyId)
                .description("检测到异常的批量密钥操作")
                .severity(Severity.MEDIUM)
                .build());
        }
        
        return alerts;
    }
}