8. CMOX_SM2

8.1. SM2 public method prototypes

group CMOX_ECC_SM2_PUBLIC_METHODS

Functions

cmox_ecc_retval_t cmox_sm2_keyGen ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , uint8_t * P_pPrivKey , size_t * P_pPrivKeyLen , uint8_t * P_pPubKey , size_t * P_pPubKeyLen )

Generate private and public keys to use with ECDSA.

Note

the private key is derived from the random in the following way: 

privkey = (random >> ((WORD_NBIT - N_MSW_NBIT) & 7)) + 1
, where: random is the input random buffer (interpreted as a big-endian integer), WORD_NBIT is the bitsize of a cpu word, N_MSW_NBIT is the bitlength of the most significant word of the parameter N of the curve.

Note

If P_RandomLen is not enough, an error is returned and P_pPrivKeyLen contains the minimum number of bytes of random to provide (and is also the minimum length of P_pPrivKey), while P_pPubKeyLen contains the minimum length of P_pPubKey.

Parameters :

  • P_pEccCtx – [in] Context for ECC operations

  • P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

    • CMOX_ECC_SM2_LOWMEM

    • CMOX_ECC_SM2_HIGHMEM

    • CMOX_ECC_SM2TEST_LOWMEM

    • CMOX_ECC_SM2TEST_HIGHMEM

  • P_pRandom – [in] Buffer of random bytes

  • P_RandomLen – [in] Byte length of the random buffer

  • P_pPrivKey – [out] Buffer with the private key (in range [1; N - 2])

  • P_pPrivKeyLen – [out] Byte length of the private key

  • P_pPubKey – [out] Buffer with the public key

  • P_pPubKeyLen – [out] Byte length of the public key

Return values :

  • CMOX_ECC_SUCCESS – Everything OK

  • CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

  • CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

  • CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

  • CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

  • CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_sm2_computeZA ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pIDA , uint16_t P_ENTLA , const uint8_t * P_pPubKey , size_t P_PubKeyLen , uint8_t * P_pZA , size_t * P_pZALen )

Compute ZA = HASH(ENTLA || IDA || a || b || xG || yG || xA || yA), that is the value to hash, together with the message, to obtain the digest to provide to cmox_sm2_sign and cmox_sm2_verify.

Parameters :

  • P_pEccCtx – [in] Context for ECC operations

  • P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

    • CMOX_ECC_SM2_LOWMEM

    • CMOX_ECC_SM2_HIGHMEM

    • CMOX_ECC_SM2TEST_LOWMEM

    • CMOX_ECC_SM2TEST_HIGHMEM

  • P_pIDA – [in] Buffer with ID (e.g. email “user@domain.com”) of the user

  • P_ENTLA – [in] Bit length of the user ID (usually, multiple of 8)

  • P_pPubKey – [in] Buffer with the public key (both X and Y)

  • P_PubKeyLen – [in] Byte length of the public key

  • P_pZA – [out] Buffer with ZA

  • P_pZALen – [out] Byte length of ZA (optional parameter)

Return values :

  • CMOX_ECC_SUCCESS – Everything OK

  • CMOX_ECC_ERR_INTERNAL – Something went wrong during internal computations (e.g. hash)

  • CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

  • CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

  • CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

  • CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_sm2_sign ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pRandom , size_t P_RandomLen , const uint8_t * P_pPrivKey , size_t P_PrivKeyLen , const uint8_t * P_pDigest , size_t P_DigestLen , uint8_t * P_pSignature , size_t * P_pSignatureLen )

Generate a signature, using ECDSA.

Note

the internal value k, used as scalar and multiplied by the base point, is derived from the random in the following way: 

k = (random >> ((WORD_NBIT - N_MSW_NBIT) & 7)) + 1
, where: random is the input random buffer (interpreted as a big-endian integer), WORD_NBIT is the bitsize of a cpu word, N_MSW_NBIT is the bitlength of the most significant word of the parameter N of the curve.

