Back to Details

aws-sdk-java-v2-kms

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AWS SDK for Java 2.x - AWS KMS (Key Management Service)

AWS SDK for Java 2.x - AWS KMS (Key Management Service)

Overview

概述

This skill provides comprehensive patterns for AWS Key Management Service (KMS) using AWS SDK for Java 2.x. Focus on implementing secure encryption solutions with proper key management, envelope encryption, and Spring Boot integration patterns.
本技能提供了使用AWS SDK for Java 2.x操作AWS Key Management Service (KMS) 的全面实践模式，重点在于实现具备完善密钥管理、信封加密及Spring Boot集成的安全加密解决方案。

When to Use

适用场景

Use this skill when:
  • Creating and managing symmetric encryption keys for data protection
  • Implementing client-side encryption and envelope encryption patterns
  • Generating data keys for local data encryption with KMS-managed keys
  • Setting up digital signatures and verification with asymmetric keys
  • Integrating encryption capabilities into Spring Boot applications
  • Implementing secure key lifecycle management
  • Setting up key rotation policies and access controls
在以下场景中可使用本技能：
  • 创建和管理用于数据保护的对称加密密钥
  • 实现客户端加密和信封加密模式
  • 生成数据密钥，使用KMS托管密钥对本地数据进行加密
  • 基于非对称密钥设置数字签名与验证功能
  • 在Spring Boot应用中集成加密能力
  • 实现安全的密钥生命周期管理
  • 设置密钥轮换策略与访问控制

Dependencies

依赖

Maven

Maven

xml
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>kms</artifactId>
</dependency>
xml
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>kms</artifactId>
</dependency>

Gradle

Gradle

groovy
implementation 'software.amazon.awssdk:kms:2.x.x'
groovy
implementation 'software.amazon.awssdk:kms:2.x.x'

Client Setup

客户端配置

Basic Synchronous Client

基础同步客户端

java
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.kms.KmsClient;

KmsClient kmsClient = KmsClient.builder()
    .region(Region.US_EAST_1)
    .build();
java
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.kms.KmsClient;

KmsClient kmsClient = KmsClient.builder()
    .region(Region.US_EAST_1)
    .build();

Basic Asynchronous Client

基础异步客户端

java
import software.amazon.awssdk.services.kms.KmsAsyncClient;

KmsAsyncClient kmsAsyncClient = KmsAsyncClient.builder()
    .region(Region.US_EAST_1)
    .build();
java
import software.amazon.awssdk.services.kms.KmsAsyncClient;

KmsAsyncClient kmsAsyncClient = KmsAsyncClient.builder()
    .region(Region.US_EAST_1)
    .build();

Advanced Client Configuration

高级客户端配置

java
KmsClient kmsClient = KmsClient.builder()
    .region(Region.of(System.getenv("AWS_REGION")))
    .credentialsProvider(DefaultCredentialsProvider.create())
    .overrideConfiguration(c -> c.retryPolicy(RetryPolicy.builder()
        .numRetries(3)
        .build()))
    .build();
java
KmsClient kmsClient = KmsClient.builder()
    .region(Region.of(System.getenv("AWS_REGION")))
    .credentialsProvider(DefaultCredentialsProvider.create())
    .overrideConfiguration(c -> c.retryPolicy(RetryPolicy.builder()
        .numRetries(3)
        .build()))
    .build();

Basic Key Management

基础密钥管理

Create Encryption Key

创建加密密钥

java
public String createEncryptionKey(KmsClient kmsClient, String description) {
    CreateKeyRequest request = CreateKeyRequest.builder()
        .description(description)
        .keyUsage(KeyUsageType.ENCRYPT_DECRYPT)
        .build();

    CreateKeyResponse response = kmsClient.createKey(request);
    return response.keyMetadata().keyId();
}
java
public String createEncryptionKey(KmsClient kmsClient, String description) {
    CreateKeyRequest request = CreateKeyRequest.builder()
        .description(description)
        .keyUsage(KeyUsageType.ENCRYPT_DECRYPT)
        .build();

    CreateKeyResponse response = kmsClient.createKey(request);
    return response.keyMetadata().keyId();
}

