crys_dh.h

00001 /**************************************************************************************
00002 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved         *
00003 *                                                                                     *
00004 * This file and the related binary are licensed under the following license:          *
00005 *                                                                                     *
00006 * ARM Object Code and Header Files License, v1.0 Redistribution.                      *
00007 *                                                                                     *
00008 * Redistribution and use of object code, header files, and documentation, without     *
00009 * modification, are permitted provided that the following conditions are met:         *
00010 *                                                                                     *
00011 * 1) Redistributions must reproduce the above copyright notice and the                *
00012 *    following disclaimer in the documentation and/or other materials                 *
00013 *    provided with the distribution.                                                  *
00014 *                                                                                     *
00015 * 2) Unless to the extent explicitly permitted by law, no reverse                     *
00016 *    engineering, decompilation, or disassembly of is permitted.                      *
00017 *                                                                                     *
00018 * 3) Redistribution and use is permitted solely for the purpose of                    *
00019 *    developing or executing applications that are targeted for use                   *
00020 *    on an ARM-based product.                                                         *
00021 *                                                                                     *
00022 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND                  *
00023 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT             *
00024 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,        *
00025 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
00026 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
00027 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED            *
00028 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR              *
00029 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF              *
00030 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING                *
00031 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS                  *
00032 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                        *
00033 **************************************************************************************/
00034 
00035 
00036 
00037 
00038 #ifndef _CRYS_DH_H
00039 #define _CRYS_DH_H
00040 
00041 #include "crys_rsa_types.h"
00042 #include "crys_kdf.h"
00043 #include "crys_rnd.h"
00044 
00045 #ifdef __cplusplus
00046 extern "C"
00047 {
00048 #endif
00049 
00050 
00051 /*!
00052 @file
00053 @brief This module defines the API that supports Diffie-Hellman key exchange, as defined in [PKCS3] and in [X9.42] (key lengths 1024 and 2048 bits).
00054 @defgroup crys_dh CryptoCell DH APIs
00055 @{
00056 @ingroup cryptocell_api
00057 */
00058 
00059 
00060 /************************ Defines ******************************/
00061 /*! Defintion for DH public key.*/
00062 #define CRYS_DHPubKey_t  CRYSRSAPubKey_t
00063 
00064 /*! Maximal valid key size in bits.*/
00065 #define CRYS_DH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS  CRYS_RSA_MAX_VALID_KEY_SIZE_VALUE_IN_BITS /*!< \internal RL restrict to 2048 */
00066 /*! Minimal valid key size in bits.*/
00067 #define CRYS_DH_MIN_VALID_KEY_SIZE_VALUE_IN_BITS  1024 /*!< Size limitation according to ANSI standard */
00068 /*! Maximal modulus size in bytes.*/
00069 #define CRYS_DH_MAX_MOD_SIZE_IN_BYTES   (CRYS_DH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS / SASI_BITS_IN_BYTE)
00070 /*! Maximal modulus size in words.*/
00071 #define CRYS_DH_MAX_MOD_SIZE_IN_WORDS   (CRYS_DH_MAX_MOD_SIZE_IN_BYTES/sizeof(uint32_t))
00072 
00073 /*! Modulus buffer size in words.*/
00074 #define CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS (CRYS_DH_MAX_MOD_SIZE_IN_WORDS + 2)
00075 /*! Maximal domain generation size in bits.*/
00076 #define CRYS_DH_DOMAIN_GENERATION_MAX_SIZE_BITS   CRYS_RSA_MAX_KEY_GENERATION_SIZE_BITS /*!< \internal RL restrict to 2048 */
00077 
00078 /*! Defintion for DH primitives data.*/
00079 #define CRYS_DHPrimeData_t   CRYS_RSAPrimeData_t
00080 /*! Defintion for DH public key.*/
00081 #define CRYS_DHUserPubKey_t  CRYS_RSAUserPubKey_t
00082 /*! Defintion for DH other info.*/
00083 #define CRYS_DH_OtherInfo_t  CRYS_KDF_OtherInfo_t
00084 
00085 /*! Keying data size is in bytes*/
00086 #define CRYS_DH_MAX_SIZE_OF_KEYING_DATA  CRYS_KDF_MAX_SIZE_OF_KEYING_DATA
00087 
00088 /************************ Enums ********************************/
00089 
00090 /*! DH operations mode */
00091 typedef enum
00092 {
00093     /*! PKCS3 operation mode. */
00094     CRYS_DH_PKCS3_mode   = 0,
00095     /*! ANSI X942 operation mode. */
00096     CRYS_DH_ANSI_X942_mode  = 1,
00097     /*! Total number of operation modes. */
00098     CRYS_DH_NumOfModes ,
00099 
00100     /*! Reserved. */
00101     CRYS_DH_OpModeLast     = 0x7FFFFFFF,
00102 
00103 }CRYS_DH_OpMode_t ;
00104 
00105 /*! HASH operation modes */
00106 typedef enum
00107 {
00108     /*! SHA1 operation mode. */
00109     CRYS_DH_HASH_SHA1_mode       = CRYS_HASH_SHA1_mode ,
00110     /*! SHA224 operation mode. */
00111     CRYS_DH_HASH_SHA224_mode     = CRYS_HASH_SHA224_mode ,
00112     /*! SHA256 operation mode. */
00113     CRYS_DH_HASH_SHA256_mode     = CRYS_HASH_SHA256_mode ,
00114     /*! SHA384 operation mode. */
00115     CRYS_DH_HASH_SHA384_mode     = CRYS_HASH_SHA384_mode ,
00116     /*! SHA512 operation mode. */
00117     CRYS_DH_HASH_SHA512_mode     = CRYS_HASH_SHA512_mode ,
00118     /*! MD5 operation mode (not used in DH). */
00119     CRYS_DH_HASH_MD5_mode            = CRYS_HASH_MD5_mode , /*!< \internal not used in DH */
00120     /*! Total number of HASH modes. */
00121     CRYS_DH_HASH_NumOfModes      = CRYS_HASH_MD5_mode ,
00122     /*! Reserved. */
00123     CRYS_DH_HASH_OperationModeLast   = 0x7FFFFFFF,
00124 
00125 }CRYS_DH_HASH_OpMode_t ;
00126 
00127 /*! Key derivation modes. */
00128 typedef enum
00129 {
00130     /*! ASN1 derivation mode.*/
00131     CRYS_DH_ASN1_Der_mode     = CRYS_KDF_ASN1_DerivMode ,
00132     /*! Concatination derivation mode.*/
00133     CRYS_DH_Concat_Der_mode   = CRYS_KDF_ConcatDerivMode ,
00134     /*! X963 derivation mode.*/
00135     CRYS_DH_X963_DerMode     = CRYS_KDF_ConcatDerivMode ,
00136     /*! Reserved. */
00137     CRYS_DH_DerivationFunc_ModeLast = 0x7FFFFFFF,
00138 
00139 }CRYS_DH_DerivationFunc_Mode ;
00140 
00141 
00142 /************************ Typedefs  *************************************/
00143 /*! Temporary buffer structure for internal usage.*/
00144 typedef struct
00145 {
00146     /*! Temporary primitives data */
00147     CRYS_DHPrimeData_t PrimeData ;
00148     /*! Public key. */
00149     CRYS_DHPubKey_t    PubKey ;
00150     /*! Temporary buffer for internal usage. */
00151     uint32_t TempBuff[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00152 } CRYS_DH_ExpTemp_t ;
00153 
00154 /*! Temporary buffer structure for internal usage. */
00155 typedef struct
00156 {
00157     /*! Temporary primitives data */
00158     CRYS_DHPrimeData_t PrimeData ;
00159     /*! User's public key. */
00160     CRYS_DHUserPubKey_t    UserPubKey ;
00161     /*! Temporary buffer for internal usage. */
00162     uint32_t TempBuff[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00163 } CRYS_DH_Temp_t ;
00164 
00165 /*! Temporary buffer structure for internal usage. */
00166 typedef struct
00167 {
00168     /*! Temporary primitives data */
00169     CRYS_DHPrimeData_t PrimeData ;
00170     /*! User's public key. */
00171     CRYS_DHUserPubKey_t    UserPubKey ;
00172     /*! Temporary buffer for internal usage. */
00173     uint32_t TempBuff[2*CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00174 } CRYS_DH_HybrTemp_t ;
00175 
00176 /*! Defintion of buffer used for FIPS Known Answer Tests. */
00177 typedef struct
00178 {
00179     /*! Public key. */
00180     CRYS_DHUserPubKey_t pubKey ;
00181     /*! Temporary primitives data */
00182     CRYS_DHPrimeData_t  primeData ;
00183     /*! Buffer for the secret value.*/
00184     uint8_t secretBuff[CRYS_DH_MIN_VALID_KEY_SIZE_VALUE_IN_BITS/SASI_BITS_IN_BYTE];  // KAT tests uses 1024 bit key
00185 } CRYS_DH_FipsKat_t ;
00186 
00187 
00188 /************************ Structs  **************************************/
00189 
00190 /************************ Public Variables ******************************/
00191 
00192 /************************ Public Functions ******************************/
00193 
00194 /*******************************************************************************************/
00195 
00196 /*!
00197 @brief This function has two purposes:
00198 <ol><li> Randomly generate the client private key according to the choosen version [PKCS3] or [ANSI X9.42].</li>
00199 <li> Computes the client public key as follows: ClientPub = Generator^Prv mod Prime, where '^' is the symbol of exponentiation.</li></ol>
00200 This function should not be called directly. Instead, use the macros ::CRYS_DH_PKCS3_GeneratePubPrv and ::CRYS_DH_ANSI_X942_GeneratePubPrv.
00201 \note
00202 All buffer parameters should be in Big-Endian form.
00203 
00204 @return CRYS_OK on success.
00205 @return A non-zero value on failure as defined crys_dh_error.h, crys_rnd_error.h or crys_rsa_error.h.
00206  */
00207 CIMPORT_C CRYSError_t  _DX_DH_GeneratePubPrv(
00208                     void   *rndState_ptr,               /*!< [in/out] Pointer to the RND state structure. */
00209                     SaSiRndGenerateVectWorkFunc_t  rndGenerateVectFunc, /*!< [in] Pointer to the random vector generation function. */
00210                     uint8_t *Generator_ptr,                         /*!< [in]  Pointer to the Generator octet string. */
00211                     uint16_t GeneratorSize,                         /*!< [in]  The size of the Generator string (in bytes). */
00212                     uint8_t *Prime_ptr,                             /*!< [in]  Pointer to the Prime octet string P (used as modulus in the algorithm). */
00213                     uint16_t PrimeSize,                             /*!< [in]  The size of the Prime string in bytes. */
00214                     uint16_t L,                                     /*!< [in]  Exact size in bits of the Prime to be generated (relevant only for [PKCS3]):
00215                                                                                <ul><li> If L!=0, force the private key to be [2^(L-1) ? Prv < 2^L], where '^'
00216                                             indicates exponentiation.</li>
00217                                                                                <li> If L = 0 then [0 < Prv < P-1].</li></ul> */
00218                     uint8_t *Q_ptr,                                 /*!< [in]  Relevant only for [ANSI X9.42] - Pointer to the Q octet string in the range:
00219                                                                                 1 <= Prv <= Q-1 or 1 < Prv < Q-1. */
00220                     uint16_t QSize,                                 /*!< [in]  Relevant only for [ANSI X9.42] - Size of the Q string (in bytes). */
00221                     CRYS_DH_OpMode_t  DH_mode,                       /*!< [in]  An enumerator declaring whether this is [PKCS3] or [ANSI X9.42] mode. */
00222                     CRYS_DHUserPubKey_t *tmpPubKey_ptr,             /*!< [in]  Pointer to a temporary buffer for public key structure. Used for the
00223                                                    exponentiation function. */
00224                     CRYS_DHPrimeData_t  *tmpPrimeData_ptr,          /*!< [in]  Pointer to a structure holding internal temporary buffers. */
00225                     uint8_t *ClientPrvKey_ptr,                      /*!< [out] Pointer to the Private key Prv. This buffer should be at least the following
00226                                            size (in bytes):
00227                                                                                <ul><li> If L is provided: (L+7)/8.</li>
00228                                                                                <li> If L is NULL: \p PrimeSize. </li></ul> */
00229                     uint16_t *ClientPrvKeySize_ptr,                 /*!< [in/out] Pointer to the Private key size:
00230                                                                                     <ul><li> Input - size of the given buffer.</li>
00231                                                                                     <li> Output - actual size of the generated private key.</li></ul> */
00232                     uint8_t *ClientPub1_ptr,                        /*!< [out] Pointer to the Public key. This buffer should be at least \p PrimeSize bytes. */
00233                     uint16_t *ClientPubSize_ptr                     /*!< [in/out] Pointer to the Public key size:
00234                                                                                   <ul><li> Input - size of the given buffer.</li>
00235                                                                                   <li> Output - actual size of the generated public key.</li></ul> */
00236 );
00237 
00238 
00239 /* macro for calling the GeneratePubPrv function on PKCS#3 mode:  Q is irrelevant */
00240 /*--------------------------------------------------------------------------------*/
00241 /*!
00242 This macro is used to generate the public and private DH keys according to [PKCS3]. For a description of the parameters see ::_DX_DH_GeneratePubPrv.
00243 */
00244 #define CRYS_DH_PKCS3_GeneratePubPrv(rndState_ptr, rndGenerateVectFunc, Generator_ptr,GeneratorSize,\
00245                 Prime_ptr,PrimeSize,\
00246                 L,\
00247                 tmpPubKey_ptr,tmpPrimeData_ptr,\
00248                 ClientPrvKey_ptr,ClientPrvKeySize_ptr,\
00249                 ClientPub_ptr,ClientPubSize_ptr)\
00250         _DX_DH_GeneratePubPrv(rndState_ptr, rndGenerateVectFunc, (Generator_ptr),(GeneratorSize),\
00251                 (Prime_ptr),(PrimeSize),\
00252                 (L),\
00253                 (uint8_t *)NULL,(uint16_t)0,\
00254                 CRYS_DH_PKCS3_mode,\
00255                 (tmpPubKey_ptr),(tmpPrimeData_ptr),\
00256                 (ClientPrvKey_ptr),(ClientPrvKeySize_ptr),\
00257                 (ClientPub_ptr),(ClientPubSize_ptr))
00258 
00259 /*!
00260 This macro is used to generate the public and private DH keys according to [ANSI X9.42]. For a description of the parameters see ::_DX_DH_GeneratePubPrv.
00261 */
00262 #define CRYS_DH_ANSI_X942_GeneratePubPrv(rndState_ptr, rndGenerateVectFunc, Generator_ptr,GeneratorSize,Prime_ptr,PrimeSize,\
00263                 Q_ptr,QSize,\
00264                 tmpPubKey_ptr,tmpPrimeData_ptr,\
00265                 ClientPrvKey_ptr,ClientPrvKeySize_ptr,\
00266                 ClientPub_ptr,ClientPubSize_ptr)\
00267         _DX_DH_GeneratePubPrv(rndState_ptr, rndGenerateVectFunc, (Generator_ptr),(GeneratorSize),\
00268                 (Prime_ptr),(PrimeSize),\
00269                 (uint16_t)0,\
00270                 (Q_ptr),(QSize),\
00271                 CRYS_DH_ANSI_X942_mode,\
00272                 (tmpPubKey_ptr),(tmpPrimeData_ptr),\
00273                 (ClientPrvKey_ptr),(ClientPrvKeySize_ptr),\
00274                 (ClientPub_ptr),(ClientPubSize_ptr))
00275 
00276 
00277 /*******************************************************************************************/
00278 /*!
00279 @brief This function computes the shared secret key (value) accordng to [ANSI X9.42], 7.5.1:
00280           SecretKey = ServerPubKey ^ ClientPrvKey mod Prime.
00281 \note <ul id="noteb"><li> All buffer parameters should be in Big-Endian form.</li>
00282 <li>The user must obtain assurance of validity of the public key, using one of methods,
00283 described in [ANSI X9.42] paragraph 7.4.</li>
00284 <li>The actual size of the private key (in bits) must be not less than 2 and not greater than the actual
00285 size of the Prime (modulus in bits).</li></ul>
00286 
00287 @return CRYS_OK on success.
00288 @return A non-zero value on failure as defined in crys_dh_error.h or crys_rsa_error.h.
00289 */
00290 CIMPORT_C CRYSError_t  CRYS_DH_GetSecretKey(
00291                     uint8_t *ClientPrvKey_ptr,                  /*!< [in]  Pointer to the Private key octet string Prv < Prime. */
00292                     uint16_t ClientPrvKeySize,                  /*!< [in]  The Private key Size (in bytes). */
00293                     uint8_t *ServerPubKey_ptr,                  /*!< [in]  Pointer to the Server public key octet string. */
00294                     uint16_t ServerPubKeySize,                  /*!< [in]  The Server Public key Size (in bytes). */
00295                     uint8_t *Prime_ptr,                         /*!< [in]  Pointer to the Prime octet string. */
00296                     uint16_t PrimeSize,                         /*!< [in]  The size of the Prime string. */
00297                     CRYS_DHUserPubKey_t *tmpPubKey_ptr,         /*!< [in]  Pointer to the public key structure. Used for the exponentiation
00298                                              operation function. Need not be initialized. */
00299                     CRYS_DHPrimeData_t  *tmpPrimeData_ptr,      /*!< [in]  Pointer to a structure containing internal temp buffers. */
00300                     uint8_t *SecretKey_ptr,                     /*!< [out] Pointer to the secret key octet string. This buffer should be at
00301                                             least PrimeSize bytes. */
00302                     uint16_t *SecretKeySize_ptr                 /*!< [in/out] Pointer to the secret key Buffer Size. This buffer should be at
00303                                             least of PrimeSize bytes:
00304                                             <ul><li> Input  - size of the given buffer.</li>
00305                                             <li> Output - actual size. </li></ul>*/
00306 );
00307 
00308 
00309 /******************************************************************************************/
00310 /*!
00311 @brief This function extracts the shared secret keying data from the shared secret value. It should be called by using
00312 macros ::CRYS_DH_X942_GetSecretDataAsn1 and ::CRYS_DH_X942_GetSecretDataConcat.
00313 
00314 \note
00315 <ul id="noteb"><li> The "other info" argument and its AlgorithmID entry are mandatory only for ASN1 key derivation, and optional for
00316 the other derivation modes. </li>
00317 <li>If used, all entries of the structure should be initialized with relevant data and size, prior to calling this function
00318 (entry size of empty fields must be set to 0).</li>
00319 <li>All buffers arguments are represented in Big-Endian form.</li></ul>
00320 
00321 @return CRYS_OK on success.
00322 @return A non-zero value on failure as defined in crys_dh_error.h, crys_rsa_error.h, crys_kdf_error.h or crys_hash_error.h.
00323 */
00324  CIMPORT_C CRYSError_t  CRYS_DH_X942_GetSecretData(
00325                     uint8_t                  *ClientPrvKey_ptr,        /*!< [in] Pointer to the Private key octet string. */
00326                     uint16_t                  ClientPrvKeySize,         /*!< [in] The Private key size (in bytes). */
00327                     uint8_t                  *ServerPubKey_ptr,         /*!< [in] Pointer to the Server public key octet string. */
00328             uint16_t                  ServerPubKeySize,         /*!< [in] The Server Public key size (in bytes). */
00329                     uint8_t                  *Prime_ptr,                /*!< [in] Pointer to the Prime octet string. */
00330                     uint16_t                  PrimeSize,                /*!< [in] The size of the Prime string. */
00331                     CRYS_DH_OtherInfo_t        *otherInfo_ptr,          /*!< [in] Pointer to structure containing other data, shared by two entities
00332                                           sharing the secret keying data.
00333                                                                                   The Maximal size of each data entry of "other info" is limited - see crys_kdf.h
00334                                           for the defined value. */
00335                     CRYS_DH_HASH_OpMode_t        hashMode,               /*!< [in] One of the supported SHA-x HASH modes. The supported modes are according to the supported
00336                                               HASH modes for the product (and MD5 is not supported). */
00337                     CRYS_DH_DerivationFunc_Mode  DerivFunc_mode,         /*!< [in] The enumerator ID of key derivation function mode. ASN1 or Concatenation
00338                                           modes are supported. */
00339                     CRYS_DH_Temp_t              *tmpBuff_ptr,            /*!< [in] A pointer to the DH temp buffer structure. Not initialized. */
00340                     uint8_t                  *SecretKeyingData_ptr,     /*!< [out] Pointer to the secret key octet string. This buffer should be at least
00341                                            PrimeSize bytes. */
00342                     uint16_t                  SecretKeyingDataSize      /*!< [in] The required Secret Keying data size (in bytes). Must be larger than 0,
00343                                           and smaller than the maximal - CRYS_DH_MAX_SIZE_OF_KEYING_DATA. */
00344 );
00345 
00346 /****************************************************************/
00347 /*!
00348 This macro implements the DH [ANSI X9.42] standard. It derives a secret key using the Derivation function based on ASN.1. For a
00349 description of the parameters see ::CRYS_DH_X942_GetSecretData.*/
00350 #define CRYS_DH_X942_GetSecretDataAsn1(ClientPrvKey_ptr,ClientPrvKeySize,ServerPubKey_ptr,ServerPubKeySize,Prime_ptr,PrimeSize,otherInfo_ptr,hashMode,tmpBuff_ptr,SecretKeyingData_ptr,SecretKeyingDataSize)\
00351     CRYS_DH_X942_GetSecretData((ClientPrvKey_ptr),(ClientPrvKeySize),(ServerPubKey_ptr),(ServerPubKeySize),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashMode),(CRYS_DH_ASN1_Der_mode),(tmpBuff_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))
00352 /*!
00353 This macro implements the DH [ANSI X9.42] standard. It derives a secret key using the Derivation function based on concatenation of HASHed data.
00354 For a description of the parameters see ::CRYS_DH_X942_GetSecretData.*/
00355 #define CRYS_DH_X942_GetSecretDataConcat(ClientPrvKey_ptr,ClientPrvKeySize,ServerPubKey_ptr,ServerPubKeySize,Prime_ptr,PrimeSize,otherInfo_ptr,hashMode,tmpBuff_ptr,SecretKeyingData_ptr,SecretKeyingDataSize)\
00356     CRYS_DH_X942_GetSecretData((ClientPrvKey_ptr),(ClientPrvKeySize),(ServerPubKey_ptr),(ServerPubKeySize),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashMode),(CRYS_DH_Concat_Der_mode),(tmpBuff_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))
00357 
00358 
00359 /****************************************************************/
00360 /*!
00361 @brief The function computes shared secret data using two pairs of public and private keys:
00362 
00363 <ul><li> SecretKey1 = ServerPubKey1^ClientPrvKey1 mod Prime. </li>
00364 <li> SecretKey2 = ServerPubKey2^ClientPrvKey2 mod Prime. </li></ul>
00365 It uses the Derivation function to derive secret keying data from the two secret keys (values).
00366 This function may be called directly, or by using macros ::CRYS_DH_X942_HybridGetSecretDataAsn1 and ::CRYS_DH_X942_HybridGetSecretDataConcat
00367 described above.
00368 
00369 \note
00370 <ul id="noteb"><li> The "other info" argument and its AlgorithmID entry are mandatory only for ASN1 key derivation, and optional for the other derivation modes.</li>
00371 If used, all entries of the structure should be initialized with relevant data and size, prior to calling this function
00372 (entry size of empty fields must be set to 0).
00373 <li> All buffers arguments are represented in Big-Endian form. </li></ul>
00374 
00375 @return CRYS_OK on success.
00376 @return A non-zero value on failure as defined in crys_dh_error.h, crys_rsa_error.h or crys_hash_error.h.
00377 */
00378 CIMPORT_C CRYSError_t  CRYS_DH_X942_HybridGetSecretData(
00379                 uint8_t            *ClientPrvKey_ptr1,          /*!< [in]  Pointer to the First Private key octet string number. */
00380                 uint16_t            ClientPrvKeySize1,          /*!< [in]  The First Private key Size (in bytes). */
00381                 uint8_t            *ClientPrvKey_ptr2,          /*!< [in]  Pointer to the Second Private key octet string. */
00382         uint16_t            ClientPrvKeySize2,          /*!< [in]  The Second Private key Size (in bytes). */
00383                 uint8_t            *ServerPubKey_ptr1,          /*!< [in]  Pointer to the First Server public key octet string. */
00384                 uint16_t            ServerPubKeySize1,          /*!< [in]  The First Server Public key Size (in bytes). */
00385                 uint8_t            *ServerPubKey_ptr2,          /*!< [in]  Pointer to the Second Server public key octet string. */
00386                 uint16_t            ServerPubKeySize2,          /*!< [in]  The Second Server Public key Size (in bytes). */
00387                 uint8_t            *Prime_ptr,                  /*!< [in]  Pointer to the Prime octet string. */
00388                 uint16_t            PrimeSize,                  /*!< [in]  The size of the Prime string. */
00389                 CRYS_DH_OtherInfo_t  *otherInfo_ptr,            /*!< [in]  Pointer to structure containing optional other data, shared by two entities
00390                                  sharing the secret keying data. */
00391                 CRYS_DH_HASH_OpMode_t  hashMode,                 /*!< [in]  One of the supported SHA-x HASH modes. The supported modes are according to the supported
00392                                            HASH modes for the product (and MD5 is not supported). */
00393                 CRYS_DH_DerivationFunc_Mode  DerivFunc_mode,     /*!< [in]  The type of function to use to derive the secret key to the key data.
00394                                  ASN.1 or Concatenation modes are supported. */
00395                 CRYS_DH_HybrTemp_t    *tmpDhHybr_ptr,            /*!< [in]  Pointer to a CRYS_DH_Temp_t structure that contains temp buffers for
00396                                  internal operations. */
00397                 uint8_t            *SecretKeyingData_ptr,       /*!< [out] Pointer to the secret key octet string. This buffer should be at least
00398                                  of size PrimeSize bytes. */
00399                 uint16_t            SecretKeyingDataSize        /*!< [in]  The required Secret Keying data size (in bytes). Must be larger than 0,
00400                                  and smaller than CRYS_DH_MAX_SIZE_OF_KEYING_DATA. */
00401 );
00402 
00403 
00404 /****************************************************************/
00405 /*!
00406 This macro implements the DH [X9.42] standard deriving a hybrid secret key from two public-private pair of keys using the Derivation function based on ASN.1.
00407 For a description of the parameters see ::CRYS_DH_X942_HybridGetSecretData.*/
00408 #define CRYS_DH_X942_HybridGetSecretDataAsn1(ClientPrvKey_ptr1,ClientPrvKeySize1,ClientPrvKey_ptr2,ClientPrvKeySize2,ServerPubKey_ptr1,ServerPubKeySize1,ServerPubKey_ptr2,ServerPubKeySize2,Prime_ptr,PrimeSize,otherInfo_ptr,hashFunc,tmpDhHybr_ptr,SecretKeyingData_ptr,SecretKeyingDataSize)\
00409     CRYS_DH_X942_HybridGetSecretData((ClientPrvKey_ptr1),(ClientPrvKeySize1),(ClientPrvKey_ptr2),(ClientPrvKeySize2),(ServerPubKey_ptr1),(ServerPubKeySize1),(ServerPubKey_ptr2),(ServerPubKeySize2),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashFunc),CRYS_DH_ASN1_Der_mode,(tmpDhHybr_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))
00410 
00411 /*!
00412 This macro implements the DH [X9.42] standard, deriving a hybrid secret key from two pairs of public-private keys, using the Derivation
00413 function based on concatenation using SHA-x HASH. For a description of the parameters see ::CRYS_DH_X942_HybridGetSecretData.
00414 */
00415 #define CRYS_DH_X942_HybridGetSecretDataConcat(ClientPrvKey_ptr1,ClientPrvKeySize1,ClientPrvKey_ptr2,ClientPrvKeySize2,ServerPubKey_ptr1,ServerPubKeySize1,ServerPubKey_ptr2,ServerPubKeySize2,Prime_ptr,PrimeSize,otherInfo_ptr,hashFunc,tmpDhHybr_ptr,SecretKeyingData_ptr,SecretKeyingDataSize)\
00416     CRYS_DH_X942_HybridGetSecretData((ClientPrvKey_ptr1),(ClientPrvKeySize1),(ClientPrvKey_ptr2),(ClientPrvKeySize2),(ServerPubKey_ptr1),(ServerPubKeySize1),(ServerPubKey_ptr2),(ServerPubKeySize2),(Prime_ptr),(PrimeSize),(otherInfo_ptr),(hashFunc),CRYS_DH_Concat_Der_mode,(tmpDhHybr_ptr),(SecretKeyingData_ptr),(SecretKeyingDataSize))
00417 
00418 
00419 /******************************************************************************************/
00420 /*!
00421 @brief The function checks the obtained DH public key according to its domain parameters [ANSI X9.42-2001]
00422 
00423 \note
00424 Assuming: The DH domain parameters are valid.
00425 
00426 @return CRYS_OK on success.
00427 @return A non-zero value on failure as defined in crys_dh_error.h.
00428 */
00429 CIMPORT_C CRYSError_t  CRYS_DH_CheckPubKey(
00430                     uint8_t              *modP_ptr,            /*!< [in] The pointer to the modulus (prime) P. */
00431                     uint32_t              modPsizeBytes,        /*!< [in]  The modulus size in bytes. */
00432                     uint8_t              *orderQ_ptr,           /*!< [in]  The pointer to the prime order Q of generator. */
00433                     uint32_t              orderQsizeBytes,      /*!< [in]  The size of order of generator in bytes. */
00434                     uint8_t              *pubKey_ptr,           /*!< [in]  The pointer to the public key to be validated. */
00435                     uint32_t              pubKeySizeBytes,      /*!< [in]  The public key size in bytes. */
00436                     CRYS_DH_Temp_t        *tempBuff_ptr         /*!< [in]  The temp buffer for internal calculations. */
00437 );
00438 
00439 
00440 #ifdef __cplusplus
00441 }
00442 #endif
00443 /**
00444 @}
00445  */
00446 #endif