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 key is created. For more information, see Getting started with keys.

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 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	The value cannot exceed 30,720 bytes in length, which is equivalent to 30 KB in size. 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 review 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 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 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: 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 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

You can use Alibaba Cloud SDK, KMS Instance SDK, and secret SDKs including the secret client, the secret Java Database Connectivity (JDBC) client, and the RAM secret plug-in to retrieve the secret. For more information, see SDK references.

In the following section, the secret client for Java is used as an example. For more information, see Secret client.

Prerequisites

1. Install the secret client for Java.

   Add dependencies to the project by using Maven and install the secret client. Sample code:

   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>alibabacloud-secretsmanager-client</artifactId>
       <version>x.x.x</version>
   </dependency>

   Note

   Make sure that the version of the secret client is 1.3.2 or later.

2. Configure the runtime parameters for the secret client by using the secretsmanager.properties configuration file.

   The following sample code provides an example on how to use an environment variable to obtain the password of the client key file:

   cache_client_dkms_config_info=[{"regionId":"<your KMS instance region>","endpoint":"<your KMS instance  endpoint>","passwordFromEnvVariable":"<your_password_env_variable>","clientKeyFile":"<your client key file path>","ignoreSslCerts":false,"caFilePath":"<your KMS instanceCA certificate file path>"}]

   Note

   You must configure an environment variable on the server on which your application is deployed. The name of the environment variable is the value that is specified in the passwordFromEnvVariable field, and the value of the environment variable is the password of the client key file. The method that is used to configure environment variables varies based on the operating system. For more information, see Configure environment variables in Linux, macOS, and Windows.

Secret retrieval

import com.aliyuncs.kms.secretsmanager.client.SecretCacheClient;
import com.aliyuncs.kms.secretsmanager.client.SecretCacheClientBuilder;
import com.aliyuncs.kms.secretsmanager.client.exception.CacheSecretException;
import com.aliyuncs.kms.secretsmanager.client.model.SecretInfo;

public class SecretCacheClientSample {

    public static void main(String[] args) {
        try {
            SecretCacheClient client = SecretCacheClientBuilder.newClient();
            SecretInfo secretInfo = client.getSecretInfo("#secretName#");
            System.out.println(secretInfo);
        } catch (CacheSecretException e) {
            e.printStackTrace();
        }
    }
}