Describe Key

描述密钥

java
public KeyMetadata getKeyMetadata(KmsClient kmsClient, String keyId) {
    DescribeKeyRequest request = DescribeKeyRequest.builder()
        .keyId(keyId)
        .build();

    return kmsClient.describeKey(request).keyMetadata();
}
java
public KeyMetadata getKeyMetadata(KmsClient kmsClient, String keyId) {
    DescribeKeyRequest request = DescribeKeyRequest.builder()
        .keyId(keyId)
        .build();

    return kmsClient.describeKey(request).keyMetadata();
}

Enable/Disable Key

启用/禁用密钥

java
public void toggleKeyState(KmsClient kmsClient, String keyId, boolean enable) {
    if (enable) {
        kmsClient.enableKey(EnableKeyRequest.builder().keyId(keyId).build());
    } else {
        kmsClient.disableKey(DisableKeyRequest.builder().keyId(keyId).build());
    }
}
java
public void toggleKeyState(KmsClient kmsClient, String keyId, boolean enable) {
    if (enable) {
        kmsClient.enableKey(EnableKeyRequest.builder().keyId(keyId).build());
    } else {
        kmsClient.disableKey(DisableKeyRequest.builder().keyId(keyId).build());
    }
}

Basic Encryption and Decryption

基础加密与解密

Encrypt Data

加密数据

java
public String encryptData(KmsClient kmsClient, String keyId, String plaintext) {
    SdkBytes plaintextBytes = SdkBytes.fromString(plaintext, StandardCharsets.UTF_8);

    EncryptRequest request = EncryptRequest.builder()
        .keyId(keyId)
        .plaintext(plaintextBytes)
        .build();

    EncryptResponse response = kmsClient.encrypt(request);
    return Base64.getEncoder().encodeToString(
        response.ciphertextBlob().asByteArray());
}
java
public String encryptData(KmsClient kmsClient, String keyId, String plaintext) {
    SdkBytes plaintextBytes = SdkBytes.fromString(plaintext, StandardCharsets.UTF_8);

    EncryptRequest request = EncryptRequest.builder()
        .keyId(keyId)
        .plaintext(plaintextBytes)
        .build();

    EncryptResponse response = kmsClient.encrypt(request);
    return Base64.getEncoder().encodeToString(
        response.ciphertextBlob().asByteArray());
}

Decrypt Data

解密数据

java
public String decryptData(KmsClient kmsClient, String ciphertextBase64) {
    byte[] ciphertext = Base64.getDecoder().decode(ciphertextBase64);
    SdkBytes ciphertextBytes = SdkBytes.fromByteArray(ciphertext);

    DecryptRequest request = DecryptRequest.builder()
        .ciphertextBlob(ciphertextBytes)
        .build();

    DecryptResponse response = kmsClient.decrypt(request);
    return response.plaintext().asString(StandardCharsets.UTF_8);
}
java
public String decryptData(KmsClient kmsClient, String ciphertextBase64) {
    byte[] ciphertext = Base64.getDecoder().decode(ciphertextBase64);
    SdkBytes ciphertextBytes = SdkBytes.fromByteArray(ciphertext);

    DecryptRequest request = DecryptRequest.builder()
        .ciphertextBlob(ciphertextBytes)
        .build();

    DecryptResponse response = kmsClient.decrypt(request);
    return response.plaintext().asString(StandardCharsets.UTF_8);
}

Envelope Encryption Pattern

信封加密模式

Generate and Use Data Key

生成并使用数据密钥

