SDK references

KMS provides three SDK categories: Alibaba Cloud SDK, Secret SDKs, and KMS Instance SDK (not recommended). Choose an SDK based on your integration scenario, authentication requirements, and gateway type.

SDK integration flowchart

Alibaba Cloud SDK

Alibaba Cloud SDK is a dependency package for calling cloud service APIs. Developers can quickly build applications on top of Alibaba Cloud. It supports both management and business API operations. Supported languages: Java, Python, C++, PHP, .NET (C# only), Go, TypeScript, and Swift. For more information, see Alibaba Cloud SDK.

Supported API operations

Alibaba Cloud SDK supports management and business operations of KMS API. The full list is available in Supported OpenAPI.

Management operations: manage default keys and KMS instances, such as creating keys, secrets, and instances, and changing key tags.
Business operations:
- Cryptographic operations: symmetric and asymmetric encryption and decryption, envelope encryption, data key generation, and digital signature generation and verification.
- Secret value retrieval: retrieve secret values from KMS instances.

Important

In production, implement retry policies and secret caching to prevent retrieval failures caused by network jitter. For more information, see Retry requests with exponential backoff.

Supported gateway types

Alibaba Cloud SDK accesses KMS API and KMS Instance API over shared or dedicated gateways. Management operations are available only over shared gateways. Business operations are available over both.

Gateway type	Recommended scenario	Authentication	Supported API operation
Shared gateway	You need to manage KMS instances, keys, and secrets. Workloads are deployed outside Alibaba Cloud virtual private clouds (VPCs). You access KMS from a non-production environment, such as a test environment.	RAM authentication	All KMS API operations
Dedicated gateway	Workloads are deployed on Alibaba Cloud VPCs. Business API operations such as encryption, decryption, and secret retrieval are frequently called and require high performance. You have high data security requirements.	RAM authentication	Secret value retrieval and cryptographic operations of KMS API

Secret SDKs

Secret SDKs wrap KMS API and KMS Instance API with built-in secret caching and refresh, providing high stability and easy integration. Secret SDKs only retrieve secrets. Three types are available: the secret client, the secret Java Database Connectivity (JDBC) client, and the Resource Access Management (RAM) secret plug-in. Supported languages: Java 8+, Python, and Go. For more information, see Credentials SDK.

Types of secret SDKs

SDK type	Description
Secrets Manager Client	All types of secrets are supported. Retrieve a secret with a single line of code. Built-in secret caching and refresh for higher stability.
Secret JDBC client	Only Java is supported. You must use Java 8 or later. Only ApsaraDB RDS secrets and generic secrets whose secret values are in the `{"AccountName":"<The username of your database account>","AccountPassword":"<The password of your database account>"}` format are supported. Supports JDBC connections, connection pools (c3p0, DBCP), and open source database frameworks for identity authentication with custom secret refresh frequency.
RAM secret plug-in	Only RAM secrets are supported. Your Alibaba Cloud SDK must be supported by the RAM secret plug-in. Check compatibility in Supported Alibaba Cloud SDKs.

Supported APIs

Secret SDKs only retrieve secret values through KMS API or KMS Instance API. KMS Instance API is not recommended. To manage secrets, use Alibaba Cloud SDK.

Important

In production, implement retry policies and secret caching to prevent retrieval failures caused by network jitter. For more information, see Retry requests with exponential backoff.

Supported gateway types

Secret SDKs retrieve secret values over shared or dedicated gateways. Shared gateways support RAM authentication or application access point (AAP) authentication for KMS API calls. Dedicated gateways support only AAP authentication for KMS Instance API calls.

Gateway type	Recommended scenario	Authentication	Supported API operation
Shared gateway	Secret retrieval performance requirements are low. Workloads are deployed outside Alibaba Cloud VPCs. You access KMS from a non-production environment, such as a test environment.	RAM authentication	Secret value retrieval of KMS API
Shared gateway		AAP authentication (not recommended)	Secret value retrieval of KMS Instance API
Dedicated gateway	Workloads are deployed on Alibaba Cloud VPCs. Secret retrieval operations are frequently called. You have high data security requirements.	AAP authentication (not recommended)	Secret value retrieval of KMS Instance API

KMS Instance SDK (not recommended)

KMS Instance SDK accesses dedicated gateway endpoints for cryptographic operations and secret value retrieval. Supported languages: Java 8+, PHP, Go, Python, and .NET (C# only). For more information, see KMS Instance SDK.

Gateway endpoints and authentication

Gateway endpoints

KMS provides two types of endpoints:

Shared gateway endpoint (KMS service endpoint): the global network address of KMS, accessible over Internet or VPCs. Endpoints vary by region. For example, the China (Hangzhou) endpoints are kms.cn-hangzhou.aliyuncs.com and kms-vpc.cn-hangzhou.aliyuncs.com. For more information, see Operations.
Dedicated gateway endpoint (also known as KMS instance endpoint): the network address of a specific KMS instance. You can access dedicated gateway endpoints only over a private network. Dedicated gateway endpoints are in the {The ID of the KMS instance}.cryptoservice.kms.aliyuncs.com format.

Authentication

KMS supports RAM and AAP authentication. Shared gateways support both. Dedicated gateways support only AAP authentication.

RAM authentication: RAM roles, Security Token Service (STS) tokens, RAM roles of Elastic Compute Service (ECS) instances, and AccessKey pairs.
AAP authentication (not recommended): Create an AAP and download and save the client key, which includes ClientKeyContent and ClientKeyPassword. Two modes are available: dedicated gateway configuration and shared gateway configuration. Configure AAP by following AAP authentication.