Alibaba Cloud SDK supports both management operations (creating instances and keys) and business operations (encryption, decryption, and secret retrieval) for KMS. Management operations use the shared gateway only; business operations support both shared and dedicated gateways.
Access overview
Management operations are accessible only through the shared gateway. Business operations are accessible through both the shared and dedicated gateways.
Shared vs. dedicated gateway
The following table compares the shared and dedicated gateways for KMS business operations.
|
Item |
Shared gateway |
Dedicated gateway |
|
|
Network |
Public network or VPC network. |
KMS private network. |
|
|
Performance |
API requests are subject to per-second quotas. Example: encryption and decryption QPS is fixed at 1,000. |
No per-request quota. Requests are processed in best-effort mode using all available computing and storage resources. You select the QPS capacity when purchasing a KMS instance. |
|
|
Supported APIs |
All cryptographic operations and secret retrieval APIs. |
All cryptographic operations and secret retrieval APIs, except ReEncrypt. |
|
|
Network access control |
Supports VPC ID (condition key: acs:SourceVpc) and VPC IP addresses (condition key: acs:VpcSourceIp) for network access control. |
Does not support VPC ID (condition key: acs:SourceVpc) or source IP addresses within a VPC (condition key: acs:VpcSourceIp) for network access control. Contact your account manager if you require this capability. |
|
|
Authorization |
With STS authentication, authorization applies only to GetSecretValue, not Decrypt. Other authentication methods authorize both operations. |
Both GetSecretValue and Decrypt are authorized during secret retrieval. |
|
|
Log auditing |
ActionTrail |
Simple Log Service (SLS) |
|
|
SDK configurations |
Endpoint |
During client initialization, configure the shared gateway endpoint in one of the following formats:
|
During client initialization, configure the dedicated gateway endpoint in the format: |
|
CA certificate |
Not required. |
|
|
Supported APIs
Management operations use the shared gateway only. Business operations support both shared and dedicated gateways.
Management operations
Service management
API | Title | Description |
DescribeAccountKmsStatus | Queries the status of Key Management Service (KMS) within your Alibaba Cloud account. | |
OpenKmsService | Activates Key Management Service (KMS) for your Alibaba Cloud account. |
Instances management
API | Title | Description |
ListKmsInstances | Queries all KMS instances in the current region. | |
ConnectKmsInstance | Enables a Key Management Service (KMS) instance. | |
GetKmsInstance | Retrieves the details of a KMS instance. | |
UpdateKmsInstanceBindVpc | Updates the VPC bindings of a KMS instance. | |
ReleaseKmsInstance | Releases a pay-as-you-go KMS instance. | |
GetDefaultKmsInstance | Queries the default KMS instance in a specified region. |
Key management
|
API |
Title |
Description |
|
CreateKey |
Creates a customer master key (CMK) for envelope encryption, digital signatures, or other cryptographic operations. |
|
|
ListKeys |
Queries the IDs and ARNs of all CMKs in the current region. |
|
|
DescribeKey |
Queries the metadata of a CMK, such as the key state, usage, and rotation configuration. |
|
|
UpdateKeyDescription |
Updates the description of a CMK. |
|
|
EnableKey |
Enables a key to encrypt and decrypt data. |
|
|
DisableKey |
Disables a key. |
|
|
CreateAlias |
Creates an alias for a key. |
|
|
ListAliases |
Queries all aliases in the current region for the current account. |
|
|
ListAliasesByKeyId |
Queries all aliases that are bound to a key. |
|
|
DeleteAlias |
Deletes an alias. |
|
|
UpdateAlias |
Binds an existing alias to a different customer master key (CMK) ID. |
|
|
GetParametersForImport |
Queries the parameters that are used to import key material for a customer master key (CMK). |
|
|
ImportKeyMaterial |
Imports externally generated key material into a CMK whose origin is EXTERNAL. |
|
|
DeleteKeyMaterial |
Deletes the imported key material from a CMK. After deletion, the CMK enters the PendingImport state until you re-import key material. |
|
|
ScheduleKeyDeletion |
Deletes a specified customer master key (CMK). |
|
|
CancelKeyDeletion |
Cancels the deletion task of a CMK. |
|
|
SetDeletionProtection |
Enables or disables deletion protection for a customer master key (CMK). |
|
|
UpdateRotationPolicy |
Updates the automatic rotation policy of a CMK. |
|
|
DescribeKeyVersion |
Queries the metadata of a specific CMK version. |
|
|
CreateKeyVersion |
Creates a version for a customer master key (CMK). |
|
|
ListKeyVersions |
Queries all versions of a specified CMK. |
|
|
SetKeyPolicy |
Sets the key policy for a CMK in a KMS instance. |
|
|
GetKeyPolicy |
Queries the key policy of a CMK in a KMS instance. |
Secrets management
|
API |
Title |
Description |
|
ListSecrets |
Queries all secrets in the current region. |
|
|
DeleteSecret |
Deletes a secret. |
|
|
CreateSecret |
Creates a secret and stores its initial version. |
|
|
UpdateSecret |
Updates the metadata of a secret. |
|
|
UpdateSecretVersionStage |
Moves a version stage label to a different version of a secret. |
|
|
UpdateSecretRotationPolicy |
Updates the rotation policy of a secret. |
|
|
DescribeSecret |
Queries the metadata of a secret. |
|
|
ListSecretVersionIds |
Queries all version IDs and stage labels of a specified secret. |
|
|
GetRandomPassword |
Generates a random password string. |
|
|
PutSecretValue |
Stores a new version of a secret value for a generic secret. |
|
|
RestoreSecret |
Restores a deleted secret. |
|
|
RotateSecret |
Immediately rotates a secret. |
|
|
SetSecretPolicy |
Sets the access policy for a secret in a KMS instance. |
|
|
GetSecretPolicy |
Queries the access policy of a specified secret in a KMS instance. |
Tag management
API | Title | Description |
GetKmsInstanceQuotaInfos | Queries the quota usage and limits of a KMS instance. | |
ListResourceTags | Queries the tags of a customer master key (CMK). | |
TagResource | Adds tags to a CMK, secret, or certificate. | |
UntagResource | Removes tags from a CMK, secret, or certificate. |
Applications management
API | Title | Description |
CreateNetworkRule | Creates a network access rule to configure the private IP addresses or private CIDR blocks that are allowed to access a Key Management Service (KMS) instance. | |
ListNetworkRules | Queries all network access rules in the current region. | |
DescribeNetworkRule | Retrieves the details of a network access rule. | |
UpdateNetworkRule | Updates a network access rule. | |
DeleteNetworkRule | Deletes a network access rule. | |
CreatePolicy | Creates a permission policy to configure the keys and secrets that are allowed to access. | |
ListPolicies | Queries all permission policies in the current region. | |
DescribePolicy | Retrieves the details of a permission policy. | |
UpdatePolicy | Updates a permission policy. | |
DeletePolicy | Deletes a permission policy. | |
CreateApplicationAccessPoint | Creates an application access point (AAP) | |
ListApplicationAccessPoints | Queries all application access points (AAPs) in the current region. | |
DescribeApplicationAccessPoint | Retrieves the details of an application access point (AAP). | |
UpdateApplicationAccessPoint | Updates the information about an application access point (AAP). | |
DeleteApplicationAccessPoint | Deletes an application access point (AAP). | |
CreateClientKey | Creates a client key. | |
ListClientKeys | Queries all client keys within an AAP. | |
GetClientKey | Retrieves information about a client key. | |
DeleteClientKey | Deletes a client key. |
Business operations-Cryptographic operations
To perform cryptographic operations through the shared gateway, you must first enable public access.
|
API |
Description |
Shared gateway |
Dedicated gateway |
|
Generates a random data key for envelope encryption. The data key is returned in both plaintext and ciphertext forms. |
|
|
|
|
Generates a random data key, encrypts it by using a CMK and a public key that you specify, and returns both ciphertexts. |
|
|
|
|
Encrypts plaintext by using a symmetric CMK. |
|
|
|
|
Decrypts ciphertext that was encrypted by using a CMK. |
|
|
|
|
Re-encrypts ciphertext under a different CMK without exposing the plaintext. |
|
|
|
|
Exports a data key encrypted by a CMK. The data key is re-encrypted by a public key that you specify for secure transmission. |
|
|
|
|
Generates a random data key in only ciphertext form, without the plaintext copy. |
|
|
|
|
Generates a digital signature by using an asymmetric CMK. |
|
|
|
|
Verifies a digital signature by using the public key of an asymmetric CMK. |
|
|
|
|
Encrypts data by using the public key of an asymmetric CMK. |
|
|
|
|
Decrypts data by using the private key of an asymmetric CMK. |
|
|
|
|
Retrieves the public key of an asymmetric key. You can use the public key to encrypt data or verify a signature on your device. |
|
|
Business operations-Retrieving secret values
|
API |
Description |
Shared gateway |
Dedicated gateway |
|
Retrieves a secret value. |
|
|
Supported programming languages
The following table lists SDK download links and documentation for each supported language.