java
public DataKeyResult encryptWithEnvelope(KmsClient kmsClient, String masterKeyId, byte[] data) {
    // Generate data key
    GenerateDataKeyRequest keyRequest = GenerateDataKeyRequest.builder()
        .keyId(masterKeyId)
        .keySpec(DataKeySpec.AES_256)
        .build();

    GenerateDataKeyResponse keyResponse = kmsClient.generateDataKey(keyRequest);

    // Encrypt data with data key
    byte[] encryptedData = encryptWithAES(data,
        keyResponse.plaintext().asByteArray());

    // Clear plaintext key from memory
    Arrays.fill(keyResponse.plaintext().asByteArray(), (byte) 0);

    return new DataKeyResult(
        encryptedData,
        keyResponse.ciphertextBlob().asByteArray());
}

public byte[] decryptWithEnvelope(KmsClient kmsClient,
                                  DataKeyResult encryptedEnvelope) {
    // Decrypt data key
    DecryptRequest keyDecryptRequest = DecryptRequest.builder()
        .ciphertextBlob(SdkBytes.fromByteArray(
            encryptedEnvelope.encryptedKey()))
        .build();

    DecryptResponse keyDecryptResponse = kmsClient.decrypt(keyDecryptRequest);

    // Decrypt data with decrypted key
    byte[] decryptedData = decryptWithAES(
        encryptedEnvelope.encryptedData(),
        keyDecryptResponse.plaintext().asByteArray());

    // Clear plaintext key from memory
    Arrays.fill(keyDecryptResponse.plaintext().asByteArray(), (byte) 0);

    return decryptedData;
}
java
public DataKeyResult encryptWithEnvelope(KmsClient kmsClient, String masterKeyId, byte[] data) {
    // Generate data key
    GenerateDataKeyRequest keyRequest = GenerateDataKeyRequest.builder()
        .keyId(masterKeyId)
        .keySpec(DataKeySpec.AES_256)
        .build();

    GenerateDataKeyResponse keyResponse = kmsClient.generateDataKey(keyRequest);

    // Encrypt data with data key
    byte[] encryptedData = encryptWithAES(data,
        keyResponse.plaintext().asByteArray());

    // Clear plaintext key from memory
    Arrays.fill(keyResponse.plaintext().asByteArray(), (byte) 0);

    return new DataKeyResult(
        encryptedData,
        keyResponse.ciphertextBlob().asByteArray());
}

public byte[] decryptWithEnvelope(KmsClient kmsClient,
                                  DataKeyResult encryptedEnvelope) {
    // Decrypt data key
    DecryptRequest keyDecryptRequest = DecryptRequest.builder()
        .ciphertextBlob(SdkBytes.fromByteArray(
            encryptedEnvelope.encryptedKey()))
        .build();

    DecryptResponse keyDecryptResponse = kmsClient.decrypt(keyDecryptRequest);

    // Decrypt data with decrypted key
    byte[] decryptedData = decryptWithAES(
        encryptedEnvelope.encryptedData(),
        keyDecryptResponse.plaintext().asByteArray());

    // Clear plaintext key from memory
    Arrays.fill(keyDecryptResponse.plaintext().asByteArray(), (byte) 0);

    return decryptedData;
}

Digital Signatures

数字签名

Create Signing Key and Sign Data

创建签名密钥并签署数据

