Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crys_dh_kg.h
Go to the documentation of this file.
1 /**************************************************************************************
2 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
3 * *
4 * This file and the related binary are licensed under the following license: *
5 * *
6 * ARM Object Code and Header Files License, v1.0 Redistribution. *
7 * *
8 * Redistribution and use of object code, header files, and documentation, without *
9 * modification, are permitted provided that the following conditions are met: *
10 * *
11 * 1) Redistributions must reproduce the above copyright notice and the *
12 * following disclaimer in the documentation and/or other materials *
13 * provided with the distribution. *
14 * *
15 * 2) Unless to the extent explicitly permitted by law, no reverse *
16 * engineering, decompilation, or disassembly of is permitted. *
17 * *
18 * 3) Redistribution and use is permitted solely for the purpose of *
19 * developing or executing applications that are targeted for use *
20 * on an ARM-based product. *
21 * *
22 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
23 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
24 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
25 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
26 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
28 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
33 **************************************************************************************/
34 
35 
36 
37 
38 #ifndef _CRYS_DH_KG_H
39 #define _CRYS_DH_KG_H
40 
41 
42 #include "crys_dh.h"
43 
44 
45 #ifdef __cplusplus
46 extern "C"
47 {
48 #endif
49 
50 /*! @file
51 @brief This module defines the API that supports Diffie-Hellman domain.
52 @defgroup crys_dh_kg CryptoCell DH Key Generation APIs
53 @{
54 @ingroup crys_dh
55 */
56 
57 /************************ Defines ******************************/
58 /*! Minimal size of DH seed in bytes. */
59 #define CRYS_DH_SEED_MIN_SIZE_IN_BYTES CRYS_HASH_SHA1_DIGEST_SIZE_IN_BYTES
60 /*! Minimal size of DH seed in bits. */
61 #define CRYS_DH_SEED_MIN_SIZE_IN_BITS (CRYS_DH_SEED_MIN_SIZE_IN_BYTES * 8)
62 
63 /************************ Enums ********************************/
64 
65 
66 /************************ Typedefs ****************************/
67 
68 /* temp buffers, used in different DH KG functions */
69 
70 /*! Temporary data buffer structure for domain parameters generation in DH. */
71 typedef struct CRYS_DHKGData_t
72 {
73  /* The aligned input and output temp buffers */
74  /*! Temporary buffer. */
75  uint32_t TempBuff1[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
76  /*! Temporary buffer. */
77  uint32_t TempBuff2[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
78  /*! Temporary buffer. */
79  uint32_t TempBuff3[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
80  /*! Temporary buffer. */
81  uint32_t TempBuff4[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
82  /*! Temporary buffer. */
83  uint32_t TempBuff5[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
84  /*! Temporary buffer. */
85  uint32_t TempBuff6[CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
86  /*! Temporary buffer. */
87  CRYS_DH_Temp_t ExpTemps;
88 }CRYS_DHKGData_t;
89 
90 /*! Temporary buffer structure . */
91 typedef struct CRYS_DHKG_CheckTemp_t
92 {
93  /*! Temporary buffer. */
94  uint32_t CheckTempBuff[3*CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS];
95  /*! Temporary buffer. */
96  CRYS_DHKGData_t DhKgBuff;
97 }CRYS_DHKG_CheckTemp_t;
98 
99 /*! DH Domain generation values definitions */
100 /*! Minimal modulus size for X942 - 1024.*/
101 #define DH_X942_PRIME_MOD_MIN_VAL 1024
102 /*! Maximal modulus size for X942 - 2048.*/
103 #define DH_X942_PRIME_MOD_MAX_VAL 2048
104 /*! PGeneration counter for X942 - 4096.*/
105 #define DH_X942_PGEN_COUNTER_CONST 4096
106 /*! HASH size in bits for X942 - 160.*/
107 #define DH_X942_HASH_SIZE_BITS 160
108 /*! Maximal allowed ratio between modulus and generator order sizes (by implementation) */
109 #define DH_MAX_RATIO_MODULO_TO_ORDER 4
110 
111 /************************ Structs ******************************/
112 
113 /************************ Public Variables **********************/
114 
115 /************************ Public Functions **********************/
116 
117 
118 /******************************************************************************************/
119 /*!
120 @brief This function generates DH domain parameters in Galois prime field according to standard [ANS X9.42].
121 It receives the required sizes (in bits) of the modulus, the generator's order, and the seed, and then generates
122 the prime modulus and the generator according to given sizes.
123 If generateSeed argument is set to 1, the function generates and outputs the random seed. Otherwise (if set to 0),
124 the seed has to be passed as an input argument. According to implementation the seed should be not greate, than (2^seedSizeBits - 2^32).
125 The seed and some additional parameters, generated by the function (factorJ, pgenCounter), are used for checking
126 that all domain parameters are generated according to the standard and not forged.
127 \note All buffer parameters should be in Big-Endian form.
128 
129 @return CRYS_OK on success.
130 @return A non-zero value on failure as defined crys_dh_error.h, crys_rnd_error.h or crys_hash_error.h.
131 */
132 CIMPORT_C CRYSError_t CRYS_DH_CreateDomainParams(
133  void *rndState_ptr, /*!< [in/out] Pointer to the RND state structure. */
134  SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, /*!< [in] Pointer to a random vector generation function. */
135  uint32_t modPsizeBits, /*!< [in] Size of the modulus (Prime) in bits equal 256*n, where n >= 4. FIPS 186-4
136  defines sizes 1024 and 2048 bit. */
137  uint32_t orderQsizeBits, /*!< [in] Size of the Generator's order in bits. FIPS 186-4 defines orderQSizeBits = 160
138  for modulus 1024 bit and 224 or 256 bit for modPSizeBits = 2048. We not recommend
139  sizes > 256 and returns an error if orderQSizeBits > modPSizeBits/4 */
140  uint32_t seedSizeBits, /*!< [in] Seed size in bits. Requirements: modPSizeBits >= seedSizeBits >= orderQSizeBits
141  (the first is required by our implementation). */
142  uint8_t *modP_ptr, /*!< [out] Pointer to the modulus (prime) buffer. The size of the buffer for output
143  generated value must be no less than given modulus size. */
144  uint8_t *orderQ_ptr, /*!< [out] Pointer to the order Q of generator. The size of the buffer for output generated
145  value must be no less than the given order size. */
146  uint8_t *generatorG_ptr, /*!< [out] Pointer to the generator of multiplicative subgroup in GF(P).
147  If the user does not need this output, then both the pointer and the buffer size
148  must be set to 0. */
149  uint32_t *generGsizeBytes_ptr, /*!< [in/out] Pointer to the one word buffer for outputting the generator's size.
150  The passed size (if needed) must be not less than modulus size and the function
151  returns the actual size of the generator. */
152  uint8_t *factorJ_ptr, /*!< [out] Pointer to the buffer for integer factor J. If NULL, the function does not output
153  this parameter (in this case JsizeBytes_ptr also must be set to NULL, else the function
154  returns an error). */
155  uint32_t *JsizeBytes_ptr, /*!< [in/out] Pointer to the size of integer factor J. If NULL, the function does not output
156  this parameter. */
157  uint8_t *seedS_ptr, /*!< [in/out] Random seed used for prime generation. The size of the buffer must be
158  at least the seed size. */
159  int8_t generateSeed, /*!< [in] Flag, defining whether the seed should be generated randomly by the function
160  (1) or is passed by the user (0). */
161  uint32_t *pgenCounter_ptr, /*!< [out] Pointer to counter of tries to generate the primes. If NULL, the function does not
162  output this parameter. */
163  CRYS_DHKGData_t *DHKGbuff_ptr /*!< [out] The temp buffer of defined structure for internal calculations. */
164 );
165 
166 
167 /******************************************************************************************/
168 /*!
169 @brief This function receives DH domain parameters, seed and prime generation counter and then verifies
170 that the domain was created according to the standard [ANS X9.42].
171 According to implementation, the value of the user passed seed should be not
172 greate, than (2^seedSizeBits - 2^32), otherwise an error is returned.
173 \note All buffer parameters should be in Big-Endian form. For more detailed
174 description of the parameters see ::CRYS_DH_CreateDomainParams.
175 
176 @return CRYS_OK on success.
177 @return A non-zero value on failure as defined crys_dh_error.h, crys_rnd_error.h or crys_hash_error.h.
178 */
179 CIMPORT_C CRYSError_t CRYS_DH_CheckDomainParams(
180  void *rndState_ptr, /*!< [in/out] Pointer to the RND state. */
181  SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, /*!< [in/out] Pointer to the RND Generate vector function pointer. */
182  uint8_t *modP_ptr, /*!< [in] Pointer to the modulus (Prime). */
183  uint32_t modPsizeBytes, /*!< [in] Size of the modulus (Prime) in bytes. */
184  uint8_t *orderQ_ptr, /*!< [in] Pointer to the order Q of generator. The size of the buffer for output
185  generated value must be no less than the order size. */
186  uint32_t orderQsizeBytes, /*!< [in] Size of the Generator's order in bytes. */
187  uint8_t *generatorG_ptr, /*!< [in] Pointer to the generator of the multiplicative subgroup in GF(P). */
188  uint32_t generatorSizeBytes, /*!< [in] Size of the generator in bytes. */
189  uint8_t *seedS_ptr, /*!< [in] Random seed used for prime generation. */
190  uint32_t seedSizeBits, /*!< [in] Seed size in bits. */
191  uint32_t pgenCounter, /*!< [in] Counter of prime generation attempts. */
192  CRYS_DHKG_CheckTemp_t *checkTempBuff_ptr /*!< [in] Temporary buffer for internal calculations. */
193 
194 );
195 
196 
197 #ifdef __cplusplus
198 }
199 #endif
200 /**
201 @}
202  */
203 #endif
CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS
#define CRYS_DH_MAX_MOD_BUFFER_SIZE_IN_WORDS
Definition: crys_dh.h:74
CRYS_DHKGData_t
struct CRYS_DHKGData_t CRYS_DHKGData_t
CRYS_DHKGData_t
Definition: crys_dh_kg.h:71
CRYS_DHKGData_t::TempBuff1
uint32_t TempBuff1[(((2048 /8)/sizeof(uint32_t))+2)]
Definition: crys_dh_kg.h:75
CRYS_DHKGData_t::TempBuff2
uint32_t TempBuff2[(((2048 /8)/sizeof(uint32_t))+2)]
Definition: crys_dh_kg.h:77
CRYS_DH_CreateDomainParams
CRYSError_t CRYS_DH_CreateDomainParams(void *rndState_ptr, SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, uint32_t modPsizeBits, uint32_t orderQsizeBits, uint32_t seedSizeBits, uint8_t *modP_ptr, uint8_t *orderQ_ptr, uint8_t *generatorG_ptr, uint32_t *generGsizeBytes_ptr, uint8_t *factorJ_ptr, uint32_t *JsizeBytes_ptr, uint8_t *seedS_ptr, int8_t generateSeed, uint32_t *pgenCounter_ptr, CRYS_DHKGData_t *DHKGbuff_ptr)
This function generates DH domain parameters in Galois prime field according to standard [ANS X9...
CRYS_DHKGData_t::TempBuff5
uint32_t TempBuff5[(((2048 /8)/sizeof(uint32_t))+2)]
Definition: crys_dh_kg.h:83
crys_dh.h
This module defines the API that supports Diffie-Hellman key exchange, as defined in [PKCS3] and in [...
CRYS_DH_CheckDomainParams
CRYSError_t CRYS_DH_CheckDomainParams(void *rndState_ptr, SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, uint8_t *modP_ptr, uint32_t modPsizeBytes, uint8_t *orderQ_ptr, uint32_t orderQsizeBytes, uint8_t *generatorG_ptr, uint32_t generatorSizeBytes, uint8_t *seedS_ptr, uint32_t seedSizeBits, uint32_t pgenCounter, CRYS_DHKG_CheckTemp_t *checkTempBuff_ptr)
This function receives DH domain parameters, seed and prime generation counter and then verifies that...
CRYS_DHKG_CheckTemp_t
struct CRYS_DHKG_CheckTemp_t CRYS_DHKG_CheckTemp_t
CRYS_DHKGData_t::TempBuff3
uint32_t TempBuff3[(((2048 /8)/sizeof(uint32_t))+2)]
Definition: crys_dh_kg.h:79
CRYS_DHKG_CheckTemp_t::DhKgBuff
CRYS_DHKGData_t DhKgBuff
Definition: crys_dh_kg.h:96
CRYSError_t
uint32_t CRYSError_t
Definition: crys_error.h:253
CRYS_DHKGData_t::TempBuff4
uint32_t TempBuff4[(((2048 /8)/sizeof(uint32_t))+2)]
Definition: crys_dh_kg.h:81
CRYS_DHKG_CheckTemp_t
Definition: crys_dh_kg.h:91
CRYS_DHKGData_t::TempBuff6
uint32_t TempBuff6[(((2048 /8)/sizeof(uint32_t))+2)]
Definition: crys_dh_kg.h:85
CRYS_DH_Temp_t
Definition: crys_dh.h:155
SaSiRndGenerateVectWorkFunc_t
uint32_t(* SaSiRndGenerateVectWorkFunc_t)(void *rndState_ptr, uint16_t outSizeBytes, uint8_t *out_ptr)
Definition: crys_rnd.h:206
CRYS_DHKGData_t::ExpTemps
CRYS_DH_Temp_t ExpTemps
Definition: crys_dh_kg.h:87
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.