Digital signature verification

Functions
UFR_STATUS DL_API	DigitalSignatureVerifyHash (uint32_t digest_alg, uint32_t padding_alg, uint32_t cypher_alg, IN const uint8_t *tbs, uint32_t tbs_len, IN const uint8_t *signature, uint32_t signature_len, IN const void *sig_params, uint32_t sig_params_len, IN const uint8_t *pub_key, uint32_t pub_key_len, IN const void *pub_key_params, uint32_t pub_key_params_len)

Detailed Description

Function Documentation

DigitalSignatureVerifyHash()

UFR_STATUS DL_API DigitalSignatureVerifyHash	(	uint32_t	digest_alg,
		uint32_t	padding_alg,
		uint32_t	cypher_alg,
		IN const uint8_t *	tbs,
		uint32_t	tbs_len,
		IN const uint8_t *	signature,
		uint32_t	signature_len,
		IN const void *	sig_params,
		uint32_t	sig_params_len,
		IN const uint8_t *	pub_key,
		uint32_t	pub_key_len,
		IN const void *	pub_key_params,
		uint32_t	pub_key_params_len )

This function is used to verify the digital signature of the pre-hashed value or some relatively short plain text message. If there is no errors during the verification process and digital signature correspond to the "To Be Signed" (TBS) data array and public cryptographic key, the function returns UFR_OK status. "To Be Signed" is just a colloquial term for already signed data, which is the origin of the digital signature. In case of wrong digital signature, function returns CRYPTO_SUBSYS_WRONG_SIGNATURE status. Function can return following status codes in case of various errors:

• CRYPTO_SUBSYS_NOT_INITIALIZED
• CRYPTO_SUBSYS_INVALID_HASH_ALGORITHM
• CRYPTO_SUBSYS_INVALID_PADDING_ALGORITHM
• CRYPTO_SUBSYS_INVALID_CIPHER_ALGORITHM
• CRYPTO_SUBSYS_INVALID_SIGNATURE_PARAMS
• CRYPTO_SUBSYS_INVALID_RSA_PUB_KEY
• CRYPTO_SUBSYS_INVALID_ECC_PUB_KEY
• CRYPTO_SUBSYS_INVALID_ECC_PUB_KEY_PARAMS
• CRYPTO_SUBSYS_UNKNOWN_ECC_CURVE
• CRYPTO_SUBSYS_SIGNATURE_VERIFICATION_ERROR For digest_alg use one of the values declared in E_SIGNER_DIGESTS enumeration: enum E_SIGNER_DIGESTS { ALG_NULL = 0, ALG_SHA, ALG_SHA_256, ALG_SHA_384, ALG_SHA_512, ALG_SHA_224, ALG_SHA_512_224, ALG_SHA_512_256, SIG_DIGEST_MAX_SUPPORTED }; ALG_SHA is the designator for the SHA-1 algorithm. For padding_alg use one of the values declared in E_SIGNER_RSA_PADDINGS enumeration: enum E_SIGNER_RSA_PADDINGS { PAD_NULL = 0, PAD_PKCS1_V1_5, PAD_PKCS1_PSS, SIG_PAD_MAX_SUPPORTED }; PAD_PKCS1 is an alias of the PAD_PKCS1_V1_5 padding algorithm: #define PAD_PKCS1 PAD_PKCS1_V1_5 For cipher_alg use one of the values declared in E_SIGNER_CIPHERS enumeration: enum E_SIGNER_CIPHERS { SIG_CIPHER_RSA = 0, SIG_CIPHER_ECDSA, SIG_CIPHER_MAX_SUPPORTED }; When the signer cipher algorithm is SIG_CIPHER_ECDSA, padding_alg is ignored and you can freely use PAD_NULL i.e. value 0 as a padding_alg. ECDSA data alignment in use is described in RFC6979 (section 2.3. - Integer Conversions).

Parameters

