KMS integration guide, shared gateway, dedicated gateway, SDK, KMS Agent, application access-Key Management Service(KMS)-阿里云帮助中心

KMS integration overview

Integrating with KMS requires decisions in four areas:

Gateway type: shared gateway (Internet/VPC) or dedicated gateway (private network)
Authentication method: RAM authentication or application access point (AAP) authentication (not recommended)
Integration method: SDK (Alibaba Cloud SDK, secret SDK, or instance SDK) or KMS Agent
API type: management API operations, cryptographic operations, and secret retrieval operations

KMS integration architecture:

Decision guide

Use these steps to determine your gateway, authentication, and integration methods:

Step 1: Determine network isolation requirements

Workloads deployed in Alibaba Cloud VPCs with requirements for high performance or high security → Dedicated gateway (private network, end-to-end data encryption)
Workloads deployed in non-Alibaba Cloud environments or management operations required → Shared gateway (Internet/VPC)

Step 2: Determine API capability requirements

Management operations required (creating keys, secrets, and so on) → Shared gateway + Alibaba Cloud SDK (required, as management operations are supported only through this combination)
Only cryptographic operations or secret retrieval required → Secret SDK or Alibaba Cloud SDK (depending on the gateway type)
Cross-language applications that need simplified integration → KMS Agent (supports only secret retrieval)

Gateway types

KMS offers shared gateways and dedicated gateways.

Shared gateways use the KMS global network for access over the Internet or VPC. They support both management and business API operations.
Dedicated gateways use the private network of a specific KMS instance for access over private networks only. They support only business API operations and provide end-to-end API security with higher data security.

Feature	Shared gateway	Dedicated gateway
Recommended scenario	You need to manage KMS instances, keys, or secrets (create, modify, or delete). Workloads are deployed outside Alibaba Cloud VPCs. You access KMS from a non-production environment such as an internal test environment.	Workloads are deployed on Alibaba Cloud VPCs. Business operations (encryption, decryption, secret retrieval) require high performance. Data security requirements are high.
Endpoint	Internet or VPC	KMS private endpoint
Performance	Subject to QPS limits. For example, shared gateway encryption/decryption supports 1,000 QPS.	Determined by the KMS instance you purchase (for example, 1,000 or 2,000 QPS). See the Content parameter description.
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 OpenAPI operations	OpenAPI: cryptographic operations and secret retrieval. Instance API (not recommended)
Authentication	RAM authentication and AAP authentication (not recommended)	RAM authentication and AAP authentication (not recommended)
CA certificate	Not required	Required

Integration methods

KMS supports SDK-based integration and KMS Agent. They differ in supported API operations and scenarios.

SDK vs KMS Agent

Dimension	SDK (Alibaba Cloud/secret/instance)	KMS Agent	Recommended choice
Supported API operations	Management, cryptographic, and secret retrieval	Secret retrieval only	Management operations required :SDK Only secret retrieval: Either
Language support	Java, Python, Go, C++, PHP, .NET, TypeScript, Swift	Any programming language (HTTP interface)	Cross-language or niche language : Agent
Network deployment	Direct connection to the gateway. Supports Internet, VPC, and private network	Local application access. HTTP local communication	Multi-language microservices :Agent Performance-critical direct connection :SDK
Integration complexity	Language-specific SDK with built-in signature logic	Simplified authentication, standard HTTP interface, proxy-managed secrets	Quick integration:Agent Full control: SDK

Integration process

SDK integration

KMS SDKs handle the signature process internally — you provide parameters and authentication information. Available SDKs: Alibaba Cloud SDK, secret SDK, and KMS Instance SDK (not recommended).

Select an SDK based on your gateway, authentication, and API type, then follow this integration process. The SDK reference provides detailed configuration.

SDK integration process

Standard integration process:

Usage notes

Supports all key and secret operations (management and business). Management operations require SDK integration.
Install the SDK for your programming language.

SDK types in detail

The three SDK types differ in supported operations, gateways, authentication, and languages:

