All Products
Search

This Product

    Key Management Service:SDK reference

    Document Center

    Key Management Service:SDK reference

    Last Updated:May 10, 2024

    After you purchase a Key Management Service (KMS) instance of the software key management type or the hardware key management type, your applications can use SDKs to manage and use resources in the instance by calling API operations. This topic describes the SDKs that your applications can use.

    Alibaba Cloud SDK

    After you integrate Alibaba Cloud SDK into your applications, you can call an API operation to perform the following operations by using an endpoint of KMS. For more information about API operations, see List of operations by function.

    • 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. To perform management operations in KMS, you must call Alibaba Cloud SDK.

    • Secret value retrieval: the operation to retrieve secret values in KMS.

    Note

    Take note of the following information to perform cryptographic operations:

    • Use keys outside KMS instances: Only Alibaba Cloud SDK is supported.

    • Use keys in KMS instances: Alibaba Cloud SDK and KMS Instance SDK are supported. When you use Alibaba Cloud SDK, authentication methods support only Resource Access Management (RAM) roles whose trusted entities are Alibaba Cloud services. For more information, see Create a RAM role for a trusted Alibaba Cloud service.

    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 that are related to Alibaba Cloud. Alibaba Cloud provides Alibaba Cloud SDK V1.0 and Alibaba Cloud SDK V2.0. For more information about the differences between Alibaba Cloud SDK V1.0 and Alibaba Cloud SDK V2.0 and how to select an appropriate version, see Alibaba Cloud SDK V1.0 and Alibaba Cloud SDK V2.0.

    Alibaba Cloud SDK V2.0 supports various programming languages, including Java 6 or later, Python, C++, PHP, NET (C# only), Go, TypeScript, and Swift. Alibaba Cloud SDK V1.0 supports various programming languages, including Java 6 or later, Python, C++, PHP, NET (C# only), and Go. For more information, see Overview of Alibaba Cloud SDK.

    Note

    When you use Alibaba Cloud SDK to retrieve a secret in the production environment, we recommend that you implement business logic such as error-based retry and secret caching to prevent secret retrieval failures caused by network fluctuations. We recommend that you use a secret SDK.

    KMS Instance SDK

    Applications call KMS Instance SDK to use the keys of a KMS instance to perform cryptographic operations and retrieve the secrets of the KMS instance by using the endpoint of the KMS instance.

    KMS Instance SDK supports various programming languages, including Java 8 or later, PHP, Go, Python, and .NET (C# only). For more information, see KMS Instance SDK.

    Note

    When you use KMS Instance SDK to retrieve a secret in the production environment, we recommend that you implement business logic such as error-based retry and secret caching to prevent secret retrieval failures caused by network fluctuations. We recommend that you use a secret SDK.

    Secret SDKs

    Secret SDKs are exclusively designed to retrieve secrets.

    Note

    When you use secret SDKs to retrieve a secret in the production environment, we recommend that you implement business logic such as error-based retry and secret caching to prevent secret retrieval failures caused by network fluctuations.

    The following types of secret SDKs are available:

    • Secret client: supports all types of secrets. You can use a single line of code to quickly retrieve a secret in an application. The secret client encapsulates the capabilities to cache and refresh secrets in applications to provide high stability. The secret client supports various programming languages, including Java 8 or later, Go, and Python.

    • Secret Java Database Connectivity (JDBC) client: supports only ApsaraDB RDS secrets and generic secrets whose values meet specific format requirements. If you connect to a database by using JDBC connections, connection pools, or open source database frameworks, you can use the SDK to complete identity authentication and configure the custom secret refresh frequency. Connection pools include c3p0 and Database Connection Pools (DBCPs). The secret JDBC client supports only Java 8 or later.

      Note

      Before you can use the secret JDBC client, the secret client must be installed.

    • RAM secret plug-in: supports only RAM secrets. If your application uses Alibaba Cloud SDK V1.0, OSS-SDK, or ONS Java Client, you can use the plug-in to retrieve secret values and complete identity authentication. In this case, the secrets refer to AccessKey pairs. The RAM secret plug-in supports various programming languages, including Java 8 or later, Go, and Python.

    Endpoint description

    KMS provides the following two types of endpoints:

    • KMS endpoint: the global network address of KMS. You can use an endpoint of KMS to establish a connection with KMS and call operations of KMS API. You can access KMS over the Internet or an internal network. For more information about operations, see List of operations by function. For more information about the endpoints of KMS, see Operations.

    • KMS instance endpoint: the address of a specific KMS instance. You can use an endpoint of a KMS instance to establish a connection with the KMS instance and call operations of KMS Instance API. You can access a KMS instance only over an internal network. For more information about operations, see Instance API.

      An endpoint of a KMS instance is in the {Instance ID}.cryptoservice.kms.aliyuncs.com format. To obtain the endpoint of a KMS instance, go to the Instances page, view the details of the instance, obtain the value of Instance VPC Endpoint, and then remove https:// from the value.

    You can use a secret SDK to retrieve secrets, you can use a KMS endpoint or a KMS instance endpoint to access KMS. Compared with KMS endpoints, KMS instance endpoints provide the following advantages. We recommend that you use KMS instance endpoints.

    • A client can directly communicate with a KMS instance. This reduces network latency.

    • A client can communicate with a KMS instance only when the client is configured with the endpoint of the instance. This enhances security and control capabilities.

    • High queries per second (QPS) is provided. For more information, see Performance quotas.