本文以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的方式来实现身份验证为例。
更多认证信息配置方式,请参见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()); } }