java
public String createAndSignData(KmsClient kmsClient, String description, String message) {
    // Create signing key
    CreateKeyRequest keyRequest = CreateKeyRequest.builder()
        .description(description)
        .keySpec(KeySpec.RSA_2048)
        .keyUsage(KeyUsageType.SIGN_VERIFY)
        .build();

    CreateKeyResponse keyResponse = kmsClient.createKey(keyRequest);
    String keyId = keyResponse.keyMetadata().keyId();

    // Sign data
    SignRequest signRequest = SignRequest.builder()
        .keyId(keyId)
        .message(SdkBytes.fromString(message, StandardCharsets.UTF_8))
        .signingAlgorithm(SigningAlgorithmSpec.RSASSA_PSS_SHA_256)
        .build();

    SignResponse signResponse = kmsClient.sign(signRequest);
    return Base64.getEncoder().encodeToString(
        signResponse.signature().asByteArray());
}
java
public String createAndSignData(KmsClient kmsClient, String description, String message) {
    // Create signing key
    CreateKeyRequest keyRequest = CreateKeyRequest.builder()
        .description(description)
        .keySpec(KeySpec.RSA_2048)
        .keyUsage(KeyUsageType.SIGN_VERIFY)
        .build();

    CreateKeyResponse keyResponse = kmsClient.createKey(keyRequest);
    String keyId = keyResponse.keyMetadata().keyId();

    // Sign data
    SignRequest signRequest = SignRequest.builder()
        .keyId(keyId)
        .message(SdkBytes.fromString(message, StandardCharsets.UTF_8))
        .signingAlgorithm(SigningAlgorithmSpec.RSASSA_PSS_SHA_256)
        .build();

    SignResponse signResponse = kmsClient.sign(signRequest);
    return Base64.getEncoder().encodeToString(
        signResponse.signature().asByteArray());
}

Verify Signature

验证签名

java
public boolean verifySignature(KmsClient kmsClient,
                             String keyId,
                             String message,
                             String signatureBase64) {
    byte[] signature = Base64.getDecoder().decode(signatureBase64);

    VerifyRequest verifyRequest = VerifyRequest.builder()
        .keyId(keyId)
        .message(SdkBytes.fromString(message, StandardCharsets.UTF_8))
        .signature(SdkBytes.fromByteArray(signature))
        .signingAlgorithm(SigningAlgorithmSpec.RSASSA_PSS_SHA_256)
        .build();

    VerifyResponse verifyResponse = kmsClient.verify(verifyRequest);
    return verifyResponse.signatureValid();
}
java
public boolean verifySignature(KmsClient kmsClient,
                             String keyId,
                             String message,
                             String signatureBase64) {
    byte[] signature = Base64.getDecoder().decode(signatureBase64);

    VerifyRequest verifyRequest = VerifyRequest.builder()
        .keyId(keyId)
        .message(SdkBytes.fromString(message, StandardCharsets.UTF_8))
        .signature(SdkBytes.fromByteArray(signature))
        .signingAlgorithm(SigningAlgorithmSpec.RSASSA_PSS_SHA_256)
        .build();

    VerifyResponse verifyResponse = kmsClient.verify(verifyRequest);
    return verifyResponse.signatureValid();
}

Spring Boot Integration

Spring Boot集成

Configuration Class

配置类

java
@Configuration
public class KmsConfiguration {

    @Bean
    public KmsClient kmsClient() {
        return KmsClient.builder()
            .region(Region.US_EAST_1)
            .build();
    }

    @Bean
    public KmsAsyncClient kmsAsyncClient() {
        return KmsAsyncClient.builder()
            .region(Region.US_EAST_1)
            .build();
    }
}
java
@Configuration
public class KmsConfiguration {

    @Bean
    public KmsClient kmsClient() {
        return KmsClient.builder()
            .region(Region.US_EAST_1)
            .build();
    }

    @Bean
    public KmsAsyncClient kmsAsyncClient() {
        return KmsAsyncClient.builder()
            .region(Region.US_EAST_1)
            .build();
    }
}

Encryption Service

加密服务

java
@Service
@RequiredArgsConstructor
public class KmsEncryptionService {

    private final KmsClient kmsClient;

    @Value("${kms.encryption-key-id}")
    private String keyId;

    public String encrypt(String plaintext) {
        try {
            EncryptRequest request = EncryptRequest.builder()
                .keyId(keyId)
                .plaintext(SdkBytes.fromString(plaintext, StandardCharsets.UTF_8))
                .build();

            EncryptResponse response = kmsClient.encrypt(request);
            return Base64.getEncoder().encodeToString(
                response.ciphertextBlob().asByteArray());

        } catch (KmsException e) {
            throw new RuntimeException("Encryption failed", e);
        }
    }

