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, ApsaraDB RDS 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 settings. Secrets Manager periodically updates the secret to ensure the security of the secret.

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click 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 Secrets

     Parameter	Description
     Secret Name	The name of the secret.
     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 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.
     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 (:), and at signs (@). 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.
     Advanced Settings	The policy settings of the secret. Default Policy: If the secret is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy. If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the secret. If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1. Secrets created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the secrets. Secrets created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the secrets. Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the secret, select Custom Policy. Important Administrators and users do not consume Access Management Quota. Cross-account users consume Access Management Quota of the KMS instance. The consumed quota is calculated based on the number of Alibaba Cloud accounts. If you revoke the permissions, wait approximately 5 minutes and then query the quota. The consumed quota is restored. When you use a secret, you must have the permission to use the required key to decrypt the secret. An administrator can manage the secret but cannot retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by administrators { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:PutSecretValue", "kms:Update*", "kms:DeleteSecret", "kms:RestoreSecret", "kms:RotateSecret", "kms:TagResource", "kms:UntagResource" ] } ] } A user can retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] } A cross-account user can retrieve the secret value. You can select RAM users and RAM roles within other Alibaba Cloud accounts. RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: aacs:ram::119285303511****:user/testpolicyuser. RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole. Note After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the secret in RAM. Then, the RAM user or RAM role can use the secret. For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role. Permissions supported by cross-account users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] }

     Note

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

   • RAM Secrets

     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.
     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 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.
     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 (:), and at signs (@). 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 select Enable Automatic Rotation. KMS periodically updates the secret based on the value of this parameter.
     Description	The description of the secret.
     Advanced Settings	The policy settings of the secret. Default Policy: If the secret is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy. If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the secret. If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1. Secrets created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the secrets. Secrets created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the secrets. Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the secret, select Custom Policy. Important Administrators and users do not consume Access Management Quota. Cross-account users consume Access Management Quota of the KMS instance. The consumed quota is calculated based on the number of Alibaba Cloud accounts. If you revoke the permissions, wait approximately 5 minutes and then query the quota. The consumed quota is restored. When you use a secret, you must have the permission to use the required key to decrypt the secret. An administrator can manage the secret but cannot retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by administrators { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:PutSecretValue", "kms:Update*", "kms:DeleteSecret", "kms:RestoreSecret", "kms:RotateSecret", "kms:TagResource", "kms:UntagResource" ] } ] } A user can retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] } A cross-account user can retrieve the secret value. You can select RAM users and RAM roles within other Alibaba Cloud accounts. RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: aacs:ram::119285303511****:user/testpolicyuser. RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole. Note After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the secret in RAM. Then, the RAM user or RAM role can use the secret. For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role. Permissions supported by cross-account users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] }

   • ApsaraDB RDS Secrets

     Parameter	Description
     Secret Name	The name of the secret.
     RDS Instance	The existing ApsaraDB RDS instance that you want to manage within your Alibaba Cloud account.
     Secret Value	The value cannot exceed 30,720 bytes in length, which is equivalent to 30 KB in size. Manage Dual Accounts (recommended): This mode applies to 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 and Authorize Account tab, specify a username prefix, select a database, and then specify the permissions. Note KMS does not immediately create the accounts. KMS creates the 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 applies to 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 and Authorize 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 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.
     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 (:), and at signs (@). 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 select 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.
     Advanced Settings	The policy settings of the secret. Default Policy: If the secret is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy. If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the secret. If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1. Secrets created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the secrets. Secrets created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the secrets. Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the secret, select Custom Policy. Important Administrators and users do not consume Access Management Quota. Cross-account users consume Access Management Quota of the KMS instance. The consumed quota is calculated based on the number of Alibaba Cloud accounts. If you revoke the permissions, wait approximately 5 minutes and then query the quota. The consumed quota is restored. When you use a secret, you must have the permission to use the required key to decrypt the secret. An administrator can manage the secret but cannot retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by administrators { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:PutSecretValue", "kms:Update*", "kms:DeleteSecret", "kms:RestoreSecret", "kms:RotateSecret", "kms:TagResource", "kms:UntagResource" ] } ] } A user can retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] } A cross-account user can retrieve the secret value. You can select RAM users and RAM roles within other Alibaba Cloud accounts. RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: aacs:ram::119285303511****:user/testpolicyuser. RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole. Note After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the secret in RAM. Then, the RAM user or RAM role can use the secret. For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role. Permissions supported by cross-account users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] }

   • ECS Secrets

     Parameter	Description
     Secret Name	The name of the secret.
     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 when 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 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.
     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 (:), and at signs (@). 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 select 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.
     Advanced Settings	The policy settings of the secret. Default Policy: If the secret is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy. If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the secret. If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1. Secrets created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the secrets. Secrets created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the secrets. Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the secret, select Custom Policy. Important Administrators and users do not consume Access Management Quota. Cross-account users consume Access Management Quota of the KMS instance. The consumed quota is calculated based on the number of Alibaba Cloud accounts. If you revoke the permissions, wait approximately 5 minutes and then query the quota. The consumed quota is restored. When you use a secret, you must have the permission to use the required key to decrypt the secret. An administrator can manage the secret but cannot retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by administrators { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:PutSecretValue", "kms:Update*", "kms:DeleteSecret", "kms:RestoreSecret", "kms:RotateSecret", "kms:TagResource", "kms:UntagResource" ] } ] } A user can retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] } A cross-account user can retrieve the secret value. You can select RAM users and RAM roles within other Alibaba Cloud accounts. RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: aacs:ram::119285303511****:user/testpolicyuser. RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole. Note After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the secret in RAM. Then, the RAM user or RAM role can use the secret. For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role. Permissions supported by cross-account users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] }

Step 2: Retrieve the secret

You can use Alibaba Cloud SDK, KMS Instance SDK, and secret SDKs including secret client, secret Java Database Connectivity (JDBC) client, and RAM secret plug-in to retrieve the secret. For more information, see SDK references. In this topic, the secret client for Java is used as an example. For more information, see Secret client.

Preparations

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.

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();
        }
    }
}