digest_alg	in the E_SIGNER_DIGESTS enumeration.
padding_alg	in the E_SIGNER_RSA_PADDINGS enumeration. When the signer cipher algorithm is SIG_CIPHER_ECDSA, padding_alg is ignored and you can freely use PAD_NULL i.e. value 0 as a padding_alg. ECDSA data alignment in use is described in RFC6979 (section 2.3. - Integer Conversions).
cypher_alg	in the E_SIGNER_CIPHERS enumeration. tbs Pointer to the “To Be Signed“ data array i.e. hash or relatively short plain text message whose digital signature is being verified. "To Be Signed" is just a colloquial term for already signed data, which is the origin of the digital signature. tbs_len Length of the “To Be Signed“ array (in bytes). signature Pointer to the signature array. signature_len Length of the signature array (in bytes). sig_params Pointer to the additional signature parameters. Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this pointer should point to the unsigned 4-byte integer containing the value of the cryptographic salt length. sig_params_len Length of the additional signature parameters (in bytes). Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this value should be 4 i.e. size of unsigned 4-byte integer. In other cases this parameter is ignored. pub_key Pointer to the public key array. In the case of the RSA public key, this array should contain key modulus (‘N’). pub_key_len Length of the public key parameter pub_key (in bytes). pub_key_params Pointer to the additional public key parameters. In the case of the RSA public key, this array should contain a public key exponent array (‘e’). In the case of the ECC public key, this array should contain an elliptic curve definition array. To set an elliptic curve definition array you can use SetEllipticCurveByIndex() or SetEllipticCurveByName() functions. pub_key_params_len Length of the additional public key parameters (in bytes).
tbs	Pointer to the “To Be Signed“ data array i.e. hash or relatively short plain text message whose digital signature is being verified. "To Be Signed" is just a colloquial term for already signed data, which is the origin of the digital signature.
tbs_len	Length of the “To Be Signed“ array (in bytes). signature Pointer to the signature array. signature_len Length of the signature array (in bytes). sig_params Pointer to the additional signature parameters. Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this pointer should point to the unsigned 4-byte integer containing the value of the cryptographic salt length. sig_params_len Length of the additional signature parameters (in bytes). Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this value should be 4 i.e. size of unsigned 4-byte integer. In other cases this parameter is ignored. pub_key Pointer to the public key array. In the case of the RSA public key, this array should contain key modulus (‘N’). pub_key_len Length of the public key parameter pub_key (in bytes). pub_key_params Pointer to the additional public key parameters. In the case of the RSA public key, this array should contain a public key exponent array (‘e’). In the case of the ECC public key, this array should contain an elliptic curve definition array. To set an elliptic curve definition array you can use SetEllipticCurveByIndex() or SetEllipticCurveByName() functions. pub_key_params_len Length of the additional public key parameters (in bytes).
signature	Pointer to the signature array.
signature_len	Length of the signature array (in bytes). sig_params Pointer to the additional signature parameters. Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this pointer should point to the unsigned 4-byte integer containing the value of the cryptographic salt length. sig_params_len Length of the additional signature parameters (in bytes). Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this value should be 4 i.e. size of unsigned 4-byte integer. In other cases this parameter is ignored. pub_key Pointer to the public key array. In the case of the RSA public key, this array should contain key modulus (‘N’). pub_key_len Length of the public key parameter pub_key (in bytes). pub_key_params Pointer to the additional public key parameters. In the case of the RSA public key, this array should contain a public key exponent array (‘e’). In the case of the ECC public key, this array should contain an elliptic curve definition array. To set an elliptic curve definition array you can use SetEllipticCurveByIndex() or SetEllipticCurveByName() functions. pub_key_params_len Length of the additional public key parameters (in bytes).
sig_params	Pointer to the additional signature parameters. Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this pointer should point to the unsigned 4-byte integer containing the value of the cryptographic salt length.
sig_params_len	Length of the additional signature parameters (in bytes). Additional signature parameters are in use only when padding_alg is PAD_PKCS1_PSS and in that case this value should be 4 i.e. size of unsigned 4-byte integer. In other cases this parameter is ignored. pub_key Pointer to the public key array. In the case of the RSA public key, this array should contain key modulus (‘N’). pub_key_len Length of the public key parameter pub_key (in bytes). pub_key_params Pointer to the additional public key parameters. In the case of the RSA public key, this array should contain a public key exponent array (‘e’). In the case of the ECC public key, this array should contain an elliptic curve definition array. To set an elliptic curve definition array you can use SetEllipticCurveByIndex() or SetEllipticCurveByName() functions. pub_key_params_len Length of the additional public key parameters (in bytes).
pub_key	Pointer to the public key array. In the case of the RSA public key, this array should contain key modulus (‘N’).
pub_key_len	Length of the public key parameter pub_key (in bytes). pub_key_params Pointer to the additional public key parameters. In the case of the RSA public key, this array should contain a public key exponent array (‘e’). In the case of the ECC public key, this array should contain an elliptic curve definition array. To set an elliptic curve definition array you can use SetEllipticCurveByIndex() or SetEllipticCurveByName() functions. pub_key_params_len Length of the additional public key parameters (in bytes).
pub_key_params	Pointer to the additional public key parameters. In the case of the RSA public key, this array should contain a public key exponent array (‘e’). In the case of the ECC public key, this array should contain an elliptic curve definition array. To set an elliptic curve definition array you can use SetEllipticCurveByIndex() or SetEllipticCurveByName() functions.
pub_key_params_len	Length of the additional public key parameters (in bytes).

Returns

Operation status