Key Management Service (KMS) provides SDKs and KMS Agent for key management, cryptographic operations, and operations for secret value retrieval. You can integrate SDKs or KMS Agent with your self-managed application to perform the preceding operations. This topic describes the integration process.
Integration overview
Applications can use different integration tools to call API operations of KMS. The supported authentication methods and API types in the process vary based on gateway types. The following figure shows the integration process.
Gateway types: Shared and dedicated gateways are provided. Shared gateways are for the global network of KMS, and dedicated gateways are for the network of a specific KMS instance.
Authentication methods: KMS supports Resource Access Management (RAM) authentication and application access point (AAP) authentication. AAP authentication is not recommended.
Integration methods: KMS provides SDKs and KMS Agent for users to integrate KMS in business code. Supported SDKs are Alibaba Cloud SDK, secret SDKs, and KMS Instance SDK.
API types: KMS provides KMS API and KMS Instance API. KMS Instance API is not recommended. The supported API operations can be classified into management API operations and business API operations in terms of features. Business API operations are cryptographic operations and secret retrieval operations. KMS API supports management and business API operations while KMS Instance API supports only business API operations.
Gateway types
KMS provides shared and dedicated gateways. Shared gateways are for the global network of KMS and allow users to access KMS over the Internet or virtual private clouds (VPCs). Shared gateways support management and business API operations. Dedicated gateways are for the network of a specific KMS instance and allow users to access KMS only over private networks. Dedicated gateways support only business API operations and ensure end-to-end API operation security and high data security.
Difference | Shared gateway | Dedicated gateway |
Recommended scenario |
|
|
Endpoint | Internet or VPC | KMS private network |
Performance | For data encryption and decryption performance, queries per second (QPS) is 1,000 when shared gateways are used to access KMS. | The performance is subject to the computing performance of your KMS instance. For example, the computing performance can be 1,000 or 2,000 QPS. |
Supported integration method | Alibaba Cloud SDK, secret SDK, and KMS Agent | Alibaba Cloud SDK, secret SDK, KMS Agent, and KMS Instance SDK |
Supported API operation | All KMS API operations | Cryptographic operations and secret value retrieval operation of KMS API, and KMS Instance API operations. KMS Instance API operations are not recommended. |
Authentication | RAM authentication and AAP authentication. AAP authentication is not recommended. | RAM authentication and AAP authentication. AAP authentication is not recommended. |
Certificate authority (CA) certificate | No CA certificates are required. | CA certificates are required. |
Authentication
KMS supports RAM authentication and AAP authentication. AAP authentication is not recommended. For more information, see Manage access credentials and AAP management.
Difference | RAM authentication | AAP authentication (not recommended) |
Function |
|
|
Supported integration method | Alibaba Cloud SDK, secret SDK, and KMS Agent | Secret SDK and KMS Instance SDK |
Supported API operation | All KMS API operations | Secret retrieval operation of KMS API and operations of KMS Instance API |
Supported gateway | Dedicated and shared gateways | Dedicated and shared gateways Note 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. |
Integration methods
KMS provides SDKs and KMS Agent for integration. SDKs support all management API operations and business API operations, which are cryptographic operations and secret retrieval operations. KMS Agent supports only secret retrieval operations.
SDKs
SDKs encapsulate the complex data signing process in a method. You need to only enter the required parameters and authentication information based on the API description. KMS provides Alibaba Cloud SDK, secret SDKs, and KMS Instance SDK. KMS Instance SDK is not recommended. You can select a SDK based on business requirements. Then, you can integrate the SDK and use KMS based on the following flowchart. For more information about SDK integration, see SDK references.
Usage notes
All management and business API operations related to keys and secrets are supported. Management API operations support only the SDK integration method.
SDKs in different programming languages are provided for corresponding environments.
Integration flowchart
Integration description
SDK type | Supported API operation | Gateway and authentication method | Supported programming language |
Secret SDK |
| Shared gateway:
Dedicated gateway: AAP authentication for KMS Instance API (not recommended) |
|
Alibaba Cloud SDK | KMS API:
| Shared gateway: RAM authentication for KMS API Dedicated gateway: RAM authentication for KMS API |
|
KMS Instance SDK (not recommended) | KMS Instance API: Key-related operations, Secret-related operations, and GenerateRandom | Shared gateway: not supported Dedicated gateway: AAP authentication for KMS Instance API |
|
KMS Agent
KMS Agent simplifies the authentication and cache management processes for access from applications to KMS. It is developed on top of standard HTTP interfaces. For more information, see KMS Agent.
Usage notes
Business applications in any programming language can access KMS Agent.
KMS Agent supports access only from local business applications.
KMS Agent supports only the secret retrieval operation and does not support secret information management operations, such as modifying and deleting a secret.
Integration flowchart
Integration description
Supported API operation | Gateway type | Authentication method | Supported programming language |
KMS API: | Shared and dedicated gateways | RAM authentication | KMS Agent is developed on top of standard HTTP interfaces and can be used by business applications in all programming languages. |
API types
KMS provides KMS API and KMS Instance API. KMS Instance API is not recommended. The supported API operations can be classified into management API operations, cryptographic operations, and secret retrieval operations in terms of features. For more information, see KMS API and KMS Instance API.
Management API operations
Management API operations include the operations to manage KMS instances, keys, and secrets, such as creating a key, creating a secret, creating a KMS instance, and modifying a secret tag.
You can use only Alibaba Cloud SDK to call management API operations of KMS API over shared gateways.
Cryptographic operations
Cryptographic operations include symmetric encryption and decryption, asymmetric encryption and decryption, envelope encryption, data key generation, data signing, and signature verification.
You can use Alibaba Cloud SDK or KMS Instance SDK to call cryptographic operations.
If you want to call cryptographic operations over shared gateways, you must turn on the switch for access over the Internet. For more information, see Access KMS instance keys over the Internet.
Secret value retrieval
You can use secret SDKs, Alibaba Cloud SDK, KMS Instance SDK, or KMS Agent to call GetSecretValue of KMS API or GetSecretValue of KMS Instance API over shared or dedicated gateways. The GetSecretValue operation of KMS Instance API is not recommended.
