.. _gfpeckeyexchangesm2_sharedkey:


GFpECKeyExchangeSM2_SharedKey
=============================

Computes a shared key between two participants of the cryptosystem. 

Syntax
-------

IppStatus ippsGFpECKeyExchangeSM2_SharedKey(Ipp8u* pSharedKey, int sharedKeySize, Ipp8u* pSSelf, const IppsBigNumState* pPrvKey, IppsBigNumState* pEphPrvKey,    IppsGFpECKeyExchangeSM2State *pKE, Ipp8u* pScratchBuffer)


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

``ippcp.h``

Parameters 
----------


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

   * - pSharedKey
     - Pointer to the secret-number Shared Key.
   * - sharedKeySize
     - length to the secret-number Shared Key.
   * - pSSelf
     - Pointer (NULL - optional) to the Self Conformation hash data.
   * - pPrvKey
     - Pointer to the private keys of the elliptic curve.
   * - pEphPrvKey
     - Ephemeral Pointer to the private keys of the elliptic curve. Is cleared inside of the function if returned status is ``ippStsNoErr``.
   * - pScratchBuffer
     - Pointer to the scratch buffer for the elliptic curve.
   * - pKE
     - Pointer to the buffer begging initialization.


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

The function computes a secret-number ``pSharedKey``, which is a secret key shared between two participants of the cryptosystem. 

.. note:: The ephemeral public(R_a/b) and private(r_a/b) keys (steps A1-A3 and B1-B3) have to be generated by the user's application.

[GBT.32918.3-2016] Public Key cryptographic algorithm SM2 based on elliptic curves.

Part 3: Key exchange protocol

6.2 Process of key exchange protocol

stack compute[standart link]:

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

   * - 
     - [user  A| user  B]
   * - 2) x(a/b)` = 2^w + (x(a/b) & (2^w – 1)) 
     - [step  4| step  3]
   * - 3) t(a/b)  = (d(a/b) + x(a/b)`*r(a/b) ) mod n    
     - [step  5| step  4]
   * - 4) x(b/a)` = 2^w + ( x(b/a) & (2^w – 1) )    
     - [step  6| step  5]
   * - 5) U/V = [h*t(a/b)]( P(b/a) + [x(b/a)`]R(b/a) ) = ( x(u/v), y(u/v) )            
       tmp_p = SM3( x(u/v) || Za || Zb || xa || ya || xb || yb )
     - [step  7| step  6]
   * - 6) S(a/b) = SM3( 0x0(3/2) || y(u/v) || tmp_p )  
     - [step 10| step  8]
   * - 7) K(a/b) = KDF(x(u/v) || y(u/v) || Za || Zb, klen)  
     - [step  8| step  7]              
                            
Shared secret shared is an SM3 hash digest of the secret point on the elliptic curve.



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 are NULL.
   * - ippStsContextMatchErr 
     - Indicates an error condition if the ``IppsGFpECState`` context parameter does not match the operation or public keys are set up incorrectly.
   * - ippStsNotSupportedModeErr
     - Indicates an error condition if the ``IppsGFpECState`` context parameter defines an elliptic curve over an extension of the prime finite field.
   * - ippStsRangeErr
     - Indicates an error condition if the length in bits of the elliptic curve is less than the length in bits of the SM3 hash digest.
   * - ippStsBadArgErr
     - Indicates an error condition if the role is not equal to ``ippKESM2Requester`` or ``ippKESM2Responder``.
   * - ippStsInvalidPrivateKey
     - Indicates an error condition if the secret key is not within (0, order).
   * - ippStsOutOfRangeErr
     - Indicates an error condition if ``sharedKeySize`` <= 0.