Key Management Service (KMS) provides Alibaba Cloud SDK, secret SDKs, and KMS Instance SDK. KMS Instance SDK is not recommended. This topic describes the SDK integration process, authentication, supported API operations, and supported gateway types. You can select a SDK based on your business requirements.
SDK integration flowchart
Alibaba Cloud SDK
Alibaba Cloud SDK is an encapsulated program dependency package and is used to call API operations of cloud services. This way, developers can quickly build applications on top of Alibaba Cloud. Alibaba Cloud SDK supports both management API operations to manage secrets and keys and business API operations. Alibaba Cloud SDK supports Java, Python, C++, PHP, .NET (C# only), Go, TypeScript, and Swift. For more information, see Alibaba Cloud SDK.
Supported API operations
Alibaba Cloud SDK allows you to call management and business operations of KMS API. For more information, see Supported OpenAPI.
Management operations: the operations to manage default keys and KMS instances, such as creating a key, creating a secret, creating a KMS instance, and changing key tags.
Business operations:
Cryptographic operations: symmetric encryption and decryption, asymmetric encryption and decryption, envelope encryption, and the operations to generate data keys, generate digital signatures, and verify digital signatures.
Secret value retrieval: the operation to retrieve the secret values of secrets in KMS instances.
When you use Alibaba Cloud SDK to retrieve a secret value in the production environment, we recommend that you implement business logic such as retry policies and secret caching to prevent secret value retrieval failures caused by network jitter. For more information, see Use the exponential backoff method to retry requests.
Supported gateway types
Alibaba Cloud SDK allows you to call KMS API and KMS Instance API over shared or dedicated gateways. You can call management API operations only over shared gateways. You can call business API operations over shared or dedicated gateways.
Gateway type | Recommended scenario | Authentication | Supported API operation |
Shared gateway |
| RAM authentication | All KMS API operations |
Dedicated gateway |
| RAM authentication | The secret value retrieval operation and cryptographic operations of KMS API |
Secret SDKs
Secret SDKs are a tool for custom encapsulation of KMS API and KMS Instance API and encapsulate the capabilities to cache and refresh secrets in applications. Secret SDKs feature high service stability and easy integration with service applications for developers. Secret SDKs only allow you to retrieve secrets. The following types of secret SDKs are available: the secret client, the secret Java Database Connectivity (JDBC) client, and the Resource Access Management (RAM) secret plug-in. Secret SDKs support Java 8 and later, Python, and Go. For more information, see Secret SDKs.
Types of secret SDKs
SDK type | Description |
| |
| |
|
Supported APIs
Secret SDKs only allow you to retrieve secret values by calling KMS API or KMS Instance API. KMS Instance API is not recommended. If you want to call API operations to manage secrets, we recommend that you use Alibaba Cloud SDK.
When you use secret SDKs to retrieve a secret value in the production environment, we recommend that you implement business logic such as retry policies and secret caching to prevent secret value retrieval failures caused by network jitter. For more information, see Use the exponential backoff method to retry requests.
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 |
| RAM authentication | Secret value retrieval of KMS API |
AAP authentication (not recommended) | Secret value retrieval of KMS Instance API | ||
Dedicated gateway |
| AAP authentication (not recommended) | Secret value retrieval of KMS Instance API |
KMS Instance SDK (not recommended)
Applications use KMS Instance SDK to access dedicated gateway endpoints and call cryptographic operations and retrieve secret values. KMS Instance SDK supports Java 8 and later, PHP, Go, Python, and .NET (C# only). For more information, see KMS Instance SDK.
Gateway endpoints and authentication
Gateway endpoints
KMS provides the following two types of endpoints:
Shared gateway endpoint (also known as KMS service endpoint): the global network address of KMS. You can access shared gateway endpoints over Internet or VPCs. Shared gateway endpoints vary based on regions. For example, the shared gateway endpoints for the China (Hangzhou) region 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 provides RAM authentication and AAP authentication. Shared gateways support both RAM authentication and AAP authentication. 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): If you want to use this authentication method, you must create an AAP and download and save the client key, which includes ClientKeyContent and ClientKeyPassword. For AAP authentication, two authentication modes of dedicated gateway configuration and shared gateway configuration are provided for different gateways. For more information, see AAP authentication.