AsymmetricSign - Key Management Service - Alibaba Cloud Documentation Center

Operation description

Precautions

For information about the access policies that are required for a RAM user or RAM role 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 a VPC. This method requires you to enable Internet access. For more information, see Access keys 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

Shared gateway: This operation is limited to 200 queries per second (QPS) for each user. If the limit is exceeded, API calls are throttled, which may affect your business. We recommend that you call this operation at a reasonable rate.
Dedicated gateway: The QPS for each user is limited by the performance specifications of your KMS instance. For more information, see Performance metrics.

Description

This operation supports only asymmetric keys for which the Usage parameter is set to SIGN/VERIFY. The following table describes the supported signature algorithms.

KeySpec	Algorithm	Description
RSA_2048	RSA_PSS_SHA_256	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
RSA_2048	RSA_PKCS1_SHA_256	RSASSA-PKCS1-v1_5 using SHA-256
RSA_3072	RSA_PSS_SHA_256	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
RSA_3072	RSA_PKCS1_SHA_256	RSASSA-PKCS1-v1_5 using SHA-256
EC_P256	ECDSA_SHA_256	ECDSA on the P-256 Curve(secp256r1) with a SHA-256 digest
EC_P256K	ECDSA_SHA_256	ECDSA on the P-256K Curve(secp256k1) with a SHA-256 digest
EC_SM2	SM2DSA	SM2 elliptic curve digital signature algorithm

Note

According to the GB/T 32918.2 standard "Information security technology - SM2 elliptic curve public key cryptography - Part 2: Digital signature algorithm", when you calculate an SM2 signature, the value of the Digest parameter is not the SM3 hash value of the original message. Instead, the value is the SM3 hash value of the result of concatenating Z(A) and M. M is the original message to be signed. Z(A) is the hash value of user A, as defined in GB/T 32918.2.

This topic provides an example of how to use an asymmetric key with the key ID 5c438b18-05be-40ad-b6c2-3be6752c**** and the key version ID 2ab1a983-7072-4bbc-a582-584b5bd8**** to sign the digest ZOyIygCyaOW6GjVnihtTFtIS9PNmskdyMlNKiuy****= using the RSA_PSS_SHA_256 signature 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
KeyId	string	Yes	The globally unique identifier (GUID) of the customer master key (CMK). Note You can also specify the alias that is bound to the CMK. For more information, see Overview of aliases.	5c438b18-05be-40ad-b6c2-3be6752c****
KeyVersionId	string	Yes	The ID of the key version. The ID must be the GUID of the key version.	2ab1a983-7072-4bbc-a582-584b5bd8****
Algorithm	string	Yes	The signature algorithm.	RSA_PSS_SHA_256
Digest	string	Yes	The digest of the original message. The digest is generated using the hash algorithm that corresponds to the value of the Algorithm parameter. Note The value is Base64-encoded. For information about how to calculate a message digest, see the "Pre-signing: calculate a message digest" section of the Asymmetric digital signature topic.	ZOyIygCyaOW6GjVnihtTFtIS9PNmskdyMlNKiu****=
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 API calls and verify the permissions on the resources that you have and the validity of the request parameters. If you enable the dry-run feature, KMS always returns a failure response and a failure reason. The failure reasons include the following: DryRunOperationError: The request would have succeeded if the DryRun parameter is not configured. ValidationError: The specified parameters in the request are invalid. AccessDeniedError: You are not authorized to perform the operation on the KMS resource.	false

Response parameters

Parameter	Type	Description	Example
	object
KeyVersionId	string	The ID of the key version. The ID is the GUID of the key version.	2ab1a983-7072-4bbc-a582-584b5bd8****
KeyId	string	The GUID of the CMK. Note If you use an alias of the CMK in the request, the ID of the CMK to which the alias is bound is returned.	5c438b18-05be-40ad-b6c2-3be6752c****
Value	string	The generated signature. Note The value is Base64-encoded.	M2CceNZH00ZgL9ED/ZHFp21YRAvYeZHknJUc207OCZ0N9wNn9As4z2bON3FF3je+1Nu+2+/8Zj50HpMTpzYpMp2R93cYmACCmhaYoKydxylbyGzJR8y9likZRCrkD38lRoS40aBBvv/6iRKzQuo9EGYVcel36cMNg00VmYNBy3pa1rwg3gA4l3cy6kjayZja1WGPkVhrVKsrJMdbpl0ApLjXKuD8rw1n1XLCwCUEL5eLPljTZaAveqdOFQOiZnZEGI27qIiZe7I1fN8tcz6anS/gTM7xRKE++5egEvRWlTQQTJeApnPSiUPA+8ZykNdelQsOQh5SrGoyI4A5pq****==
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 and locate issues.	475f1620-b9d3-4d35-b5c6-3fbdd941423d

Examples

Success response

JSON format

{
  "KeyVersionId": "2ab1a983-7072-4bbc-a582-584b5bd8****",
  "KeyId": "5c438b18-05be-40ad-b6c2-3be6752c****",
  "Value": "M2CceNZH00ZgL9ED/ZHFp21YRAvYeZHknJUc207OCZ0N9wNn9As4z2bON3FF3je+1Nu+2+/8Zj50HpMTpzYpMp2R93cYmACCmhaYoKydxylbyGzJR8y9likZRCrkD38lRoS40aBBvv/6iRKzQuo9EGYVcel36cMNg00VmYNBy3pa1rwg3gA4l3cy6kjayZja1WGPkVhrVKsrJMdbpl0ApLjXKuD8rw1n1XLCwCUEL5eLPljTZaAveqdOFQOiZnZEGI27qIiZe7I1fN8tcz6anS/gTM7xRKE++5egEvRWlTQQTJeApnPSiUPA+8ZykNdelQsOQh5SrGoyI4A5pq****==",
  "RequestId": "475f1620-b9d3-4d35-b5c6-3fbdd941423d"
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidParameter	The specified parameter is not valid.	An invalid value is specified for the parameter.
404	InvalidAccessKeyId.NotFound	The Access Key ID provided does not exist in our records.
404	Forbidden.KeyNotFound	The specified Key is not found.	The error message returned because the specified CMK does not exist.
404	Forbidden.AliasNotFound	The specified Alias is not found.	The error message returned because the specified alias does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.