AsymmetricEncrypt - Key Management Service - Alibaba Cloud Documentation Center

Operation description

Precautions

For information about the permissions that are required to call this operation, see Resource Access Management.
You can call this operation using a shared gateway or a dedicated gateway. For more information, see Alibaba Cloud SDK.
- Shared gateway: You can access KMS over the Internet or using a VPC domain name. To access KMS over the Internet, you must enable Internet access. For more information, see Access a key in a KMS instance over the Internet.
- Dedicated gateway: You can access KMS using the private endpoint of KMS (<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com).

QPS limits

If you use a shared gateway: The number of queries per second (QPS) for a single user is limited to 200. If the limit is exceeded, API calls are throttled. This may affect your business. We recommend that you plan your API calls to avoid exceeding this limit.
If you use a dedicated gateway: The QPS limit for a single user depends on the computing performance specifications of your KMS instance. For more information, see Performance metrics.

Description

This operation supports only asymmetric keys that have the Usage parameter set to ENCRYPT/DECRYPT. The following table describes the supported encryption algorithms.

KeySpec	Algorithm	Description	Maximum number of bytes that can be encrypted
RSA_2048	RSAES_OAEP_SHA_256	RSAES-OAEP using SHA-256 and MGF1 with SHA-256	190
RSA_2048	RSAES_OAEP_SHA_1	RSAES-OAEP using SHA1 and MGF1 with SHA1	214
RSA_3072	RSAES_OAEP_SHA_256	RSAES-OAEP using SHA-256 and MGF1 with SHA-256	318
RSA_3072	RSAES_OAEP_SHA_1	RSAES-OAEP using SHA1 and MGF1 with SHA1	342
EC_SM2	SM2PKE	SM2 elliptic curve public key encryption algorithm	6047

In this example, the plaintext SGVsbG8gd29ybGQ= is encrypted using an asymmetric key with the key ID key-hzz630494463ejqjx****, the key version ID 2ab1a983-7072-4bbc-a582-584b5bd8****, and the RSAES_OAEP_SHA_1 encryption algorithm.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request parameters

Parameter	Type	Required	Description	Example
Plaintext	string	Yes	The plaintext to be encrypted. The value must be Base64-encoded.	SGVsbG8gd29ybGQ=
KeyId	string	Yes	The ID of the key. You can also specify the alias or the Amazon Resource Name (ARN) of the key. For more information about aliases, see Manage aliases. Note To access a key of another Alibaba Cloud account, you must specify the ARN of the key. The key ARN is in the format of `acs:kms:${region}:${account}:key/${keyid}`.	5c438b18-05be-40ad-b6c2-3be6752c****
KeyVersionId	string	Yes	The ID of the key version. The ID must be a globally unique identifier. Note You can call the ListKeyVersions operation to obtain the key version ID.	2ab1a983-7072-4bbc-a582-584b5bd8****
Algorithm	string	Yes	The encryption algorithm.	RSAES_OAEP_SHA_1
DryRun	string	No	Specifies whether to enable the dry run feature. true: enables the feature. false (default): disables the feature. The dry run feature is used to test the API call and verify the permissions on the specified resources and the validity of the request parameters. If you enable the dry run feature, KMS always returns a failed result and a failure reason. The failure reasons include the following: DryRunOperationError: The request would have succeeded if the DryRun parameter was not specified. ValidationError: The specified parameters in the request are invalid. AccessDeniedError: You are not authorized to perform this operation on the KMS resource.	false

Response parameters

Parameter	Type	Description	Example
	object
KeyVersionId	string	The version number of the master key that is used to encrypt the plaintext.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	The ID of the key. If you specify an alias or an ARN of the key in the request, the ID of the key is returned.	5c438b18-05be-40ad-b6c2-3be6752c****
CiphertextBlob	string	The ciphertext of the data that is encrypted. The value is Base64-encoded.	BQKP+1zK6+ZEMxTP5qaVzcsgXtWplYBKm0NXdSnB5FzliFxE1bSiu4dnEIlca2JpeH7yz1/S6fed630H+hIH6DoM25fTLNcKj+mFB0Xnh9m2+HN59Mn4qyTfcUeadnfCXSWcGBouhXFwcdd2rJ3n337bzTf4jm659gZu3L0i6PLuxM9p7mqdwO0cKJPfGVfhnfMz+f4alMg79WB/NNyE2lyX7/qxvV49ObNrrJbKSFiz8Djocaf0IESNLMbfYI5bXjWkJlX92DQbKhibtQW8ZOJ//ZC6t0AWcUoKL6QDm/dg5koQalcleRinpB+QadFm894sLbVZ9+N4GVsv1Wbjwg==
RequestId	string	The ID of the request, which is a unique identifier generated by Alibaba Cloud for the request. You can use the request ID to troubleshoot issues.	475f1620-b9d3-4d35-b5c6-3fbdd941423d

Examples

Success response

JSON format

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "5c438b18-05be-40ad-b6c2-3be6752c****",
  "CiphertextBlob": "BQKP+1zK6+ZEMxTP5qaVzcsgXtWplYBKm0NXdSnB5FzliFxE1bSiu4dnEIlca2JpeH7yz1/S6fed630H+hIH6DoM25fTLNcKj+mFB0Xnh9m2+HN59Mn4qyTfcUeadnfCXSWcGBouhXFwcdd2rJ3n337bzTf4jm659gZu3L0i6PLuxM9p7mqdwO0cKJPfGVfhnfMz+f4alMg79WB/NNyE2lyX7/qxvV49ObNrrJbKSFiz8Djocaf0IESNLMbfYI5bXjWkJlX92DQbKhibtQW8ZOJ//ZC6t0AWcUoKL6QDm/dg5koQalcleRinpB+QadFm894sLbVZ9+N4GVsv1Wbjwg==",
  "RequestId": "475f1620-b9d3-4d35-b5c6-3fbdd941423d"
}

Error codes

HTTP status code	Error code	Error message	Description
400	Rejected.UnsupportedOperation	Unsupported operation.	The operation is not supported.
404	Forbidden.AliasNotFound	The specified Alias is not found.	The error message returned because the specified alias does not exist.
404	Forbidden.KeyNotFound	The specified Key is not found.	The error message returned because the specified CMK does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.