crys_rnd.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_RND_H
00039 #define CRYS_RND_H
00040 
00041 #include "crys_error.h"
00042 #include "ssi_aes.h"
00043 
00044 #ifdef __cplusplus
00045 extern "C"
00046 {
00047 #endif
00048 
00049 /*!
00050 @file
00051 @brief This file contains the CRYS APIs used for random number generation.
00052 The random-number generation module implements referenced standard [SP800-90].
00053 @defgroup crys_rnd CryptoCell Random Generator APIs
00054 @{
00055 @ingroup cryptocell_api
00056 */
00057 
00058 /************************ Defines ******************************/
00059 
00060 /*!  Maximal reseed counter - indicates maximal number of
00061 requests allowed between reseeds; according to NIST 800-90
00062 it is (2^48 - 1), our restriction is :  (0xFFFFFFFF - 0xF).*/
00063 #define CRYS_RND_MAX_RESEED_COUNTER     (0xFFFFFFFF - 0xF)
00064 
00065 /* Max size for one RNG generation (in bits) =
00066   max_num_of_bits_per_request = 2^19 (FIPS 800-90 Tab.3) */
00067 /*! Maximal size of generated vector in bits. */
00068 #define CRYS_RND_MAX_GEN_VECTOR_SIZE_BITS       0x7FFFF
00069 /*! Maximal size of generated vector in bytes. */
00070 #define CRYS_RND_MAX_GEN_VECTOR_SIZE_BYTES      0xFFFF
00071 
00072 /*! AES output block size in words. */
00073 #define CRYS_RND_AES_BLOCK_SIZE_IN_WORDS  SASI_AES_BLOCK_SIZE_IN_WORDS
00074 
00075 
00076 /* RND seed and additional input sizes */
00077 /*! Maximal size of random seed in words. */
00078 #define CRYS_RND_SEED_MAX_SIZE_WORDS                  12
00079 
00080 #ifndef CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS
00081 /*! Maximal size of additional input data in words. */
00082 #define CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS CRYS_RND_SEED_MAX_SIZE_WORDS
00083 #endif
00084 
00085 /* allowed sizes of AES Key, in words */
00086 /*! AES key size (128 bits) in words. */
00087 #define CRYS_RND_AES_KEY_128_SIZE_WORDS  4
00088 /*! AES key size (192 bits) in words. */
00089 #define CRYS_RND_AES_KEY_192_SIZE_WORDS  6
00090 /*! AES key size (256 bits) in words. */
00091 #define CRYS_RND_AES_KEY_256_SIZE_WORDS  8
00092 
00093 /*   Definitions of temp buffer for RND_DMA version of CRYS_RND   */
00094 /*******************************************************************/
00095 /*   Definitions of temp buffer for DMA version of CRYS_RND   */
00096 
00097 /*! Temporary buffer size in words. */
00098 #define CRYS_RND_WORK_BUFFER_SIZE_WORDS 1528
00099 
00100 /*! A definition for RAM buffer to be internally used in instantiation (or reseeding) operation. */
00101 typedef struct
00102 {
00103     /*! Internal buffer*/
00104     uint32_t crysRndWorkBuff[CRYS_RND_WORK_BUFFER_SIZE_WORDS];
00105 }CRYS_RND_WorkBuff_t ;
00106 
00107 /*! A definition for entropy estimation data type. */
00108 #define CRYS_RND_EntropyEstimatData_t  CRYS_RND_WorkBuff_t
00109 /*! A definition for entropy estimation buffer. */
00110 #define crysRndEntrIntBuff  crysRndWorkBuff
00111 
00112 
00113 /* RND source buffer inner (entrpopy) offset       */
00114 /*! An internal offset definition. */
00115 #define CRYS_RND_TRNG_SRC_INNER_OFFSET_WORDS    2
00116 /*! An internal offset definition. */
00117 #define CRYS_RND_TRNG_SRC_INNER_OFFSET_BYTES    (CRYS_RND_TRNG_SRC_INNER_OFFSET_WORDS*sizeof(uint32_t))
00118 
00119 
00120 
00121 
00122 /* Size of the expected output buffer used by FIPS KAT */
00123 /*! FIPS Known answer test output size. */
00124 #define CRYS_PRNG_FIPS_KAT_OUT_DATA_SIZE      64
00125 
00126 /************************ Enumerators  ****************************/
00127 
00128 /*! Definition of random operation modes. */
00129 typedef  enum
00130 {
00131     /*! SW entropy estimation mode. */
00132     CRYS_RND_Fast   = 0,
00133     /*! Full entropy mode. */
00134     CRYS_RND_Slow   = 1,
00135     /*! Reserved. */
00136     CRYS_RND_ModeLast  = 0x7FFFFFFF,
00137 } CRYS_RND_mode_t ;
00138 
00139 
00140 
00141 /************************ Structs  *****************************/
00142 
00143 
00144 /* The internal state of DRBG mechanism based on AES CTR and CBC-MAC
00145    algorithms. It is set as global data defined by the following
00146    structure  */
00147 /*! RND state structure. Includes internal data that needs to be saved between boots by the user.*/
00148 typedef  struct
00149 {
00150     /* Seed buffer, consists from concatenated Key||V: max size 12 words */
00151     /*! Random Seed buffer */
00152     uint32_t  Seed[CRYS_RND_SEED_MAX_SIZE_WORDS];
00153     /* Previous value for continuous test */
00154     /*! Previous random data (used for continuous test). */
00155     uint32_t  PreviousRandValue[SASI_AES_BLOCK_SIZE_IN_WORDS];
00156 
00157     /* AdditionalInput buffer max size = seed max size words + 4w for padding*/
00158     /*! Previous additional input buffer. */
00159     uint32_t  PreviousAdditionalInput[CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS+5];
00160     /*! Additional input buffer. */
00161     uint32_t  AdditionalInput[CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS+4];
00162     /*! Additional input size in words. */
00163     uint32_t  AddInputSizeWords ; /* size of additional data set by user, words   */
00164 
00165     /*! Entropy source size in words */
00166     uint32_t  EntropySourceSizeWords ;
00167 
00168     /*! Reseed counter (32 bits active) - indicates number of requests for entropy
00169     since instantiation or reseeding */
00170     uint32_t  ReseedCounter ;
00171 
00172     /*! Key size: 4 or 8 words according to security strength 128 bits or 256 bits*/
00173     uint32_t KeySizeWords ;
00174 
00175     /* State flag (see definition of StateFlag above), containing bit-fields, defining:
00176     - b'0: instantiation steps:   0 - not done, 1 - done;
00177     - 2b'9,8: working or testing mode: 0 - working, 1 - KAT DRBG test, 2 -
00178       KAT TRNG test;
00179     b'16: flag defining is Previous random valid or not:
00180             0 - not valid, 1 - valid */
00181     /*! State flag used internally in the code.*/
00182     uint32_t StateFlag ;
00183 
00184     /* Trng processing flag - indicates which ROSC lengths are:
00185     -  allowed (bits 0-3);
00186     -  total started (bits 8-11);
00187     -  processed (bits 16-19);
00188     -  started, but not processed (bits24-27)              */
00189     /*! TRNG process state used internally in the code */
00190     uint32_t TrngProcesState ;
00191 
00192     /* validation tag */
00193     /*! Validation tag used internally in the code */
00194     uint32_t ValidTag ;
00195 
00196     /*! Rnd source entropy size in bits */
00197     uint32_t  EntropySizeBits ;
00198 
00199 } CRYS_RND_State_t ;
00200 
00201 
00202 /*! The RND Generate vector function pointer type definition.
00203    The prototype intendent for External and CRYS internal RND functions
00204    pointers definitions.
00205    Full description can be found in ::CRYS_RND_GenerateVector function API. */
00206 typedef uint32_t (*SaSiRndGenerateVectWorkFunc_t )(        \
00207                 void  *rndState_ptr, /*context*/   \
00208                 uint16_t          outSizeBytes,   /*in*/      \
00209                 uint8_t          *out_ptr         /*out*/);
00210 
00211 
00212 
00213 /*! Data structure required for internal FIPS verification for PRNG KAT. */
00214 typedef  struct
00215 {
00216        /*! Internal working buffer. */
00217        CRYS_RND_WorkBuff_t       rndWorkBuff ;
00218        /*! Output buffer. */
00219        uint8_t                  rndOutputBuff[CRYS_PRNG_FIPS_KAT_OUT_DATA_SIZE];
00220 } CRYS_PrngFipsKatCtx_t ;
00221 
00222 
00223 /*****************************************************************************/
00224 /**********************        Public Functions      *************************/
00225 /*****************************************************************************/
00226 
00227 /*!
00228 @brief This function initializes the RND context.
00229 It must be called at least once prior to using this context with any API that requires it as a parameter (e.g., other RND APIs, asymmetric
00230 cryptography key generation and signatures).
00231 It is called as part of ARM TrustZone CryptoCell library initialization, which initializes and returns the primary RND context.
00232 This primary context can be used as a single global context for all RND needs.
00233 Alternatively, other contexts may be initialized and used with a more limited scope (for specific applications or specific threads).
00234 The call to this function must be followed by a call to ::CRYS_RND_SetGenerateVectorFunc API to set the generate vector function.
00235 It implements referenced standard [SP800-90] - 10.2.1.3.2 - CTR-DRBG Instantiate algorithm using AES (FIPS-PUB 197) and Derivation Function (DF).
00236 \note Additional data can be mixed with the random seed (personalization data or nonce). If required, this data should be provided by calling ::CRYS_RND_AddAdditionalInput prior to using this API.
00237 
00238 @return CRYS_OK on success.
00239 @return A non-zero value from crys_rnd_error.h on failure.
00240 */
00241 CIMPORT_C CRYSError_t  CRYS_RND_Instantiation(
00242                         void   *rndState_ptr,       /*!< [in/out]  Pointer to the RND state buffer allocated by the user, which is used to
00243                                            maintain the RND state. This context state must be saved and provided as a
00244                                            parameter to any API that uses the RND module.
00245                                            \note the context must be cleared before sent to the function. */
00246                         CRYS_RND_WorkBuff_t   *rndWorkBuff_ptr       /*!< [in/out] Scratchpad for the RND module's work. */
00247 );
00248 
00249 
00250 /*!
00251 @brief Clears existing RNG instantiation state.
00252 
00253 @return CRYS_OK on success.
00254 @return A non-zero value from crys_rnd_error.h on failure.
00255 */
00256 CIMPORT_C CRYSError_t  CRYS_RND_UnInstantiation(
00257                         void *rndState_ptr       /*!< [in/out] Pointer to the RND context state buffer. */
00258 );
00259 
00260 
00261 /*!
00262 @brief This function is used for reseeding the RNG with additional entropy and additional user-provided input.
00263 (additional data should be provided by calling ::CRYS_RND_AddAdditionalInput prior to using this API).
00264 It implements referenced standard [SP800-90] - 10.2.1.4.2 - CTR-DRBG Reseeding algorithm, using AES (FIPS-PUB 197) and Derivation Function (DF).
00265 
00266 @return CRYS_OK on success.
00267 @return A non-zero value from crys_rnd_error.h on failure.
00268 */
00269 CIMPORT_C CRYSError_t  CRYS_RND_Reseeding(
00270                         void   *rndState_ptr,          /*!< [in/out] Pointer to the RND context buffer. */
00271                         CRYS_RND_WorkBuff_t   *rndWorkBuff_ptr      /*!< [in/out] Scratchpad for the RND module's work. */
00272 );
00273 
00274 
00275 /****************************************************************************************/
00276 /*!
00277 @brief Generates a random vector according to the algorithm defined in referenced standard [SP800-90] - 10.2.1.5.2 - CTR-DRBG.
00278 The generation algorithm uses AES (FIPS-PUB 197) and Derivation Function (DF).
00279 
00280 \note
00281 <ul id="noteb"><li> The RND module must be instantiated prior to invocation of this API.</li>
00282 <li> In the following cases, Reseeding operation must be performed prior to vector generation:</li>
00283     <ul><li> Prediction resistance is required.</li>
00284     <li> The function returns CRYS_RND_RESEED_COUNTER_OVERFLOW_ERROR, stating that the Reseed Counter has passed its upper-limit (2^32-2).</li></ul></ul>
00285 
00286 @return CRYS_OK on success.
00287 @return A non-zero value from crys_rnd_error.h on failure.
00288 */
00289 CIMPORT_C CRYSError_t  CRYS_RND_GenerateVector(
00290                             void *rndState_ptr,     /*!< [in/out] Pointer to the RND state structure, which is part of the RND context structure.
00291                                      Use rndContext->rndState field of the context for this parameter. */
00292                             uint16_t   outSizeBytes,            /*!< [in]  The size in bytes of the random vector required. The maximal size is 2^16 -1 bytes. */
00293                             uint8_t   *out_ptr                  /*!< [out] The pointer to output buffer. */
00294 );
00295 
00296 
00297 
00298 /**********************************************************************************************************/
00299 /*!
00300 @brief Generates a random vector with specific limitations by testing candidates (described and used in FIPS 186-4: B.1.2, B.4.2 etc.).
00301 
00302 This function draws a random vector, compare it to the range limits, and if within range - return it in rndVect_ptr.
00303 If outside the range, the function continues retrying until a conforming vector is found, or the maximal retries limit is exceeded.
00304 If maxVect_ptr is provided, rndSizeInBits specifies its size, and the output vector must conform to the range [1 < rndVect < maxVect].
00305 If maxVect_ptr is NULL, rndSizeInBits specifies the exact required vector size, and the output vector must be the exact same
00306 bit size (with its most significant bit = 1).
00307 \note
00308 The RND module must be instantiated prior to invocation of this API.
00309 
00310 @return CRYS_OK on success.
00311 @return A non-zero value from crys_rnd_error.h on failure.
00312 */
00313 CIMPORT_C CRYSError_t  CRYS_RND_GenerateVectorInRange(
00314                     void   *rndState_ptr,                 /*!< [in/out] Pointer to the RND state structure. */
00315                     SaSiRndGenerateVectWorkFunc_t  rndGenerateVectFunc,   /*!< [in] Pointer to the random vector generation function. */
00316                     uint32_t  rndSizeInBits,                /*!< [in]  The size in bits of the random vector required. The allowed size in range  2 <= rndSizeInBits < 2^19-1, bits. */
00317                     uint8_t  *maxVect_ptr,                  /*!< [in]  Pointer to the vector defining the upper limit for the random vector output, Given as little-endian byte array.
00318                                                                        If not NULL, its actual size is treated as [(rndSizeInBits+7)/8] bytes and its value must be in range (3, 2^19) */
00319                     uint8_t  *rndVect_ptr                   /*!< [in/out] Pointer to the output buffer for the random vector. Must be at least [(rndSizeInBits+7)/8] bytes.
00320                                                                  Treated as little-endian byte array. */
00321 );
00322 
00323 
00324 /*************************************************************************************/
00325 /*!
00326 @brief Used for adding additional input/personalization data provided by the user,
00327 to be later used by the ::CRYS_RND_Instantiation/::CRYS_RND_Reseeding/::CRYS_RND_GenerateVector functions.
00328 
00329 @return CRYS_OK on success.
00330 @return A non-zero value from crys_rnd_error.h on failure.
00331 */
00332 CIMPORT_C CRYSError_t  CRYS_RND_AddAdditionalInput(
00333                             void *rndState_ptr,         /*!< [in/out] Pointer to the RND context state buffer. */
00334                             uint8_t *additonalInput_ptr,            /*!< [in]  The Additional Input buffer. */
00335                             uint16_t additonalInputSize             /*!< [in]  The size of the Additional Input buffer. It must
00336                                                                                be <= CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS and a multiple of 4. */
00337 );
00338 
00339 /*!
00340 @brief The CRYS_RND_EnterKatMode function sets KAT mode bit into StateFlag of global CRYS_RND_WorkingState structure.
00341 
00342 The user must call this function before calling functions performing KAT tests.
00343 
00344 \note Total size of entropy and nonce must be not great than 126 words (maximal size of entropy and nonce).
00345 
00346 @return CRYS_OK on success.
00347 @return A non-zero value from crys_rnd_error.h on failure.
00348 */
00349 CIMPORT_C CRYSError_t  CRYS_RND_EnterKatMode(
00350             void   *rndState_ptr,       /*!< [in/out] Pointer to the RND context state buffer. */
00351             uint8_t            *entrData_ptr,       /*!< [in] Entropy data. */
00352             uint32_t            entrSize,           /*!< [in] Entropy size in bytes. */
00353             uint8_t            *nonce_ptr,          /*!< [in] Nonce. */
00354             uint32_t            nonceSize,          /*!< [in] Entropy size in bytes. */
00355             CRYS_RND_WorkBuff_t   *workBuff_ptr      /*!< [out] RND working buffer, must be the same buffer, which should be passed into
00356                             Instantiation/Reseeding functions. */
00357 );
00358 
00359 /**********************************************************************************************************/
00360 /*!
00361 @brief The CRYS_RND_DisableKatMode function disables KAT mode bit into StateFlag of global CRYS_RND_State_t structure.
00362 
00363 The user must call this function after KAT tests before actual using RND module (Instantiation etc.).
00364 
00365 @return CRYS_OK on success.
00366 @return A non-zero value from crys_rnd_error.h on failure.
00367 */
00368 CIMPORT_C void CRYS_RND_DisableKatMode(
00369                     void   *rndState_ptr     /*!< [in/out] Pointer to the RND state buffer. */
00370 );
00371 
00372 
00373 #ifdef __cplusplus
00374 }
00375 #endif
00376 /**
00377 @}
00378  */
00379 #endif /* #ifndef CRYS_RND_H */
00380