Java语言为例,为您介绍如何使用KMS SDK原版 - 密钥管理服务

本文以Java语言为例，为您介绍如何使用阿里云SDK。

背景信息

您可以访问开源代码仓库，查看更多语言和场景的代码示例。
关于OpenAPI的更多信息，请参见API概览。

前提条件

如果SDK的认证方式是AccessKey，请确保已创建AccessKey。具体操作，请参见创建AccessKey。
如果SDK的认证方式是RAM角色，请确保已创建RAM角色。具体操作，请参见授予实例RAM角色。

步骤一：添加SDK依赖

在项目中添加Maven依赖，从Maven仓库中自动下载Java安装包。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.5.2</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-kms</artifactId>
    <version>2.16.0</version>
</dependency>

说明

建议您安装最新版本的SDK。关于版本的更多信息，请参见阿里云SDK概览。

步骤二：初始化Client

使用阿里云SDK发起KMS API请求，您需要初始化一个Client。本文介绍使用AccessKey认证和使用RAM角色认证，阿里云SDK还提供了其他认证方式。更多信息，请参见Credentials 设置。

请根据KMS所属地域正确填写服务接入地址（又称“访问端点”或“Endpoint”），关于服务接入地址的更多信息，请参见支持的地域。

使用AccessKey认证

说明

阿里云账号AccessKey拥有所有OpenAPI的访问权限，建议您使用RAM用户进行API访问或日常运维。强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。

本示例以将AccessKey配置在环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET的方式来实现身份验证为例。

更多认证信息配置方式，请参见Credentials 设置。
不同操作系统的环境变量配置方法不同，具体操作，请参见在Linux、macOS和Windows系统配置环境变量。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.profile.*;
import com.aliyuncs.http.*;

	/**
     * 创建KmsClient，使用自定义Endpoint、AK认证。
     */
    public static DefaultAcsClient initClientByAK(String regionId, String endpoint) {
        //指定KMS的Endpoint
        DefaultProfile.addEndpoint(regionId, "kms", endpoint);

        IClientProfile profile = DefaultProfile.getProfile(regionId, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        HttpClientConfig clientConfig = HttpClientConfig.getDefault();
        profile.setHttpClientConfig(clientConfig);
        DefaultAcsClient kmsClient = new DefaultAcsClient(profile);
        return kmsClient;
    }

使用RAM角色认证

以ECS实例通过RAM角色访问KMS为例，介绍如何初始化Client。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.profile.*;
import com.aliyuncs.auth.AlibabaCloudCredentialsProvider;
import com.aliyuncs.auth.InstanceProfileCredentialsProvider;

    /**
     * 创建KmsClient，使用自定义Endpoint、RAMRole认证。
     */
public static DefaultAcsClient initClientByRamRole(String regionId, String ramRoleName, String endpoint) {
    //添加自定义Endpoint。
    DefaultProfile.addEndpoint(regionId, "kms", endpoint);
    DefaultProfile profile = DefaultProfile.getProfile(regionId);

    //设置ECS实例RAM角色的凭证Provider。
    AlibabaCloudCredentialsProvider provider = new InstanceProfileCredentialsProvider(ramRoleName);

    DefaultAcsClient client = new DefaultAcsClient(profile, provider);
    return client;
}

步骤三：使用已初始化的Client调用KMS API

初始化Client后，您可以通过Client调用KMS API。本文介绍如下几个使用场景和代码示例。

调用CreateKey创建密钥

示例代码以在KMS实例中创建密钥规格为RSA_2048、密钥用途为SIGN/VERIFY的密钥为例。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.kms.model.v20160120.CreateKeyRequest;
import com.aliyuncs.kms.model.v20160120.CreateKeyResponse;

/**
     * @param kmsClient 阿里云SDK客户端 
     * @param kmsInstanceId KMS实例Id
     * @return
     * @throws ClientException
     */
    public static void createKeySample(DefaultAcsClient kmsClient, String kmsInstanceId) {
        final CreateKeyRequest request = new CreateKeyRequest();
        // 在KMS软件密钥管理实例或硬件密钥管理实例中创建密钥时，请务必正确设置参数DKMSInstanceId，其他创建密钥的场景无需填写该参数。
        // 设置KMS实例Id
        request.setDKMSInstanceId(kmsInstanceId);
        // 密钥规格
        request.setKeySpec("RSA_2048");
        // 密钥用途
        request.setKeyUsage("SIGN/VERIFY");

        final CreateKeyResponse response;
        try {
            response = kmsClient.getAcsResponse(request);
            System.out.println("KeyId:" + response.getKeyMetadata().getKeyId());
        } catch (ServerException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getErrCode());
            // 打印 RequestId
            System.out.println(e.getRequestId());
            // 打印错误信息
            System.out.println(e.getErrMsg());
        } catch (ClientException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getMessage());
        }
    }

