Manage generic secrets - Key Management Service - Alibaba Cloud Documentation Center

Use Alibaba Cloud CLI to manage the full lifecycle of generic secrets in Key Management Service (KMS) Secrets Manager: create, list, retrieve values, retrieve metadata, delete, restore, and rotate.

To manage generic secrets from the KMS console or by calling API operations directly, see the KMS console guide and API reference.

Operations overview

Operation	CLI command	Description
Create	`CreateSecret`	Create a secret and store its initial version
List	`ListSecrets`	List all secrets in the current region
Get value	`GetSecretValue`	Retrieve the plaintext value of the current version
Get metadata	`DescribeSecret`	Retrieve configuration metadata without decrypting the value
Delete	`DeleteSecret`	Schedule or immediately delete a secret
Restore	`RestoreSecret`	Cancel a pending deletion within the recovery window

Prerequisites

Before you begin, ensure that you have:

Alibaba Cloud CLI installed and configured
(Required for custom encryption key only) The kms:GenerateDataKey permission on the customer master key (CMK)

Create a generic secret

Secrets Manager encrypts each secret value with a CMK. Use the default CMK for zero-configuration encryption, or specify your own CMK for explicit key control.

Without a custom encryption key

When no encryption key is specified, Secrets Manager uses the default CMK to encrypt the secret value.

aliyun kms CreateSecret \
    --SecretName db_cred \
    --SecretData "{\"uname\": \"alice\", \"pwd\": \"12****\"}" \
    --VersionId v1

Expected response:

{
  "Arn": "acs:kms:cn-shanghai:111760096384****:secret/db_cred",
  "RequestId": "ef0e4234-085c-4676-9ab6-159f2338aaf0",
  "SecretName": "db_cred",
  "SecretType": "Generic",
  "VersionId": "v1"
}

With a custom encryption key

When you specify an encryption key, Secrets Manager generates a data key from the CMK and uses that data key to encrypt the secret value.

The kms:GenerateDataKey permission on the specified CMK is required.

aliyun kms CreateSecret \
    --SecretName ssh_key \
    --SecretData ssh-key-blob \
    --VersionId v1 \
    --EncryptionKeyId Example-CMK-Id

Expected response:

{
  "Arn": "acs:kms:cn-shanghai:111760096384****:secret/ssh_key",
  "RequestId": "ef0e4234-085c-4676-9ab6-159f2338aaf0",
  "SecretName": "ssh_key",
  "SecretType": "Generic",
  "VersionId": "v1"
}

List generic secrets

Returns all generic secrets in your Alibaba Cloud account for the current region, with pagination.

aliyun kms ListSecrets

Expected response:

{
    "SecretList": {
        "Secret": [
            {
                "SecretName": "db_cred",
                "SecretType": "Generic",
                "CreateTime": "2020-01-22T03:55:18Z",
                "UpdateTime": "2020-01-22T03:55:18Z"
            },
            {
                "SecretName": "ssh_key",
                "SecretType": "Generic",
                "CreateTime": "2020-01-22T03:57:09Z",
                "UpdateTime": "2020-01-22T03:57:09Z"
            }
        ]
    },
    "RequestId": "75aebbde-be68-4cab-ba6e-e4925b61****",
    "PageNumber": 1,
    "PageSize": 10,
    "TotalCount": 2
}

Get a secret value

Retrieves the plaintext value of the current version of a secret.

aliyun kms GetSecretValue --SecretName ssh_key

Expected response:

{
  "CreateTime": "2021-07-08T05:51:50Z",
  "RequestId": "1415f5c7-ecb2-495e-8051-4cd466022c1f",
  "SecretData": "{\"test\":\"test\"}",
  "SecretDataType": "text",
  "SecretName": "ssh_key",
  "SecretType": "Generic",
  "VersionId": "v1",
  "VersionStages": {
    "VersionStage": [
      "ACSCurrent"
    ]
  }
}

VersionStages.VersionStage shows the lifecycle stage of the returned version. ACSCurrent indicates this is the active version.

Get secret metadata

Returns the configuration metadata for a secret — such as its ARN, encryption key, and timestamps — without decrypting the secret value.

aliyun kms DescribeSecret --SecretName ssh_key

Expected response:

{
    "Arn": "acs:kms:cn-shanghai:111760096384****:secret/ssh_key",
    "SecretName": "ssh_key",
    "SecretType": "Generic",
    "EncryptionKeyId": "Example-CMK-Id",
    "Description": "",
    "CreateTime": "2020-01-22T03:57:09Z",
    "UpdateTime": "2020-01-22T03:57:09Z",
    "RequestId": "ca61398f-e61e-4552-aa7e-957955f6125s"
}

Delete a generic secret

By default, DeleteSecret performs a soft delete: the secret enters a recovery window during which you can restore it with RestoreSecret. Force deletion permanently removes the secret with no recovery option.

Scenario	Flag	Recovery
Default recovery window	(none)	Within 30 days
Custom recovery window	`--RecoveryWindowInDays <days>`	Within the specified number of days
No recovery	`--ForceDeleteWithoutRecovery true`	Cannot be recovered

Delete with the default recovery window

Schedules the secret for permanent deletion 30 days from now. Restore it any time before the PlannedDeleteTime.

aliyun kms DeleteSecret --SecretName ssh_key

Expected response:

{
    "SecretName": "ssh_key",
    "RequestId": "3e54b02b-6461-46bb-afd5-dbd29d96eead",
    "PlannedDeleteTime": "2020-02-21T04:24:04.58616562Z"
}

PlannedDeleteTime is the deadline for recovery. Call RestoreSecret before this time to cancel the deletion.

Delete with a custom recovery window

Schedules deletion after the specified number of days. The example below sets a 7-day window.

aliyun kms DeleteSecret --SecretName ssh_key --RecoveryWindowInDays 7

Expected response:

{
    "SecretName": "ssh_key",
    "RequestId": "95ec4f18-8f97-4fd5-b7c6-1588979dse4s",
    "PlannedDeleteTime": "2020-01-29T04:25:14.165242211Z"
}

Force delete (no recovery)

Deletes the secret immediately and permanently. This cannot be undone.

Warning

Force deletion is irreversible. Confirm you no longer need the secret before proceeding.

aliyun kms DeleteSecret --SecretName ssh_key --ForceDeleteWithoutRecovery true

Expected response:

{
    "SecretName": "ssh_key",
    "RequestId": "75efc9c3-8e21-4e38-b6e4-486886be1546",
    "PlannedDeleteTime": "2020-01-22T12:28:22.006884739+08:00"
}

Restore a deleted secret

Cancels a pending deletion and restores the secret to its active state. This only works within the recovery window — after PlannedDeleteTime, the secret cannot be recovered.

aliyun kms RestoreSecret --SecretName ssh_key

Expected response:

{
    "RequestId": "12770cee-92af-42f5-88e0-cbaa7e0c1254",
    "SecretName": "ssh_key"
}

What's next

Rotate generic secrets — learn the typical rotation scenario and how to trigger it