Note

If P_RandomLen is not enough, an error is returned and P_pSignatureLen contains the minimum number of bytes of random to provide (and is also the minimum length of P_pPrivKey, and half the length of P_pSignature).

Parameters :

  • P_pEccCtx – [in] Context for ECC operations

  • P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

    • CMOX_ECC_SM2_LOWMEM

    • CMOX_ECC_SM2_HIGHMEM

    • CMOX_ECC_SM2TEST_LOWMEM

    • CMOX_ECC_SM2TEST_HIGHMEM

  • P_pRandom – [in] Buffer of random bytes

  • P_RandomLen – [in] Byte length of the random buffer

  • P_pPrivKey – [in] Buffer with the private key

  • P_PrivKeyLen – [in] Byte length of the private key

  • P_pDigest – [in] Buffer with the digest to sign

  • P_DigestLen – [in] Byte length of the digest

  • P_pSignature – [out] Buffer with the signature (concatenation of R and S)

  • P_pSignatureLen – [out] Byte length of the signature

Return values :

  • CMOX_ECC_SUCCESS – Everything OK

  • CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

  • CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

  • CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

  • CMOX_ECC_ERR_WRONG_RANDOM – Random material too short or not valid for the functionality

  • CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

cmox_ecc_retval_t cmox_sm2_verify ( cmox_ecc_handle_t * P_pEccCtx , const cmox_ecc_impl_t P_CurveParams , const uint8_t * P_pPubKey , size_t P_PubKeyLen , const uint8_t * P_pDigest , size_t P_DigestLen , const uint8_t * P_pSignature , size_t P_SignatureLen , uint32_t * P_pFaultCheck )

Verify a signature, using ECDSA.

Note

P_pFaultCheck value, if the parameter is provided, MUST be checked to be equal to the retval, and both MUST be equal to the successful value. P_pFaultCheck MUST be checked only if the main result is successful, and has no relevance if the main result is not successful. Every comparison (both for the return value and for P_pFaultCheck) must be done against the success value, and not comparing the value with the failure value. Indeed, in presence of faults, especially P_pFaultCheck, could be a dirty value.

Parameters :

  • P_pEccCtx – [in] Context for ECC operations

  • P_CurveParams – [in] Curve Parameters and point functions This parameter can be one of the following:

    • CMOX_ECC_SM2_LOWMEM

    • CMOX_ECC_SM2_HIGHMEM

    • CMOX_ECC_SM2TEST_LOWMEM

    • CMOX_ECC_SM2TEST_HIGHMEM

  • P_pPubKey – [in] Buffer with the public key

  • P_PubKeyLen – [in] Byte length of the public key

  • P_pDigest – [in] Buffer with the digest to sign

  • P_DigestLen – [in] Byte length of the digest

  • P_pSignature – [in] Buffer with the signature (concatenation of R and S)

  • P_SignatureLen – [in] Byte length of the signature

  • P_pFaultCheck – [out] Optional value to check, together with the retval, to verify if some fault happened

Return values :

  • CMOX_ECC_AUTH_SUCCESS – Signature verified

  • CMOX_ECC_AUTH_FAIL – Signature NOT verified

  • CMOX_ECC_ERR_MATHCURVE_MISMATCH – Mathematical function set is not compatible with current ECC curve

  • CMOX_ECC_ERR_ALGOCURVE_MISMATCH – Curve is not compatible with current functionality

  • CMOX_ECC_ERR_BAD_PARAMETERS – Some NULL/wrong/empty parameter or Construct API not called

  • CMOX_ECC_ERR_MEMORY_FAIL – Not enough memory

  • CMOX_ECC_ERR_INVALID_SIGNATURE – Input signature corrupted or not in the expected format

  • CMOX_ECC_ERR_INVALID_PUBKEY – Public key not in a valid format