文档

阿里云SDK for Java

更新时间:

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

背景信息

前提条件

  • 如果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的方式来实现身份验证为例。

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());
            }
        }

相关文档