.. _gfpecsignsm2:

GFpECSignSM2
============


Computes a digital signature over a message digest using the SM2 scheme.


Syntax
------


IppStatus ippsGFpECSignSM2(const IppsBigNumState\* pMsgDigest, const
IppsBigNumState\* pRegPrivate, const IppsBigNumState\* pEphPrivate,
IppsBigNumState\* pSignR, IppsBigNumState\* pSignS, IppsGFpECState\*
pEC, Ipp8u\* pScratchBuffer);


Include Files
-------------


``ippcp.h``


Parameters
----------


.. list-table:: 
   :header-rows: 0

   * - pMsgDigest   
     - Pointer to the message digest ``msg`` to be digitally signed, that is, to be encrypted with a private key.
   * - pRegPrivate   
     - Pointer to the regular private key of the signer.
   * - pEphPrivate   
     - Pointer to the ephemeral private key of the signer.
   * - pSignR   
     - Pointer to the integer ``r`` of the digital signature.
   * - pSignS   
     - Pointer to the integer ``s`` of the digital signature.
   * - pEC   
     - Pointer to the context of the elliptic curve.
   * - pScratchBuffer   
     - Pointer to the scratch buffer.




Description
-----------


The function computes two big numbers ``r`` and ``s`` that form the
digital signature over a message digest ``msg``.


The digital signature is computed using the SM2 scheme
[`SM2 <bibliography.html>`__].


The regular private key ``regPrivKey`` and the ephemeral private key
``ephPrivKey`` can be generated by the functions
`GFpECPrivateKey <gfpecprivatekey-gfpecpublickey-gfpectstkeypair.html>`__ and
`GFpECPublicKey <gfpecpublickey.html>`__ with
only the requirement that the key ``regPrivKey`` be different from the
key ``ephPrivKey``.


The elliptic curve domain parameters must be hitherto defined by the
functions:
`GFpECInitStd <gfpecinitstd.html>`__,
`GFpECInit <gfpecinit.html>`__,
`GFpECSet <gfpecset.html>`__, or
`GFpECSetSubgroup <gfpecsetsubgroup.html>`__.


Return Values
-------------


.. list-table:: 
   :header-rows: 0

   * - ippStsNoErr   
     - Indicates no error. Any other value indicates an error or warning.
   * - ippStsNullPtrErr   
     - Indicates an error condition if any of the specified pointers is NULL.
   * - ippStsContextMatchErr   
     - Indicates an error condition if any of the contexts pointed to by pMsgDigest, pRegPrivate, pEphPrivate, pSignR, pSignS, or pEC does not match the operation.
   * - ippStsMessageErr   
     - Indicates an error condition if the value of ``msg`` pointed to by pMsgDigest is negative.
   * - ippStsRangeErr   
     - Indicates an error condition if any of the parameters pointed to by pSignR or pSignS has a memory size that is smaller than the order ``n`` of the elliptic curve base point ``G``.
   * - ippStsIvalidPrivateKey   
     - Indicates an error condition in the following cases:
     
       * Any of the parameters pointed to by ``pRegPrivate`` or ``pEphPrivate`` has a memory size that is smaller than the order n of the elliptic curve base point G.
       * Value of any of the private keys is greater than or equal to the order n of the elliptic curve base point G.
       
   * - ippStsNotSupportedModeErr   
     - Indicates an error condition if the finite field GFp under the elliptic curve is not prime.
   * - ippStsEphemeralKeyErr   
     - Indicates an error condition if values of the ephemeral keys ``ephPrivKey`` and ``ephPubKey`` are not valid: the digital signature calculation returns ``r``\ =0 or ``s``\ =0 as a result.