Key Management Service:Getting started with secrets

Background information

KMS allows you to manage the lifecycles of secrets. For example, you can create, delete, and modify a secret. In application code, you can retrieve secrets by using an SDK. This helps prevent sensitive data leaks caused by hardcoded secrets in applications.

KMS allows you to manage generic secrets, Resource Access Management (RAM) secrets, database secrets, and Elastic Compute Service (ECS) secrets. For more information about secrets, see Overview.

Usage notes

KMS uses a key to encrypt a secret. The key and the secret must belong to the same KMS instance, and the key must be a symmetric key. For more information about the symmetric keys that are supported by KMS, see Key types.

Prerequisites

• A KMS instance is created and enabled. For more information, see Purchase and enable a KMS instance.

• A symmetric key for encrypting secrets is created in a KMS instance. For more information, see Create a key.

Step 1: Create a secret

When you create a secret, you can configure secret rotation. KMS periodically updates the secret to ensure the security of the secret.

1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

2. On the Secrets page, click a tab based on the type of secret that you want to create, select the required instance ID from the Instance ID drop-down list, and then click Create Secret. In the panel that appears, configure the parameters and click OK.

   Generic secret

   Note

   You cannot configure secret rotation when you create a generic secret. For more information about how to rotate a generic secret, see Manage and use generic secrets.

   Parameter	Description
   Secret Name	The name of the secret. The secret name is unique within the current region.
   Secret Value	The type of sensitive data that you want to manage. Valid values: Secret Key/Value and Plain Text. The value cannot exceed 30,720 bytes in length, which is equivalent to 30 KB in size.
   Initial Version	The initial version of the secret. Default value: v1. You can also specify a custom version number.
   CMK	The key that is used to encrypt the current value of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces. A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Description	The description of the secret.
   Policy Settings	The policy settings of the secret. For more information, see Overview. You can use the default policy and then modify the policy based on your business requirements after you create the secret.

   RAM secret

   Parameter	Description
   Select RAM User	The RAM user for which you want to create the secret. The selected RAM user must have at least one AccessKey pair. For more information, see Create an AccessKey pair. The secret name is automatically generated based on the name of the RAM user. The secret name is unique within the current region.
   Secret Value	The AccessKey secret of the RAM user. The value cannot exceed 30,720 bytes in length, which is equivalent to 30 KB in size.
   CMK	The key that is used to encrypt the current value of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces. A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Automatic Rotation	Specifies whether to enable automatic secret rotation.
   Days (7 Days to 365 Days)	The interval of automatic secret rotation. This setting is required only when you enable automatic rotation. KMS periodically updates the secret based on the value of this parameter.
   Description	The description of the secret.
   Policy Settings	The policy settings of the secret. For more information, see Overview. You can use the default policy and then modify the policy based on your business requirements after you create the secret.

   Database secret (ApsaraDB RDS)

   You can select only Create Single Secret.

   Parameter	Description
   Database Type	The type of database secret that you want to create. Select ApsaraDB RDS Secrets.
   Secret Name	The name of the secret. The secret name is unique within the current region.
   ApsaraDB RDS Instance	The existing ApsaraDB RDS instance that you want to manage within your Alibaba Cloud account.
   Account Management	Manage Dual Accounts (recommended): This mode is suitable for the scenarios in which the secret is used by applications to access the ApsaraDB RDS instance. In this mode, KMS manages two accounts that have identical permissions. This mode ensures that the connections between applications and the ApsaraDB RDS instance are not interrupted when the secret is rotated. Click the Create Account tab, specify a username prefix, select a database, and then specify permissions. Note KMS does not immediately create accounts. KMS creates accounts after you double-check and confirm the secret information. Click the Import Existing Accounts tab, select usernames, and then specify passwords for the usernames. Note We recommend that you specify the same passwords as the passwords that you specified for the accounts when you created the ApsaraDB RDS instance. If a username and the specified password do not match, you can retrieve the valid username and password the first time the secret is rotated. Manage Single Account: This mode is suitable for the scenarios in which a privileged account or a manual O&M account is managed. In this mode, the current version of the secret may be temporarily unavailable when the secret is rotated. Click the Create Account tab, specify a username prefix, and then select an account type. You can select Standard Account or Privileged Account for the Account Type parameter. If you select Standard Account, you must select a database and specify the permissions of the account. Click the Import Existing Accounts tab, select a username, and then specify a password for the username.
   CMK	The key that is used to encrypt the current value of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces. A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Automatic Rotation	Specifies whether to enable automatic secret rotation.
   Rotation Period	The interval of automatic secret rotation. This setting is required only when you enable automatic rotation. The value ranges from 6 hours to 365 days. KMS periodically updates the secret based on the value of this parameter.
   Description	The description of the secret.
   Policy Settings	The policy settings of the secret. For more information, see Overview. You can use the default policy and then modify the policy based on your business requirements after you create the secret.

   Database secret (PolarDB)

   You can select only Create Single Secret. When you create a PolarDB secret, note that only new accounts in dual mode are supported. The new account supports only PolarDB for MySQL and PolarDB for PostgreSQL.

   Parameter	Description
   Database Type	The type of database secret that you want to create. Select PolarDB Secret.
   Secret Name	The name of the secret. The secret name is unique within the current region.
   PolarDB Cluster	The existing PolarDB cluster that you want to manage within your Alibaba Cloud account.
   Account Management	Only Manage Dual Accounts is supported. This mode is suitable for the scenarios in which the secret is used by applications to access the PolarDB cluster. In this mode, KMS manages two accounts that have identical permissions. This mode ensures that the connections between applications and the PolarDB cluster are not interrupted when the secret is rotated.
   Secret Value	Only Create Account is supported. The type of the new account is standard. After you select a PolarDB cluster, specify a username prefix, permissions, and a database for the new account. Note KMS does not immediately create accounts. KMS creates accounts after you double-check and confirm the secret information. The account name must be unique. Otherwise, the account cannot be managed in secrets.
   CMK	The key that is used to encrypt the current value of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces. A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Automatic Rotation	Specifies whether to enable automatic secret rotation.
   Rotation Period	The interval of automatic secret rotation. This setting is required only when you enable automatic rotation. The value ranges from 6 hours to 365 days. KMS periodically updates the secret based on the value of this parameter.
   Description	The description of the secret.
   Policy Settings	The policy settings of the secret. For more information, see Overview. You can use the default policy and then modify the policy based on your business requirements after you create the secret.

   Database secret (ApsaraDB for Redis)

   Create Single Secret and Create Bulk Secrets are supported. In the following example, Create Single Secret is selected.

   Parameter	Description
   Database Type	The type of database secret that you want to create. Select ApsaraDB for Redis Secrets.
   Secret Name	The name of the secret. The secret name is unique within the current region.
   ApsaraDB for Redis/Tair Instance	The existing ApsaraDB for Redis instance that you want to manage within your Alibaba Cloud account.
   Account Management	Only Manage Dual Accounts is supported.
   Secret Value	When you use KMS to manage the accounts of the ApsaraDB for Redis instance, you can manage only new accounts. Existing accounts cannot be managed. Account Name: Enter a username prefix. Then, KMS calls an ApsaraDB for Redis operation to create two accounts that have the same permissions. For example, if you enter the user username prefix, user and user _clone accounts are created. Permissions: Valid values are Read/Write and Read-Only. The two ApsaraDB for Redis accounts have the same permissions.
   CMK	The key that is used to encrypt the current value of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces. A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Automatic Rotation	Specifies whether to enable automatic secret rotation.
   Rotation Period	The interval of automatic secret rotation. This setting is required only when you enable Automatic Rotation. The value ranges from 6 hours to 365 days. KMS periodically updates the secret based on the value of this parameter.
   Description	The description of the secret.
   Policy Settings	The policy settings of the secret. For more information, see Overview. You can use the default policy and then modify the policy based on your business requirements after you create the secret.

   ECS secret

   Parameter	Description
   Secret Name	The name of the secret. The secret name is unique within the current region.
   Managed Instance	The existing ECS instance that you want to manage within your Alibaba Cloud account.
   Managed User	The name of an existing user on the ECS instance, such as the root user for Linux operating systems or the Administrator user for Windows operating systems.
   Initial Secret Value	The value cannot exceed 30,720 bytes in length, which is equivalent to 30 KB in size. Password: the password of the user that is used to log on to the ECS instance. Key Pair: the SSH key pair of the user that is used to log on to the ECS instance. Obtain an SSH key pair An SSH key pair that is created in ECS Private key: After you create an SSH key pair, the browser automatically downloads the private key file to your computer. The name of the file is in the Key pair name.pem format. For more information, see Create an SSH key pair. Public Key: For more information about how to view the information about a public key, see View public key information. An automatically-generated SSH key pair Save the private key and the public key of a key pair after the key pair is generated. For example, run the ssh-keygen command to generate and save a 3072-bit Rivest-Shamir-Adleman (RSA) key pair. ssh-keygen -t RSA -b 3072 -m PEM -f ~/.ssh/sshKey_demo -N "" The following files are generated: ~/.ssh/sshKey_demo: contains the private key. ~/.ssh/sshKey_demo.pub: contains the public key. Note Enter a valid secret value. If you enter an invalid secret value, the password or key pair that you retrieve from KMS cannot be used to log on to the ECS instance before the first time the ECS secret is rotated.
   CMK	The key that is used to encrypt the current value of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces. A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Automatic Rotation	Specifies whether to enable automatic secret rotation.
   Rotation Period	The interval of automatic secret rotation. This setting is required only when you enable automatic rotation. The value ranges from 1 hour to 365 days. KMS periodically updates the secret based on the value of this parameter.
   Description	The description of the secret.
   Policy Settings	The policy settings of the secret. For more information, see Overview. You can use the default policy and then modify the policy based on your business requirements after you create the secret.

