Use Alibaba Cloud CLI to call Key Management Service-Key Management Service(KMS)-阿里云帮助中心

Alibaba Cloud CLI (Alibaba Cloud Command Line Interface) is a general-purpose command-line tool built on OpenAPI. You can use Alibaba Cloud CLI to automate the management and maintenance of Key Management Service. This topic uses calling the ListKmsInstances API to query a list of KMS instances as an example to describe the steps for using Alibaba Cloud CLI to call Key Management Service.

Prerequisites

Before you begin, make sure you are familiar with Alibaba Cloud CLI. For more information, see What is Alibaba Cloud CLI.

Install Alibaba Cloud CLI

Installation packages are available for Windows, Linux, and macOS. Select the installation method for your operating system.

Windows: Install Alibaba Cloud CLI on Windows.
Linux: Install, update, and uninstall Alibaba Cloud CLI.
macOS: Install Alibaba Cloud CLI on macOS.

You can also use Cloud Shell to test Alibaba Cloud CLI commands. For more information about Cloud Shell, see What is Cloud Shell?.

Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has permissions to access and manage all API operations, which creates a security risk. We strongly recommend that you create a RAM identity, grant it the minimum permissions required based on the principle of least privilege, and use the RAM identity to make API calls. For more information about the policies supported by Key Management Service, see system policies and custom policies.

Before you use Alibaba Cloud CLI, you must configure your identity credentials and a default region ID. Alibaba Cloud CLI supports multiple types of identity credentials. For more information, see Configure and manage credentials. This topic uses an AccessKey pair as an example. Perform the following steps:

Create a RAM user and an AccessKey. You will use the AccessKey to configure your identity credentials. For more information, see Create a RAM user and Create an AccessKey.
Grant permissions to the RAM user. For this example, you must grant the AliyunKMSReadOnlyAccess permission, which grants read-only access to Key Management Service. For more information, see Manage RAM user permissions.
Get an available region ID. Alibaba Cloud CLI sends API requests to the region that you specify. For a list of regions where Key Management Service is available, see Endpoints.

Note
When you use Alibaba Cloud CLI, you can add the --region option to a command to specify a region for the request. This option overrides the region specified in your default profile and environment variables. For more information, see Command-line options.
Use the AccessKey of the RAM user to configure a profile named AkProfile. For more information, see Configure and manage credentials.

Generate a sample CLI command

Go to the ListKmsInstances page in OpenAPI Explorer.
On the Parameters tab, enter the request parameters. Then, click the CLI Example tab to view the generated sample command.
Copy the sample command or run it in Cloud Shell:
- Click the Run Command button to open Cloud Shell and run the command.
- Click the Copy button to copy the sample command to the clipboard. You can then paste the command into a local shell to run it.
  Note
  - If you copy the sample command to a local shell for debugging, check the parameter format. For more information about Alibaba Cloud CLI command parameter formats, see Understand command parameters.
  - OpenAPI Explorer adds the --region option to the generated sample by default. When you copy the command to a local environment, Alibaba Cloud CLI uses the region specified by this option, overriding the region in your default profile and environment variables. You can remove or keep this option as needed.

The generated sample command is aliyun kms ListKmsInstances --region cn-hangzhou. The input parameters include PageNumber and PageSize.

Call APIs

Example 1: List Key Management Service APIs

The following example shows how to use the --help option to list the Key Management Service API operations supported by Alibaba Cloud CLI. You can also view the supported API operations in the API overview.

Run the command.
```
aliyun kms --help
```

The command returns the following output.

Product: Kms (Key Management Service)
Version: 2016-01-20
Available Api List:
    AsymmetricDecrypt            Decrypts data by using an asymmetric key.
    AsymmetricEncrypt            Encrypts data by using an asymmetric key.
    AsymmetricSign               Generates a signature by using an asymmetric key.
    AsymmetricVerify             Verifies a signature by using an asymmetric key.
    CancelKeyDeletion            Cancels a scheduled key deletion.
    CertificatePrivateKeyDecrypt Decrypts ciphertext by using the private key of an X.509 certificate.
    CertificatePrivateKeySign    Generates a signature for a message or message digest by using the private key of an X.509 certificate.
    CertificatePublicKeyEncrypt  Encrypts plaintext by using the public key of an X.509 certificate.
    CertificatePublicKeyVerify   Verifies a message signature by using the public key of an X.509 certificate.
    ConnectKmsInstance
    CreateAlias                  Creates an alias for a customer master key (CMK).
    CreateApplicationAccessPoint Creates an application access point.
    CreateCertificate            Creates a certificate.
    CreateClientKey
    CreateKey                    Creates a CMK.
    CreateKeyVersion             Creates a key version for a CMK.

Example 2: Query KMS instances

The following example shows how to use Alibaba Cloud CLI to run the ListKmsInstances command to query KMS instances in Key Management Service.

Run the command.

aliyun kms ListKmsInstances --region cn-hangzhou --PageNumber 1 --PageSize 10

The command returns the following output.

{
  "KmsInstances": {
    "KmsInstance": [
      {
        "KmsInstanceArn": "acs:kms:cn-hangzhou:141339776561****:keystore/kst-hzz66c5811c4c1wpv****",
        "KmsInstanceId": "kst-hzz66c5811c4c1wpv****"
      }
    ]
  },
  "TotalCount": 1,
  "PageNumber": 1,
  "PageSize": 10,
  "RequestId": "8b640712-ab78-47ca-b648-55b665ee51bf"
}

Note

If a Key Management Service API call returns an error, use the returned error code to verify your request parameters and values.

You can also use the request ID from the response or the SDK error message with Alibaba Cloud OpenAPI Diagnostics to troubleshoot the issue.

Cryptographic operations not available through the CLI

Starting from March 31, 2025, the Encrypt and GenerateDataKey API operations of shared KMS (KMS 1.0) are deprecated. If you call these operations by using Alibaba Cloud CLI (for example, aliyun kms Encrypt), the call fails and returns an UnsupportedOperation error.

Symmetric encryption is required to encrypt a plaintext value such as a password. AsymmetricEncrypt does not apply to this scenario because it uses an asymmetric key.

Decrypt is not affected by this change and remains available through Alibaba Cloud CLI.

To encrypt data, migrate to a KMS instance SDK. KMS instance SDKs connect over a VPC and authenticate by using a ClientKey.

For example, if you want to encrypt a password and pass the ciphertext to the kms_encrypted_password parameter, use the KMS instance SDK to generate the ciphertext. For more information, see Use a CMK to encrypt and decrypt data online.