Integrating Alibaba Cloud SDK allows you to call the OpenAPI for management operations, such as creating instances and keys. You can also perform business operations, such as encryption, decryption, and retrieving secret values. This topic helps you to use Key Management Service (KMS) by integrating Alibaba Cloud SDK.
Access overview
When integrating Alibaba Cloud SDK for KMS, note that management operations are accessible only through the shared gateway, while business operations are accessible through both the shared and dedicated gateways. The following figure illustrates these access methods.
Differences between shared and dedicated gateways for accessing KMS
The table below lists the key differences between accessing a shared gateway and a dedicated gateway when using Alibaba Cloud SDK to access KMS for business operations.
Item | Shared gateway | Dedicated gateway | |
Network | Public network or VPC network. | KMS private network. | |
Performance | KMS has a quota that limits the number of API requests per second. For example, the QPS for encryption and decryption is fixed at 1000. | Instead of limiting the number of API requests, KMS processes them in best effort mode. The maximum available computing and storage resources are used during processing. When you purchase a KMS instance, you can select an appropriate QPS based on your business requirements. | |
Supported APIs | All OpenAPIs for cryptographic operations and retrieving secret values. | All OpenAPIs for cryptographic operations and retrieving secret values, except ReEncrypt. | |
Network access control | The VPC ID (condition key: acs:SourceVpc) and IP addresses within the VPC (condition key: acs:VpcSourceIp) are supported for network access control. | The VPC ID (condition key: acs:SourceVpc) and source IP addresses within a VPC (condition key: acs:VpcSourceIp) are not supported for network access control. If you require network access control, contact your account manager. | |
Authorization | When using STS authentication to retrieve secrets, authorization is applied only to the GetSecretValue operation, not to the Decrypt operation. Other authentication methods apply authorization to both operations. |
During the secrets retrieval process, both the GetSecretValue and Decrypt operations are authorized. | |
Log auditing | ActionTrail | Simple Log Service (SLS) | |
SDK configurations | Endpoint | During client initialization, the shared gateway endpoint must be configured with one of the following formats:
| During client initialization, the dedicated gateway endpoint must be configured following the format: |
CA certificate | Not required. |
| |
Supported OpenAPI
The management operations are only accessible through the shared gateway, while business operations can be accessed through both the shared and dedicated gateways.
To perform cryptographic operations through the shared gateway, you must first enable public access.
indicates it is supported, and × indicates it is not.
API operation | Description | Shared gateway | Dedicated gateway |
Encrypts plaintext by using a symmetric key. |
|
| |
Generates a random data key that is used to encrypt on-premises data. |
|
| |
Generates a random data key, which can be used to encrypt on-premises data. |
|
| |
Encrypts a data key by using a specific public key, and exports the data key. |
|
| |
Randomly generates a data key, and uses a KMS key and a public key to encrypt the data key. This operation returns the ciphertext of the data key encrypted using both the data key and the public key. |
|
| |
Decrypts ciphertext. |
|
| |
Re-encrypts ciphertext. When you call this operation, KMS uses a different key to re-encrypt the generated plaintext or data key, and then returns the new ciphertext. |
| × | |
Generates a signature by using an asymmetric key. |
|
| |
Verifies a signature by using an asymmetric key. |
|
| |
Decrypts data by using an asymmetric key. |
|
| |
Encrypts data by using an asymmetric key. |
|
| |
Retrieves the public key of an asymmetric key pair. You can use the public key to encrypt local data and verify signatures. |
|
|
indicates it is supported, and × indicates it is not.
API operation | Description | Shared gateway | Dedicated gateway |
Retrieves a secret value. |
|
|
Endpoint
<KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com
Replace <KMS_INSTANCE_ID> with your actual KMS Instance ID.
Authentication method
When accessing the OpenAPI through a shared gateway or dedicated gateway using Alibaba Cloud SDK, the authentication methods are the same. RAM-based identity authentication methods are supported, such as AccessKey (AK), STS Token, RamRoleArn, and ECS instance RAM roles. For more information, see Manage access credentials.
AccessKey
By default, an Alibaba Cloud account serves as an administrator with the authority to manage all associated Alibaba Cloud resources. The permissions tied to the Alibaba Cloud account cannot be altered. If an AccessKey pair associated with an Alibaba Cloud account is compromised, the resources of the account are at risk. For enhanced security, we do not advise creating an AccessKey pair for an Alibaba Cloud account. Instead, create a RAM user with API access mode enabled and generate an AccessKey pair for this user. By granting the RAM user only necessary permissions in accordance with the principle of least privilege, they can perform API operations to access Alibaba Cloud resources. For more information, see Create an AccessKey pair.
Log on to the RAM console by using an Alibaba Cloud account, a RAM administrator with the AliyunRAMFullAccess policy attached, or a RAM user granted permissions to manage AccessKey pairs.
In the left-side navigation pane, choose Identities > Users, and click on the desired RAM user.
In the Authentication tab, click Create AccessKey and follow the instructions to complete the creation.
Grant the RAM user access to KMS. You have two methods to complete the grant.
Method 1: Through identity-based policies
KMS provides system-defined permission policies that can be attached to RAM users. For more information, see System policies for KMS. You can also create custom policies.
Method 2: Through resource-based policies
KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. This lets you control which Alibaba Cloud accounts, RAM users, and RAM roles have permission to manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.
STS token
By using STS services, a temporary access credential can be issued to RAM users or RAM roles, allowing them to access KMS with permissions specified by the policy for a limited validity period. After the expiration period, the credential will automatically become invalid.
Log on to the RAM console by using an Alibaba Cloud account or a RAM user who has administrative rights.
Grant AliyunSTSAssumeRoleAccess permission to a RAM user or Grant AliyunSTSAssumeRoleAccess permission to a RAM role.
Grant the RAM user access to KMS. You have two methods to complete the grant.
Method 1: Through identity-based policies
KMS provides system-defined permission policies that can be attached to RAM users. For more information, see System policies for KMS. You can also create custom policies.
Method 2: Through resource-based policies
KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. This lets you control which Alibaba Cloud accounts, RAM users, and RAM roles have permission to manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.
Use the RAM user or RAM role to call the AssumeRole interface of the STS service to obtain temporary access credentials.
RamRoleArn
RAM users or cloud services can obtain temporary permissions by assuming roles instead of directly using long-term access keys, thereby reducing the risk of key leakage. For instance, in temporary data processing tasks, RAM users or cloud services can temporarily assume a role with a specific RamRoleArn. RamRoleArn is the ARN information of the RAM role. Once the task is completed, the role's permissions are revoked, further mitigating the risk of exposure.
Log on to the RAM console by using an Alibaba Cloud account or a RAM role who has administrative rights.
Grant the RAM role access to KMS. You have two methods to complete the grant.
Method 1: Through identity-based policies
KMS provides system-defined permission policies that can be attached to RAM users. For more information, see System policies for KMS. You can also create custom policies.
Method 2: Through resource-based policies
KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. This lets you control which Alibaba Cloud accounts and RAM roles have permission to manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.
View the RamRoleArn about a RAM role.
The RamRoleArn follows the format
acs:ram::$accountID:role/$roleName, where$accountIDis the Alibaba Cloud account and$roleNameis the RAM role name.
ECS instance RAM roles
An ECS instance RAM role is a regular service role that is attached to ECS instances, and the trusted entity of an instance RAM role is ECS. You can use an instance RAM role to obtain Security Token Service (STS) tokens as temporary access credentials from within an ECS instance without the need to provide an AccessKey pair. Then, you can use the temporary access credentials to call the OpenAPI operations of KMS.
Log on to the RAM console, and create an instance RAM role whose Principal Type is an Alibaba Cloud service.
Principal Type: Select Cloud Service.
Principal Name: Select Elastic Compute Service / ECS.
Grant the RAM user access to KMS. You have two methods to complete the grant.
Method 1: Through identity-based policies
KMS provides system-defined permission policies that can be attached to RAM users. For more information, see System policies for KMS. You can also create custom policies.
Method 2: Through resource-based policies
KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. This lets you control which Alibaba Cloud accounts, RAM users, and RAM roles have permission to manage or use KMS keys and secrets. For more information, see Key policies and Secret policies.
Log on to the ECS console, and attach the instance RAM role to an ECS instance.
Supported programming languages
The table below lists supported languages and their SDK download links and reference documentation.