Step 2: Retrieve the secret

In the following example, the Alibaba Cloud SDK for Java is used.

Preparations

1. Prepare an environment.

   Environment requirement

   Download and install Java Development Kit (JDK) 8 or later.

   Version check

   Run the java -version command on the terminal to check the JDK version.

2. Install the SDK for Java.

   Add the following Maven dependency to your project. Then, a Java package of Alibaba Cloud SDK is automatically downloaded from the Maven repository. Make sure that Alibaba Cloud SDK V2.0 is used.

   <dependency>
     <groupId>com.aliyun</groupId>
     <artifactId>kms20160120</artifactId>
     <version>1.2.3</version>
   </dependency>

3. Create a credential that can be used to call API operations.

   Alibaba Cloud SDK supports multiple RAM-based authentication methods. In this example, AccessKey pairs of RAM users are used. For more information about authentication methods, see Manage access credentials.

   1. Create an AccessKey pair for a RAM user in the RAM console. For more information, see Create an AccessKey pair.

      If an AccessKey pair is already created for the RAM user, skip this step.

   2. Grant the required permissions to the RAM user.

      For example, if the RAM user requires the permissions to retrieve a secret, you can attach the system policies AliyunKMSSecretUserAccess and AliyunKMSCryptoUserAccess to the RAM user. For more information, see Grant permissions to a RAM user.

      Note

      KMS provides the following permission configuration methods:

      • Identity-based policies: The policies in the preceding example are identity-based policies. Identity-based policies associate identities with corresponding permissions to implement access control. For more information, see Use RAM to implement access control.

      • Resource-based policies: Resource-based policies include key and secret policies. Such policies are directly associated with resources and are used to define access rules for specific resources. For more information, see Key policies and Secret policies.

4. Obtain the certificate authority (CA) certificate of the KMS instance.

   1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.

   2. In the upper part of the page that appears, click Instance CA Certificate.

      

5. Obtain the Virtual Private Cloud (VPC) endpoint of the instance.

   Record the VPC endpoint of the instance on the instance details page.

   

Secret retrieval