Key Management Service:Secret management

Why use secret management

Leaked secrets, such as database account passwords, server account passwords, SSH keys, and access keys, are a major threat to data security. To reduce the risk of data leaks, it is crucial to effectively protect and periodically rotate your secrets. Using the secret management feature of KMS provides the following security advantages:

• KMS encrypts and stores secret values by using high-strength encryption algorithms. This prevents leaks of secrets and high-value assets caused by hardcoding and improves data security.

• Enables secure and convenient client access, allowing your applications to dynamically use secrets with minimal to no code.

• Immediate rotation allows you to update secrets without affecting your applications and services.

  Note

  This feature is available only for RAM secrets, database secrets (in managed dual-account mode), and ECS secrets when you integrate them by using a secrets SDK.

• Supports high-frequency rotation for fully dynamic secrets, which shortens a secret's validity period and reduces its risk of compromise.

• Supports centralized and large-scale security management through APIs and infrastructure-as-code (IaC) tools such as Resource Orchestration Service (ROS) or Terraform.

Use cases

This section uses an example of managing the username and password for a self-managed database to illustrate a basic use case for storing and retrieving a secret.

1. A security administrator configures the username and password that the MyApp application needs to access the target database.

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

3. When MyApp needs to access the database, it uses a secrets client SDK to request the 'MyDbCreds' secret from KMS.

4. KMS retrieves the encrypted secret, decrypts it, and returns the plaintext value to MyApp over HTTPS.

5. MyApp parses the returned plaintext secret to get the username and password, and then uses these credentials to access the database.

For the MyApp application, calling a KMS API to retrieve the database username and password avoids the security risks associated with hardcoding secrets. The following figure shows the difference between using hardcoded secrets and using secrets that are managed by KMS.

Components of a secret

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

• Metadata

  Includes information such as the secret name, Alibaba Cloud Resource Name (ARN), creation time, secret type, encryption key, and tags.

  Important

  The encryption key encrypts only the secret value, not the secret's metadata. 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 version includes a version number, stage labels, and a secret value.

  • A secret version can have multiple stage labels, but each stage label can point to only one version.

  • Stage label: A unique label within a secret. Stage labels include built-in stage labels and custom stage labels.

    • Built-in stage labels:

      • ACSCurrent: The current version of the secret. This label always points to the latest secret value.

      • ACSPrevious: The previous version of the secret.

      • ACSPending: A temporary label used during secret rotation. KMS removes this label after the rotation is complete.

        Note

        • When you retrieve a secret value by calling an API operation, KMS returns the secret value that is associated with the ACSCurrent stage label.

        • Built-in stage labels act like pointers. For example, when you first store a secret version (v1), it is labeled ACSCurrent. If you then store a new version (v2), the ACSCurrent label moves to v2, and v1 is automatically relabeled as ACSPrevious.

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

      Important

      Only generic secrets support custom stage labels. The total number of custom and built-in stage labels for a secret cannot exceed eight.

  • Secret value: The sensitive information that you store in the secret. It can be a string or binary data.

  Note

  When the number of versions for a secret exceeds the limit, the oldest version that is not associated with any stage label is automatically deleted.

Secret rotation

Secret rotation is the process of updating a secret by creating a new version. This practice enhances security by limiting the lifetime of a secret. The new version is automatically labeled as ACSCurrent, and applications then dynamically retrieve the secret value by requesting the ACSCurrent version.

Rotation process

Supported secret types

KMS supports four types of secrets: generic secrets, RAM secrets, database secrets, and ECS secrets. The following table provides details about each type.

Billing

Before you can use secrets, you must purchase a KMS instance and configure a secret quota. For more information about the pricing of KMS instances, see Billing. For instructions on how to purchase a KMS instance, see Purchase and enable a KMS instance.

Access control and auditing

You can use Resource Access Management (RAM) to control permissions for accessing and operating on secrets. For more information about how to configure permission policies, see Custom RAM policies for KMS.

You can use ActionTrail to record operations such as creating, rotating, and retrieving secrets. For more information, see Query the usage records of keys and secrets.

Related topics

• Get started with secret management

• Manage and use generic secrets

• Manage and use RAM secrets

• Manage and use database secrets

• Manage and use ECS secrets

• FAQ about secret management