All Products
Search

This Product

    Key Management Service:Manage and use generic secrets

    Document Center

    Key Management Service:Manage and use generic secrets

    Last Updated:Apr 16, 2024

    Generic secrets are basic secrets that are supported by Key Management Service (KMS). You can store sensitive data such as account passwords, AccessKey pairs, OAuth secrets, and tokens as generic secrets. A generic secret can have multiple versions so that you can update the secret. This prevents sensitive data leaks that are caused by hardcoded secrets. This topic describes how to manage and use generic secrets.

    Generic secret rotation

    You cannot enable automatic rotation on a custom schedule for generic secrets in KMS. However, you can use Function Compute to fulfill this purpose. For more information, see Use Function Compute to rotate generic secrets. If you want an instant secret rotation, you can store the secret value of a new version by using the KMS console or calling the PutSecretValue API operation.

    Warning

    Each generic secret can have up to 10 versions. If a generic secret has more than 10 versions, KMS automatically deletes the earliest version in a rolling manner.

    Prerequisites

    Step 1: Create a generic secret

    When you create a generic secret, KMS sets the secret to the default ACSCurrent stage.

    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. Click the Generic Secrets tab, select the required instance ID from the Instance ID drop-down list, and then click Create Secret. In the panel that appears, configure parameters based on your business requirements and click OK.

      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",
            ]
        }
    ]
}

    Step 2: Integrate applications with generic secrets

    Alibaba Cloud provides the KMS SDK, KMS Instance SDK, and Secrets Manager Client to help you obtain secret values. You can integrate applications with generic secrets by using the SDKs. For more information about SDKs, see SDK references.

    Note

    • We recommend that you use Secrets Manager Client. Secrets Manager Client encapsulates secret cache, best practices, and design patterns based on the Secrets Manager API. This way, developers can easily integrate the capabilities of Secrets Manager into business systems. For more information, see Secrets Manager Client.

    • If you want to perform management and control operations, such as creating generic secrets and modifying the tags of generic secrets, you can use only the KMS SDK.

    Related operations

    Rotate a generic secret

    You cannot configure rotation information when you create generic secrets. If you want an instant rotation, you must store a new secret version by using the KMS console or calling the PutSecretValue API operation.

    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. Click the Generic Secrets tab, select the required instance ID from the Instance ID drop-down list, find the desired secret, and then click Details in the Actions column.

    3. In the Versions section, click Store Secret Value.

    4. In the Store Secret Value dialog box, configure the Version and Secret Value parameters and click OK.

      Important

      After you add a new secret version to the generic secret, the generic secret is immediately rotated. By default, the operation that is used to obtain the secret value in KMS returns the secret value of the new version.

    Delete a generic secret

    Before you delete a generic secret, make sure that the generic secret is no longer used. You can schedule deletion of a generic secret or immediately delete a generic secret.

    Warning

    Before you delete a generic secret, make sure that the generic secret is no longer in use. If you delete a generic secret that is in use, service failures may occur.

    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. Click the Generic Secrets tab, select the required instance ID from the Instance ID drop-down list, find the desired secret, and then click Schedule Deletion in the Actions column.

    3. In the Schedule Deletion dialog box, select a method to delete the secret and click OK.

      • If you select Schedule Deletion, configure Retention Period (7 to 30 Days). When the scheduled deletion period ends, KMS deletes the secret.

      • If you select Delete Immediately, the system immediately deletes the secret.

      During the scheduled deletion period, you can click Restore Secret in the Actions column to cancel the deletion.

    Add tags for secrets

    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.

    Add tags for a secret

    Solution

    Description

    Method 1: Add tags on the Secrets page

    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. Click a tab based on the type of your secret, select the required instance ID from the Instance ID drop-down list, find the desired secret, and then click the image.png icon in the Tag column.

    3. Click Add. In the Edit Tag dialog box, enter multiple Tag Key and Tag Value, and click OK. In the message that appears, click Close.

      In the Edit Tag dialog box, you can modify the tag values and remove multiple tags at a time.

    Method 2: Add tags on the Secret Details page

    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. Click a tab based on the type of your secret. Select the required instance ID from the Instance ID drop-down list, find the desired secret, and then click Details in the Actions column.

    3. On the Secret Details page, click the image.png icon next to Tag.

    4. In the Edit Tag dialog box, enter multiple Tag Key and Tag Value and click OK. In the message that appears, click Close.

      In the Edit Tag dialog box, you can modify the tag values and remove multiple tags at a time.

    Configure tags for multiple secrets at a time

    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. Click a tab based on the type of your secret, select the required instance ID from the Instance ID drop-down list, and then select the desired secrets from the secret list.

      • Add tags: In the lower part of the secret list, click Add Tag. In the Add Tag dialog box, enter multiple Tag Key and Tag Value, and click OK. In the message that appears, click Close.

      • Remove tags: In the lower part of the secret list, click Remove Tag. In the Batch Remove dialog box, select the tags that you want to remove and click Remove. In the message that appears, click Close.

    FAQ

    What do I do if a secret is unavailable or if Rejected.Unavailable is returned when I call a secret-related API operation?