crys_kdf.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 #ifndef CRYS_KDF_H
00037 #define CRYS_KDF_H
00038 
00039 
00040 #include "crys_hash.h"
00041 
00042 #ifdef __cplusplus
00043 extern "C"
00044 {
00045 #endif
00046 
00047 /*!
00048 @file
00049 @brief This module defines the API that supports Key derivation function in modes
00050 as defined in PKCS#3, ANSI X9.42-2001, and ANSI X9.63-1999.
00051 @defgroup crys_kdf CryptoCell Key Derivation APIs
00052 @{
00053 @ingroup cryptocell_api
00054 */
00055 
00056 #include "crys_hash.h"
00057 
00058 /************************ Defines ******************************/
00059 
00060 /*! Shared secret value max size in bytes */
00061 #define  CRYS_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE  1024
00062 
00063 /* Count and max. sizeof OtherInfo entries (pointers to data buffers) */
00064 /*! Number of other info entries. */
00065 #define  CRYS_KDF_COUNT_OF_OTHER_INFO_ENTRIES   5
00066 /*! Maximal size of other info entry. */
00067 #define  CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY  64 /*!< Size is in bytes*/
00068 /*! Maximal size of keying data in bytes. */
00069 #define  CRYS_KDF_MAX_SIZE_OF_KEYING_DATA  2048
00070 
00071 /************************ Enums ********************************/
00072 /*! HASH operation modes */
00073 typedef enum
00074 {
00075     /*! SHA1 mode.*/
00076     CRYS_KDF_HASH_SHA1_mode       = 0,
00077     /*! SHA224 mode.*/
00078     CRYS_KDF_HASH_SHA224_mode    = 1,
00079     /*! SHA256 mode.*/
00080     CRYS_KDF_HASH_SHA256_mode    = 2,
00081     /*! SHA384 mode.*/
00082     CRYS_KDF_HASH_SHA384_mode    = 3,
00083     /*! SHA512 mode.*/
00084     CRYS_KDF_HASH_SHA512_mode    = 4,
00085     /*! Maximal number of HASH modes. */
00086     CRYS_KDF_HASH_NumOfModes ,
00087     /*! Reserved.*/
00088     CRYS_KDF_HASH_OpModeLast     = 0x7FFFFFFF,
00089 
00090 }CRYS_KDF_HASH_OpMode_t ;
00091 
00092 /*! Key derivation modes. */
00093 typedef enum
00094 {
00095     /*! ASN1 key derivation mode.*/
00096     CRYS_KDF_ASN1_DerivMode     = 0,
00097     /*! Concatination key derivation mode.*/
00098     CRYS_KDF_ConcatDerivMode    = 1,
00099     /*! X963 key derivation mode.*/
00100     CRYS_KDF_X963_DerivMode     = CRYS_KDF_ConcatDerivMode ,
00101     /*! ISO 18033 KDF1 key derivation mode.*/
00102     CRYS_KDF_ISO18033_KDF1_DerivMode  = 3,
00103     /*! ISO 18033 KDF2 key derivation mode.*/
00104     CRYS_KDF_ISO18033_KDF2_DerivMode  = 4,
00105     /*! Maximal number of key derivation modes. */
00106     CRYS_KDF_DerivFunc_NumOfModes  = 5,
00107     /*! Reserved.*/
00108     CRYS_KDF_DerivFuncModeLast = 0x7FFFFFFF,
00109 
00110 }CRYS_KDF_DerivFuncMode_t ;
00111 
00112 /************************ Typedefs  ****************************/
00113 
00114 /*! Structure, containing the optional data (other info) for KDF,
00115    if any data is not needed, then the pointer value and
00116    the size must be set to NULL */
00117 typedef struct
00118 {
00119     /*! A unique object identifier (OID), indicating algorithm(s)
00120     for which the keying data is used. */
00121     uint8_t    AlgorithmID[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
00122     uint32_t   SizeOfAlgorithmID ; /*!< Size of algorithm ID.*/
00123     /*! Public information contributed by the initiator. */
00124     uint8_t    PartyUInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
00125     uint32_t   SizeOfPartyUInfo ; /*!< Size of the Public information contributed by the initiator. */
00126     /*! Public information contributed by the responder. */
00127     uint8_t    PartyVInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
00128     uint32_t   SizeOfPartyVInfo ; /*!< Size of the responder's public information. */
00129     /*! Mutually-known private information, e.g. shared information
00130     communicated throgh a separate channel. */
00131     uint8_t    SuppPrivInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
00132     uint32_t   SizeOfSuppPrivInfo ; /*!< Size of the private information. */
00133     /*! Mutually-known public information, */
00134     uint8_t    SuppPubInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
00135     uint32_t   SizeOfSuppPubInfo ; /*!< Size of the public information. */
00136 
00137 }CRYS_KDF_OtherInfo_t ;
00138 
00139 /************************ Structs  ******************************/
00140 
00141 /************************ Public Variables **********************/
00142 
00143 /************************ Public Functions **********************/
00144 
00145 /****************************************************************/
00146 
00147 
00148 /*********************************************************************************************************/
00149 /*!
00150  @brief CRYS_KDF_KeyDerivFunc performs key derivation according to one of the modes defined in standards:
00151         ANS X9.42-2001, ANS X9.63, ISO/IEC 18033-2.
00152 
00153 The present implementation of the function allows the following operation modes:
00154 <ul><li> CRYS_KDF_ASN1_DerivMode - mode based on  ASN.1 DER encoding; </li>
00155 <li> CRYS_KDF_ConcatDerivMode - mode based on concatenation;</li>
00156 <li> CRYS_KDF_X963_DerivMode = CRYS_KDF_ConcatDerivMode;</li>
00157 <li> CRYS_KDF_ISO18033_KDF1_DerivMode - specific mode according to ECIES-KEM algorithm (ISO/IEC 18033-2).</li></ul>
00158 
00159 The purpose of this function is to derive a keying data from the shared secret value and some
00160 other optional shared information (SharedInfo).
00161 
00162 \note
00163 <ul id="noteb"><li> The length in Bytes of the hash result buffer is denoted by "hashlen".</li>
00164 <li> All buffers arguments are represented in Big-Endian format.</li>
00165 
00166 @return CRYS_OK on success.
00167 @return A non-zero value on failure as defined crys_kdf_error.h or crys_hash_error.h.
00168 */
00169 CIMPORT_C CRYSError_t   CRYS_KDF_KeyDerivFunc(
00170                     uint8_t                  *ZZSecret_ptr,         /*!< [in]  A pointer to shared secret value octet string. */
00171                     uint32_t                  ZZSecretSize,         /*!< [in]  The size of the shared secret value in bytes.
00172                                                                                The maximal size is defined as: CRYS_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE. */
00173                     CRYS_KDF_OtherInfo_t      *OtherInfo_ptr,        /*!< [in]  The pointer to structure, containing the data, shared by two entities of
00174                                            agreement and the data sizes. This argument may be optional in several modes
00175                                            (if it is not needed - set NULL).
00176                                                                                On two ISO/IEC 18033-2 modes - set NULL.
00177                                                                                On KDF ASN1 mode the OtherInfo and its AlgorithmID entry are mandatory. */
00178                     CRYS_KDF_HASH_OpMode_t     KDFhashMode,          /*!< [in]  The KDF identifier of hash function to be used. The hash function output
00179                                            must be at least 160 bits. */
00180                     CRYS_KDF_DerivFuncMode_t   derivation_mode,      /*!< [in]  Specifies one of above described derivation modes. */
00181                     uint8_t                  *KeyingData_ptr,       /*!< [out] A pointer to the buffer for derived keying data. */
00182                     uint32_t                  KeyingDataSizeBytes   /*!< [in]  The size in bytes of the keying data to be derived.
00183                                                                                The maximal size is defined as: CRYS_KDF_MAX_SIZE_OF_KEYING_DATA. */
00184 );
00185 
00186 /*********************************************************************************************************/
00187 /*!
00188  CRYS_KDF_ASN1_KeyDerivFunc is A MACRO that performs key derivation according to ASN1 DER encoding method defined
00189  in standard  ANS X9.42-2001, 7.2.1. For a description of the parameters see ::CRYS_KDF_KeyDerivFunc.
00190 */
00191 #define CRYS_KDF_ASN1_KeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,KDFhashMode,KeyingData_ptr,KeyLenInBytes)\
00192         CRYS_KDF_KeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(KDFhashMode),CRYS_KDF_ASN1_DerivMode,(KeyingData_ptr),(KeyLenInBytes))
00193 
00194 
00195 /*********************************************************************************************************/
00196 /*!
00197  CRYS_KDF_ConcatKeyDerivFunc is a MACRO that performs key derivation according to concatenation mode defined
00198  in standard  ANS X9.42-2001, 7.2.2. For a description of the parameters see
00199  ::CRYS_KDF_KeyDerivFunc.
00200 */
00201 #define CRYS_KDF_ConcatKeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,KDFhashMode,KeyingData_ptr,KeyLenInBytes)\
00202         CRYS_KDF_KeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(KDFhashMode),CRYS_KDF_ConcatDerivMode,(KeyingData_ptr),(KeyLenInBytes))
00203 
00204 #ifdef __cplusplus
00205 }
00206 #endif
00207 /**
00208 @}
00209  */
00210 #endif
00211