调用ListKeys列举密钥

示例代码以列举密钥状态（KeyState）为启用（Enabled)、密钥规格（KeySpec）为RSA_2048的密钥为例，同时设置了每页返回值的个数（PageSize）为100。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.kms.model.v20160120.ListKeysRequest;
import com.aliyuncs.kms.model.v20160120.ListKeysResponse;

public static void listKeysSample(DefaultAcsClient kmsClient) {
        final ListKeysRequest request = new ListKeysRequest();
        request.setPageNumber(1);
        request.setPageSize(100);
        String filters = "[{\"Key\":\"KeyState\", \"Values\":[\"Enabled\"]},{\"Key\":\"KeySpec\", \"Values\":[\"RSA_2048\"]}]";
        request.setFilters(filters);
        try{
        final ListKeysResponse listKeysResponse = kmsClient.getAcsResponse(request);
        System.out.println("TotalCount:" + listKeysResponse.getTotalCount());
        } catch (ServerException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getErrCode());
            // 打印 RequestId
            System.out.println(e.getRequestId());
            // 打印错误信息
            System.out.println(e.getErrMsg());
        } catch (ClientException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getMessage());
        }
    }

调用CreateSecret创建凭据

示例代码以在KMS实例中创建一个通用凭据，并将凭据值版本设置为V1为例。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.kms.model.v20160120.CreateSecretRequest;
import com.aliyuncs.kms.model.v20160120.CreateSecretResponse;

public static void createSecretSample(DefaultAcsClient kmsClient)  {
        final CreateSecretRequest request = new CreateSecretRequest();
        // 设置 KMS实例Id（DKMSInstanceId），即指定将凭据创建于哪个KMS实例。
        request.setDKMSInstanceId("<KMS Instance Id>");
         //用于加密凭据值的密钥的标识符（EncryptionKeyId），该密钥必须为对称密钥且和凭据属于同一个KMS实例。
        request.setEncryptionKeyId("<KeyId>");
        // 凭据名称（SecretName）
        request.setSecretName("Your-secret-name");
        // 凭据类型（SecretType）。可选参数值详见 CreateSecret 接口 API 文档。
        request.setSecretType("Generic");
        // 对凭据的描述（Description）
        request.setDescription("<Description of the secret>");

        // 凭据值版本（VersionId）
        request.setVersionId("V1");
        // 凭据值（SecretData）
        request.setSecretData("<Your Secret Data>");
        try{
        final CreateSecretResponse createSecretResponse = kmsClient.getAcsResponse(request);
        System.out.println("Arn:" + createSecretResponse.getArn());
        } catch (ServerException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getErrCode());
            // 打印 RequestId
            System.out.println(e.getRequestId());
            // 打印错误信息
            System.out.println(e.getErrMsg());
        } catch (ClientException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getMessage());
        }
    }

调用GetSecretValue获取凭据值

请求的AcceptFormat默认使用JSON格式，如果您的凭据值内容（SecretData）中包含特殊字符<>&，请将AcceptFormat设置为XML，以避免特殊字符被转义。示例代码以AcceptFormat设置为XML为例。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.kms.model.v20160120.GetSecretValueRequest;
import com.aliyuncs.kms.model.v20160120.GetSecretValueResponse;

    public static void getSecretValueSample(DefaultAcsClient kmsClient) {
        GetSecretValueRequest request = new GetSecretValueRequest();
        // 设置AcceptFormat为XML
        request.setAcceptFormat(FormatType.XML);
        request.setSecretName("Your-secret-name");
        try {
            final GetSecretValueResponse getSecretValueResponse = kmsClient.getAcsResponse(request);
            // 获取凭据值(SecretData)
            getSecretValueResponse.getSecretData();
        } catch (ServerException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getErrCode());
            // 打印 RequestId
            System.out.println(e.getRequestId());
            // 打印错误信息
            System.out.println(e.getErrMsg());
        } catch (ClientException e) {
            // 打印整体的错误输出
            e.printStackTrace();
            // 打印错误码
            System.out.println(e.getMessage());
        }
    }

密钥管理服务：阿里云SDK for Java