.. _gfpecsignnr:


GFpECSignNR
===========


Computes the digital signature over a message digest (the Nyberg-Rueppel
scheme).


Syntax
------


IppStatus ippsGFpECSignNR(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 ecrypted 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 of size produced by *ippsGFpECScratchBufferSize*.




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


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


The scheme used to compute the digital signature is an elliptic curve
analogue of the El-Gamal Digital Signature scheme with the message
recovery (the Nyberg-Rueppel signature scheme).


The regular private key ``regPrivKey`` and the ephemeral private key
``ephPrivKey`` can be generated by the functions
:ref:`GFpECPrivateKey <gfpecprivatekey-gfpecpublickey-gfpectstkeypair>` and
:ref:`GFpECPublicKey <gfpecpublickey>` 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:
:ref:`GFpECInitStd <gfpecinitstd>`,
:ref:`GFpECInit <gfpecinit>`,
:ref:`GFpECSet <gfpecset>`, or
:ref:`GFpECSetSubgroup <gfpecsetsubgroup>`.


For more information on digital signatures, please refer to the
:term:`ANSI <[ANSI]>`
standard.

The *ippsGFpECScratchBufferSize* function should be called with *nScalars* equal to at least 1 to get the valid *pScratchBuffer*.

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 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 falls outside the range of [1, ``n``-1] where ``n`` is the order of the elliptic curve base point ``G``.
   * - ippStsRangeErr
     - Indicates an error condition if any of the parameters pointed to by pSignR or pSignS has a memory size that is less than the order ``n`` of the elliptic curve base point ``G``.
   * - ippStsIvalidPrivateKey
     - Indicates an error condition if any of the parameters pointed to by pRegPrivate or pEphPrivate has a memory size that is less than 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.
   * - ippStsErr
     - Indicates an error condition if the ephemeral private key is bad.



