crys_dh_kg.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_KG_H
00039 #define _CRYS_DH_KG_H
00040 
00041 
00042 #include "crys_dh.h"
00043 
00044 
00045 #ifdef __cplusplus
00046 extern "C"
00047 {
00048 #endif
00049 
00050 /*! @file
00051 @brief This module defines the API that supports Diffie-Hellman domain.
00052 @defgroup crys_dh_kg CryptoCell DH Key Generation APIs
00053 @{
00054 @ingroup crys_dh
00055 */
00056 
00057 /************************ Defines ******************************/
00058 /*! Minimal size of DH seed in bytes. */
00059 #define CRYS_DH_SEED_MIN_SIZE_IN_BYTES    CRYS_HASH_SHA1_DIGEST_SIZE_IN_BYTES
00060 /*! Minimal size of DH seed in bits. */
00061 #define CRYS_DH_SEED_MIN_SIZE_IN_BITS     (CRYS_DH_SEED_MIN_SIZE_IN_BYTES * 8)
00062 
00063 /************************ Enums ********************************/
00064 
00065 
00066 /************************ Typedefs  ****************************/
00067 
00068 /* temp buffers, used in different DH KG functions */
00069 
00070 /*! Temporary data buffer structure for domain parameters generation in DH. */
00071 typedef struct CRYS_DHKGData_t 
00072 {
00073     /* The aligned input and output temp buffers */
00074     /*! Temporary buffer. */
00075     uint32_t TempBuff1 [CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00076     /*! Temporary buffer. */
00077     uint32_t TempBuff2 [CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00078     /*! Temporary buffer. */
00079     uint32_t TempBuff3 [CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00080     /*! Temporary buffer. */
00081     uint32_t TempBuff4 [CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00082     /*! Temporary buffer. */
00083     uint32_t TempBuff5 [CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00084     /*! Temporary buffer. */
00085     uint32_t TempBuff6 [CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00086     /*! Temporary buffer. */
00087     CRYS_DH_Temp_t   ExpTemps ;
00088 }CRYS_DHKGData_t ;
00089 
00090 /*! Temporary buffer structure . */
00091 typedef struct CRYS_DHKG_CheckTemp_t 
00092 {
00093     /*! Temporary buffer. */
00094     uint32_t         CheckTempBuff [3*CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
00095     /*! Temporary buffer. */
00096     CRYS_DHKGData_t     DhKgBuff ;
00097 }CRYS_DHKG_CheckTemp_t ;
00098 
00099 /*! DH Domain generation values definitions */
00100 /*! Minimal modulus size for X942 - 1024.*/
00101 #define DH_X942_PRIME_MOD_MIN_VAL    1024
00102 /*! Maximal modulus size for X942 - 2048.*/
00103 #define DH_X942_PRIME_MOD_MAX_VAL    2048
00104 /*! PGeneration counter for X942 - 4096.*/
00105 #define DH_X942_PGEN_COUNTER_CONST   4096
00106 /*! HASH size in bits for X942 - 160.*/
00107 #define DH_X942_HASH_SIZE_BITS        160
00108 /*! Maximal allowed ratio between modulus and generator order sizes (by implementation) */
00109 #define DH_MAX_RATIO_MODULO_TO_ORDER    4
00110 
00111 /************************ Structs  ******************************/
00112 
00113 /************************ Public Variables **********************/
00114 
00115 /************************ Public Functions **********************/
00116 
00117 
00118 /******************************************************************************************/
00119 /*!
00120 @brief This function generates DH domain parameters in Galois prime field according to standard [ANS X9.42].
00121 It receives the required sizes (in bits) of the modulus, the generator's order, and the seed, and then generates
00122 the prime modulus and the generator according to given sizes.
00123 If generateSeed argument is set to 1, the function generates and outputs the random seed. Otherwise (if set to 0),
00124 the seed has to be passed as an input argument. According to implementation the seed should be not greate, than (2^seedSizeBits - 2^32).
00125 The seed and some additional parameters, generated by the function (factorJ, pgenCounter), are used for checking
00126 that all domain parameters are generated according to the standard and not forged.
00127 \note All buffer parameters should be in Big-Endian form.
00128 
00129 @return CRYS_OK on success.
00130 @return A non-zero value on failure as defined crys_dh_error.h, crys_rnd_error.h or crys_hash_error.h.
00131 */
00132 CIMPORT_C CRYSError_t  CRYS_DH_CreateDomainParams(
00133                 void   *rndState_ptr,                 /*!< [in/out] Pointer to the RND state structure. */
00134                 SaSiRndGenerateVectWorkFunc_t  rndGenerateVectFunc,   /*!< [in] Pointer to a random vector generation function. */
00135                 uint32_t          modPsizeBits,                 /*!< [in]  Size of the modulus (Prime) in bits equal 256*n, where n >= 4. FIPS 186-4
00136                                                                      defines sizes 1024 and 2048 bit. */
00137                 uint32_t          orderQsizeBits,               /*!< [in]  Size of the Generator's order in bits. FIPS 186-4 defines orderQSizeBits = 160
00138                                                                      for modulus 1024 bit and 224 or 256 bit for modPSizeBits = 2048. We not recommend
00139                                                                      sizes > 256 and returns an error if orderQSizeBits > modPSizeBits/4 */
00140                 uint32_t          seedSizeBits,                 /*!< [in]  Seed size in bits. Requirements: modPSizeBits >= seedSizeBits >= orderQSizeBits
00141                                      (the first is required by our implementation). */
00142                 uint8_t          *modP_ptr,                     /*!< [out] Pointer to the modulus (prime) buffer. The size of the buffer for output
00143                                      generated value must be no less than given modulus size. */
00144                 uint8_t          *orderQ_ptr,                   /*!< [out] Pointer to the order Q of generator. The size of the buffer for output generated
00145                                      value must be no less than the given order size. */
00146                 uint8_t          *generatorG_ptr,               /*!< [out] Pointer to the generator of multiplicative subgroup in GF(P).
00147                                      If the user does not need this output, then both the pointer and the buffer size
00148                                      must be set to 0. */
00149                 uint32_t         *generGsizeBytes_ptr,          /*!< [in/out] Pointer to the one word buffer for outputting the generator's size.
00150                                      The passed size (if needed) must be not less than modulus size and the function
00151                                      returns the actual size of the generator. */
00152                 uint8_t          *factorJ_ptr,                  /*!< [out] Pointer to the buffer for integer factor J. If NULL, the function does not output
00153                                      this parameter (in this case JsizeBytes_ptr also must be set to NULL, else the function
00154                                                                      returns an error). */
00155                 uint32_t         *JsizeBytes_ptr,               /*!< [in/out] Pointer to the size of integer factor J. If NULL, the function does not output
00156                                      this parameter. */
00157                 uint8_t          *seedS_ptr,                    /*!< [in/out] Random seed used for prime generation. The size of the buffer must be
00158                                                                      at least the seed size. */
00159                 int8_t            generateSeed,                 /*!< [in]  Flag, defining whether the seed should be generated randomly by the function
00160                                      (1) or is passed by the user (0). */
00161                 uint32_t         *pgenCounter_ptr,              /*!< [out] Pointer to counter of tries to generate the primes. If NULL, the function does not
00162                                          output this parameter. */
00163                 CRYS_DHKGData_t     *DHKGbuff_ptr                /*!< [out] The temp buffer of defined structure for internal calculations. */
00164 );
00165 
00166 
00167 /******************************************************************************************/
00168 /*!
00169 @brief This function receives DH domain parameters, seed and prime generation counter and then verifies
00170 that the domain was created according to the standard [ANS X9.42].
00171 According to implementation, the value of the user passed seed should be not
00172 greate, than (2^seedSizeBits - 2^32), otherwise an error is returned.
00173 \note All buffer parameters should be in Big-Endian form. For more detailed
00174 description of the parameters see ::CRYS_DH_CreateDomainParams.
00175 
00176 @return CRYS_OK on success.
00177 @return A non-zero value on failure as defined crys_dh_error.h, crys_rnd_error.h or crys_hash_error.h.
00178 */
00179 CIMPORT_C CRYSError_t  CRYS_DH_CheckDomainParams(
00180                 void   *rndState_ptr,                /*!< [in/out] Pointer to the RND state. */
00181                 SaSiRndGenerateVectWorkFunc_t  rndGenerateVectFunc,   /*!< [in/out] Pointer to the RND Generate vector function pointer. */
00182                 uint8_t               *modP_ptr,                /*!< [in] Pointer to the modulus (Prime). */
00183                 uint32_t               modPsizeBytes,           /*!< [in] Size of the modulus (Prime) in bytes. */
00184                 uint8_t               *orderQ_ptr,              /*!< [in] Pointer to the order Q of generator. The size of the buffer for output
00185                                           generated value must be no less than the order size. */
00186                 uint32_t               orderQsizeBytes,         /*!< [in] Size of the Generator's order in bytes. */
00187                 uint8_t               *generatorG_ptr,          /*!< [in] Pointer to the generator of the multiplicative subgroup in GF(P). */
00188                 uint32_t               generatorSizeBytes,      /*!< [in] Size of the generator in bytes. */
00189                 uint8_t               *seedS_ptr,               /*!< [in] Random seed used for prime generation.  */
00190                 uint32_t               seedSizeBits,            /*!< [in] Seed size in bits.  */
00191                 uint32_t               pgenCounter,             /*!< [in] Counter of prime generation attempts. */
00192                 CRYS_DHKG_CheckTemp_t  *checkTempBuff_ptr        /*!< [in] Temporary buffer for internal calculations. */
00193 
00194 );
00195 
00196 
00197 #ifdef __cplusplus
00198 }
00199 #endif
00200 /**
00201 @}
00202  */
00203 #endif