    public String decrypt(String ciphertextBase64) {
        try {
            byte[] ciphertext = Base64.getDecoder().decode(ciphertextBase64);

            DecryptRequest request = DecryptRequest.builder()
                .ciphertextBlob(SdkBytes.fromByteArray(ciphertext))
                .build();

            DecryptResponse response = kmsClient.decrypt(request);
            return response.plaintext().asString(StandardCharsets.UTF_8);

        } catch (KmsException e) {
            throw new RuntimeException("Decryption failed", e);
        }
    }
}
java
@Service
@RequiredArgsConstructor
public class KmsEncryptionService {

    private final KmsClient kmsClient;

    @Value("${kms.encryption-key-id}")
    private String keyId;

    public String encrypt(String plaintext) {
        try {
            EncryptRequest request = EncryptRequest.builder()
                .keyId(keyId)
                .plaintext(SdkBytes.fromString(plaintext, StandardCharsets.UTF_8))
                .build();

            EncryptResponse response = kmsClient.encrypt(request);
            return Base64.getEncoder().encodeToString(
                response.ciphertextBlob().asByteArray());

        } catch (KmsException e) {
            throw new RuntimeException("Encryption failed", e);
        }
    }

    public String decrypt(String ciphertextBase64) {
        try {
            byte[] ciphertext = Base64.getDecoder().decode(ciphertextBase64);

            DecryptRequest request = DecryptRequest.builder()
                .ciphertextBlob(SdkBytes.fromByteArray(ciphertext))
                .build();

            DecryptResponse response = kmsClient.decrypt(request);
            return response.plaintext().asString(StandardCharsets.UTF_8);

        } catch (KmsException e) {
            throw new RuntimeException("Decryption failed", e);
        }
    }
}

Examples

示例

Basic Encryption Example

基础加密示例

java
public class BasicEncryptionExample {
    public static void main(String[] args) {
        KmsClient kmsClient = KmsClient.builder()
            .region(Region.US_EAST_1)
            .build();

        // Create key
        String keyId = createEncryptionKey(kmsClient, "Example encryption key");
        System.out.println("Created key: " + keyId);

        // Encrypt and decrypt
        String plaintext = "Hello, World!";
        String encrypted = encryptData(kmsClient, keyId, plaintext);
        String decrypted = decryptData(kmsClient, encrypted);

        System.out.println("Original: " + plaintext);
        System.out.println("Decrypted: " + decrypted);
    }
}
java
public class BasicEncryptionExample {
    public static void main(String[] args) {
        KmsClient kmsClient = KmsClient.builder()
            .region(Region.US_EAST_1)
            .build();

        // Create key
        String keyId = createEncryptionKey(kmsClient, "Example encryption key");
        System.out.println("Created key: " + keyId);

        // Encrypt and decrypt
        String plaintext = "Hello, World!";
        String encrypted = encryptData(kmsClient, keyId, plaintext);
        String decrypted = decryptData(kmsClient, encrypted);

        System.out.println("Original: " + plaintext);
        System.out.println("Decrypted: " + decrypted);
    }
}

Envelope Encryption Example

信封加密示例

java
public class EnvelopeEncryptionExample {
    public static void main(String[] args) {
        KmsClient kmsClient = KmsClient.builder()
            .region(Region.US_EAST_1)
            .build();

        String masterKeyId = "alias/your-master-key";
        String largeData = "This is a large amount of data that needs encryption...";
        byte[] data = largeData.getBytes(StandardCharsets.UTF_8);

        // Encrypt using envelope pattern
        DataKeyResult encryptedEnvelope = encryptWithEnvelope(
            kmsClient, masterKeyId, data);

        // Decrypt
        byte[] decryptedData = decryptWithEnvelope(
            kmsClient, encryptedEnvelope);

        String result = new String(decryptedData, StandardCharsets.UTF_8);
        System.out.println("Decrypted: " + result);
    }
}
java
public class EnvelopeEncryptionExample {
    public static void main(String[] args) {
        KmsClient kmsClient = KmsClient.builder()
            .region(Region.US_EAST_1)
            .build();

        String masterKeyId = "alias/your-master-key";
        String largeData = "This is a large amount of data that needs encryption...";
        byte[] data = largeData.getBytes(StandardCharsets.UTF_8);

        // Encrypt using envelope pattern
        DataKeyResult encryptedEnvelope = encryptWithEnvelope(
            kmsClient, masterKeyId, data);

        // Decrypt
        byte[] decryptedData = decryptWithEnvelope(
            kmsClient, encryptedEnvelope);

        String result = new String(decryptedData, StandardCharsets.UTF_8);
        System.out.println("Decrypted: " + result);
    }
}

