AsymmetricVerify - Key Management Service - Alibaba Cloud Documentation Center

Operation description

Precautions

For information about the access policy required for a RAM user or RAM role to call this API 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 through a VPC. To access KMS over the Internet, you must enable the public endpoint. For more information, see Access KMS instances 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 queries per second (QPS) limit for this operation is 200 for a single user. If you exceed this limit, API calls are throttled, which may impact your business. We recommend that you manage your call frequency to stay within the QPS limit.
If you use a dedicated gateway, the QPS limit for this operation for a single user is determined by the computing 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 lists 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

In accordance with the GBT32918 standard, when an SM2 signature is calculated, 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 generated by concatenating Z(A) and M. In this formula, M is the original message to be signed, and Z(A) is the hash value of user A as defined in GBT32918.

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 verify the signature `M2CceNZH00ZgL9ED/ZHFp21YRAvYeZHknJUc207OCZ0N9wNn9As4z2bON3FF3je+1Nu+2+/8Zj50HpMTpzYpMp2R93cYmACCmhaYoKydxylbyGzJR8y9likZRCrkD38lRoS40aBBvv/6iRKzQuo9EGYVcel36cMNg00VmYNBy3pa1rwg3gA4l3cy6kjayZja1WGPkVhrVKsrJMdbpl0ApLjXKuD8rw1n1XLCwCUEL5eLPljTZaAveqdOFQOiZnZEGI27qIiZe7I1fN8tcz6anS/gTM7xRKE++5egEvRWlTQQTJeApnPSiUPA+8ZykNdelQsOQh5SrGoyI4A5pq****==` for the digest `ZOyIygCyaOW6GjVnihtTFtIS9PNmskdyMlNKiuyjfzw=` 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 that is generated using the hash algorithm that corresponds to the value of Algorithm to hash the original message. Note The value is Base64-encoded.	ZOyIygCyaOW6GjVnihtTFtIS9PNmskdyMlNKiuy****=
Value	string	Yes	The signature value to be verified. Note The value is Base64-encoded.	M2CceNZH00ZgL9ED/ZHFp21YRAvYeZHknJUc207OCZ0N9wNn9As4z2bON3FF3je+1Nu+2+/8Zj50HpMTpzYpMp2R93cYmACCmhaYoKydxylbyGzJR8y9likZRCrkD38lRoS40aBBvv/6iRKzQuo9EGYVcel36cMNg00VmYNBy3pa1rwg3gA4l3cy6kjayZja1WGPkVhrVKsrJMdbpl0ApLjXKuD8rw1n1XLCwCUEL5eLPljTZaAveqdOFQOiZnZEGI27qIiZe7I1fN8tcz6anS/gTM7xRKE++5egEvRWlTQQTJeApnPSiUPA+8ZykNdelQsOQh5SrGoyI4A5pq****==
DryRun	string	No	Specifies whether to perform a dry run. true: performs a dry run. false (default): does not perform a dry run. A dry run is used to test API calls and verify whether you have the permissions to access the specified resources and whether the request parameters are valid. If you perform a dry run, KMS always returns a failure response that indicates the cause of the failure. The following failure causes are included: DryRunOperationError: The request would have succeeded if the DryRun parameter is 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 ID of the key version that is used for signature verification.	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 is returned.	5c438b18-05be-40ad-b6c2-3be6752c****
Value	boolean	Indicates whether the signature is valid.	true
RequestId	string	The ID of the request, which is a unique identifier generated by Alibaba Cloud for the request. You can use the 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****",
  "Value": true,
  "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	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.
404	InvalidAccessKeyId.NotFound	The Access Key ID provided does not exist in our records.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.