SDK type	Supported API operation	Gateway and authentication method	Supported programming language
Secret SDK	OpenAPI: Secret retrieval: GetSecretValue Instance API (not recommended): GetSecretValue	Shared gateway: RAM authentication + OpenAPI AAP authentication + OpenAPI (not recommended) AAP authentication + Instance API (not recommended) Dedicated gateway: RAM authentication + OpenAPI AAP authentication + Instance API (not recommended)	Java (Java 8 and later) Python Go
Alibaba Cloud SDK	OpenAPI: Management operations Business operations-Cryptographic operations Business operations-Retrieving secret values	Shared gateway: RAM authentication + OpenAPI Dedicated gateway: RAM authentication + OpenAPI	Java Python Go C++ PHP .NET (C#) TypeScript Swift
KMS Instance SDK (not recommended)	Instance API: Key-related operations, Secret-related operations, and GenerateRandom	Shared gateway: not supported Dedicated gateway: AAP authentication + Instance API	Java (Java 8 and later) Python Go PHP .NET (C# only)

KMS Agent integration

KMS Agent simplifies authentication and cache management for applications accessing KMS via standard HTTP interfaces. For more information, see KMS Agent.

Usage notes

Supports any programming language.
Supports local application access only.
Supports secret retrieval only. Management operations (create, modify, delete) are not supported.

KMS Agent integration process

Development notes

Supported API operation

Gateway type

Authentication method

Supported programming language

OpenAPI:

Secret retrieval: GetSecretValue

Shared gateway and dedicated gateway

RAM authentication

Any programming language (via standard HTTP interfaces)

KMS API types

KMS provides two API types: OpenAPI and KMS Instance API (not recommended). By function, they cover management operations, cryptographic operations, and secret retrieval. OpenAPI overview. KMS Instance API.

API type comparison

API types and their supported integration methods:

API type	Alibaba Cloud SDK	Secret SDK	KMS Instance SDK	KMS Agent
Management operations Create, modify, or delete keys and secrets	Supported	Unsupported	Unsupported	Unsupported
Cryptographic operations Encryption, decryption, digital signatures, and more	Supported	Unsupported	Supported	Unsupported
Secret value retrieval Retrieve secret values	Supported	Supported	Supported	Supported

Management API operations

Management operations handle KMS instances, keys, and secrets — including creation, deletion, and tag modification.

Only the Alibaba Cloud SDK can call management operations, through a shared gateway endpoint.

Cryptographic operations

Cryptographic operations include symmetric and asymmetric encryption/decryption, envelope encryption, data key generation, signing, and signature verification.

Use the Alibaba Cloud SDK or KMS Instance SDK for cryptographic operations.

Important

To call cryptographic operations through a shared gateway, you must enable Internet access. For more information, see Accessing keys over the Internet.

Secret retrieval operations

You can use the secret SDK, Alibaba Cloud SDK, KMS Instance SDK, or KMS Agent to call GetSecretValue of OpenAPI or GetSecretValue of KMS Instance API (not recommended) through a shared or dedicated gateway to retrieve KMS secret values.

Authentication

KMS supports RAM authentication and AAP authentication (not recommended). For more information, see Manage RAM access credentials and AAP management.

Feature	RAM authentication	AAP authentication (not recommended)
Description	Supports custom flexible permission policies. Supports RAM roles, STS tokens, ECS RAM roles, and AccessKey pairs. No CA certificate required.	Supports custom flexible permission policies. Requires downloading a client key file containing the identity credential (ClientKeyContent) and password (ClientKeyPassword). CA certificates can be configured for mutual TLS authentication.
Supported integration method	Alibaba Cloud SDK, secret SDK, and KMS Agent	Secret SDK and KMS Instance SDK
Supported API operation	All OpenAPI operations	OpenAPI: secret retrieval. Instance API operations
Supported gateway	Dedicated gateway and shared gateway	Dedicated gateway and shared gateway Note AAP authentication supports both dedicated and shared gateway configurations, described in AAP authentication.