Best Practices

最佳实践

Security

安全

  • Always use envelope encryption for large data - Encrypt data locally and only encrypt the data key with KMS
  • Use encryption context - Add contextual information to track and audit usage
  • Never log sensitive data - Avoid logging plaintext or encryption keys
  • Implement proper key lifecycle - Enable automatic rotation and set deletion policies
  • Use separate keys for different purposes - Don't reuse keys across multiple applications
  • 始终对大数据使用信封加密 - 在本地加密数据，仅使用KMS加密数据密钥
  • 使用加密上下文 - 添加上下文信息以追踪和审计使用情况
  • 切勿记录敏感数据 - 避免记录明文或加密密钥
  • 实现完善的密钥生命周期管理 - 启用自动轮换并设置删除策略
  • 为不同用途使用独立密钥 - 不要在多个应用中复用密钥

Performance

性能

  • Cache encrypted data keys - Reduce KMS API calls by caching data keys
  • Use async operations - Leverage async clients for non-blocking I/O
  • Reuse client instances - Don't create new clients for each operation
  • Implement connection pooling - Configure proper connection pooling settings
  • 缓存加密的数据密钥 - 通过缓存数据密钥减少KMS API调用
  • 使用异步操作 - 利用异步客户端实现非阻塞I/O
  • 复用客户端实例 - 不要为每个操作创建新客户端
  • 实现连接池 - 配置合适的连接池设置

Error Handling

错误处理

  • Implement retry logic - Handle throttling exceptions with exponential backoff
  • Check key states - Verify key is enabled before performing operations
  • Use circuit breakers - Prevent cascading failures during KMS outages
  • Log errors comprehensively - Include KMS error codes and context
  • 实现重试逻辑 - 使用指数退避处理限流异常
  • 检查密钥状态 - 在执行操作前验证密钥是否启用
  • 使用断路器 - 在KMS服务中断时防止级联故障
  • 全面记录错误 - 包含KMS错误代码和上下文信息

References

参考资料

For detailed implementation patterns, advanced techniques, and comprehensive examples:
  • @references/technical-guide.md - Complete technical implementation patterns
  • @references/spring-boot-integration.md - Spring Boot integration patterns
  • @references/testing.md - Testing strategies and examples
  • @references/best-practices.md - Security and operational best practices
如需了解详细的实现模式、高级技术及全面示例，请参考：
  • @references/technical-guide.md - 完整技术实现模式
  • @references/spring-boot-integration.md - Spring Boot集成模式
  • @references/testing.md - 测试策略与示例
  • @references/best-practices.md - 安全与运维最佳实践

Related Skills

相关技能

  • @aws-sdk-java-v2-core - Core AWS SDK patterns and configuration
  • @aws-sdk-java-v2-dynamodb - DynamoDB integration patterns
  • @aws-sdk-java-v2-secrets-manager - Secrets management patterns
  • @spring-boot-dependency-injection - Spring dependency injection patterns
  • @aws-sdk-java-v2-core - 核心AWS SDK实践与配置
  • @aws-sdk-java-v2-dynamodb - DynamoDB集成模式
  • @aws-sdk-java-v2-secrets-manager - 密钥管理实践
  • @spring-boot-dependency-injection - Spring依赖注入模式

External References

外部参考