All Products
Document Center

Key Management Service:Overview

Last Updated:May 10, 2024

Key Management Service (KMS) provides the secret management feature that allows you to store secret information such as account passwords and AccessKey pairs. If you integrate Alibaba Cloud SDK, KMS Instance SDK, or secret SDKs into your application, your application can dynamically retrieve secret information from KMS. This helps prevent risks of information leaks or malicious operations that are caused due to secret information in plaintext. This topic describes the basic information about secrets, including scenarios, elements, and rotation.

Benefits of the secret management feature

Leaks of sensitive data, such as passwords of the accounts that are used to access databases and servers, SSH keys, and AccessKey pairs, are the main threats to data security. To reduce the risks of data leaks, you must effectively protect and periodically rotate secrets. The secret management feature provides the following benefits:

  • Uses high-security encryption algorithms to encrypt and store secret values. This prevents leaks of secrets and high-value assets due to hardcoded secrets and improves data security.

  • Provides secure and convenient access methods. This way, applications can use secrets in a codeless or low-code manner.

  • Provides emergency response capabilities. Applications and services are not affected when you immediately rotate your secrets.


    The capabilities are supported only for Resource Access Management (RAM) secrets, ApsaraDB RDS secrets (Manage Dual Accounts mode), and Elastic Compute Service (ECS) secrets that are integrated into applications by using secret SDKs.

  • Allows you to rotate dynamic secrets at a high frequency. This narrows the rotation window and reduces the risk of secret cracking.

  • Allows you to use API operations and O&M orchestration tools such as Terraform and Resource Orchestration Service (ROS). This meets the requirements for centralized and large-scale security management.


The following section describes the basic management scenarios and use scenarios of secrets. In the following example, the username and password of a self-managed database are managed in KMS.


If you use an ApsaraDB RDS instance, we recommend that you use an ApsaraDB RDS secret. For more information, see Manage and use ApsaraDB RDS secrets.


  1. A security administrator configures the username and password that are required for an application named MyApp to access a database.

  2. The security administrator creates a generic secret named MyDbCreds in KMS to manage the username and password.

  3. When MyApp needs to access the database, MyApp retrieves the MyDbCreds secret from KMS by using a secret SDK.

  4. KMS reads the username and password in ciphertext, decrypts the ciphertext, and then returns the plaintext to MyApp over HTTPS.

  5. MyApp reads and parses the plaintext that is returned by KMS to obtain the username and password. Then, MyApp uses the username and password to access the database.

MyApp calls an API operation of KMS to obtain the username and password. This prevents sensitive data leaks caused by hardcoded secrets. The following figure shows the differences between hardcoded secrets and secrets managed in KMS.


Secret elements

A secret consists of metadata and one or more secret versions. You can log on to the KMS console and view secret details on the Secrets page.

  • Metadata

    The metadata of a secret contains the secret name, Alibaba Cloud Resource Name (ARN), creation time, secret type, encryption key, and tag.


    The encryption key is used only to encrypt secret values. The key is not used to encrypt the metadata of a secret. The key and the secret must belong to the same KMS instance, and the key must be a symmetric key.


  • Secret versions

    A secret can have multiple versions. Each secret version contains a version number, a stage label, and a secret value.


    • Version number: A version number can be generated only when a secret value is stored. The version number is unique within a secret and cannot be modified. A version number can be associated with multiple stage labels. Each stage label can be associated with only one version number.

    • Stage label: A stage label is unique within a secret. Stage labels fall into two categories: built-in stage labels and custom stage labels.

      • Built-in stage labels:

        • ACSCurrent: the current version of a secret, which is the status of the most recently stored secret value.

        • ACSPrevious: the previous version of a secret.

        • ACSPendding: the pending version of a secret, which is generated during the rotation of a secret. After the rotation is complete, the version is deleted.

          • When you call an operation to retrieve a secret value, the secret value whose stage label is ACSCurrent is read.

          • The built-in stage labels function as pointers. For example, the first time you store a secret value, the version number is recorded as v1, and the built-in stage label is ACSCurrent. If another secret value is subsequently stored, the version number of the secret value is recorded as v2, the built-in stage label of the secret value of v2 becomes ACSCurrent, and the stage label of the secret value of v1 is automatically changed to ACSPrevious.

      • Custom stage label: You can configure multiple custom stage labels for each secret version.

    • Secret value: the stored secret information. The value can be a string or a binary value.


    If the number of versions in a secret exceeds the upper limit, the earliest version that does not have a stage label is deleted.

Secret rotation

Rotation is the practice of periodically updating a secret to new versions. This helps improve the security of the secret. The stage label of a new secret version is set to ACSCurrent. Applications dynamically retrieve the secret value whose stage label is ACSCurrent.

Rotation process


Rotation methods

  • Automatic rotation: After you specify a rotation period, KMS automatically performs the rotation when the specified period ends. You can specify a rotation period for RAM secrets, ApsaraDB RDS secrets, and ECS secrets in KMS. You cannot specify a rotation period for generic secrets in KMS. You can periodically rotate generic secrets by using Function Compute.

  • Immediate rotation: If your secrets are leaked, you can immediately rotate the secrets as an emergency response. RAM secrets, ApsaraDB RDS secrets, and ECS secrets support immediate rotation. To immediately rotate a generic secret, you must store a secret value.

Supported types of secrets

KMS supports four types of secrets: generic secrets, RAM secrets, ApsaraDB RDS secrets, and ECS secrets. The following table describes the secret types.

  • RAM secrets, ApsaraDB RDS secrets, and ECS secrets are fully managed. For the preceding types of secrets that are fully managed in KMS, you can perform secret rotation within KMS. Operations that are performed outside KMS, such as changing the secret status or deleting the secrets, hinder secret rotation and affect the functionality of secrets that are retrieved from KMS.

  • If you want to manage the rotation of a secret, you can use a generic secret.

Secret type


Rotation method


Generic secret

Generic secrets are basic secrets that can be managed by using KMS. You can use generic secrets to store sensitive data such as accounts, AccessKey pairs, OAuth secrets and tokens, and API keys.

  • Store a new secret value to generate a new version for a generic secret to immediately rotate the generic secret.

  • Periodically rotate a generic secret by using Function Compute.

Manage and use generic secrets

RAM secret

A RAM secret is a fully managed secret that is supported by KMS. You can create a RAM secret to store the AccessKey pair of a RAM user.

  • Configure automatic rotation in KMS.

  • Immediately rotate a secret in KMS.

Manage and use RAM secrets

ApsaraDB RDS secret

An ApsaraDB RDS secret is a fully managed secret that is supported by KMS. You can create an ApsaraDB RDS secret to store the usernames and passwords of databases on an ApsaraDB RDS instance.

  • Configure automatic rotation in KMS.

  • Immediately rotate a secret in KMS.

Manage and use ApsaraDB RDS secrets

ECS secret

An ECS secret is a fully managed secret that is supported by KMS. You can create an ECS secret to store the usernames and passwords or SSH keys that are used to log on to ECS instances.

  • Configure automatic rotation in KMS.

  • Immediately rotate a secret in KMS.

Manage and use ECS secrets


Before you can use a secret, you must purchase a KMS instance and configure a secret quota when you purchase the instance. For more information about the billing of KMS, see Billing. For more information about how to purchase a KMS instance, see Purchase and enable a KMS instance.

Access control and audit

You can use Resource Access Management (RAM) to control access and operation permissions on secrets to ensure the security of the secrets. For more information about how to configure permission policies, see Custom permission policies.

You can use ActionTrail to record the creation, rotation, and retrieval of secrets. For more information, see Query the usage records of keys and secrets.