Mbed OS Reference | crys_kdf.h Source File

Go to the documentation of this file.
 /**************************************************************************************
 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved         *
 *                                                                                     *
 * This file and the related binary are licensed under the following license:          *
 *                                                                                     *
 * ARM Object Code and Header Files License, v1.0 Redistribution.                      *
 *                                                                                     *
 * Redistribution and use of object code, header files, and documentation, without     *
 * modification, are permitted provided that the following conditions are met:         *
 *                                                                                     *
 * 1) Redistributions must reproduce the above copyright notice and the                *
 *    following disclaimer in the documentation and/or other materials                 *
 *    provided with the distribution.                                                  *
 *                                                                                     *
 * 2) Unless to the extent explicitly permitted by law, no reverse                     *
 *    engineering, decompilation, or disassembly of is permitted.                      *
 *                                                                                     *
 * 3) Redistribution and use is permitted solely for the purpose of                    *
 *    developing or executing applications that are targeted for use                   *
 *    on an ARM-based product.                                                         *
 *                                                                                     *
 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND                  *
 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT             *
 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT,        *
 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE          *
 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,   *
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED            *
 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR              *
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF              *
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING                *
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS                  *
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                        *
 **************************************************************************************/
 
 
 #ifndef CRYS_KDF_H
 #define CRYS_KDF_H
 
 
 #include "crys_hash.h"
 
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
 /*!
 @file
 @brief This module defines the API that supports Key derivation function in modes
 as defined in PKCS#3, ANSI X9.42-2001, and ANSI X9.63-1999.
 @defgroup crys_kdf CryptoCell Key Derivation APIs
 @{
 @ingroup cryptocell_api
 */
 
 #include "crys_hash.h"
 
 /************************ Defines ******************************/
 
 /*! Shared secret value max size in bytes */
 #define  CRYS_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE  1024
 
 /* Count and max. sizeof OtherInfo entries (pointers to data buffers) */
 /*! Number of other info entries. */
 #define  CRYS_KDF_COUNT_OF_OTHER_INFO_ENTRIES   5
 /*! Maximal size of other info entry. */
 #define  CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY  64 /*!< Size is in bytes*/
 /*! Maximal size of keying data in bytes. */
 #define  CRYS_KDF_MAX_SIZE_OF_KEYING_DATA  2048
 
 /************************ Enums ********************************/
 /*! HASH operation modes */
 typedef enum
 {
     /*! SHA1 mode.*/
     CRYS_KDF_HASH_SHA1_mode      = 0,
     /*! SHA224 mode.*/
     CRYS_KDF_HASH_SHA224_mode   = 1,
     /*! SHA256 mode.*/
     CRYS_KDF_HASH_SHA256_mode   = 2,
     /*! SHA384 mode.*/
     CRYS_KDF_HASH_SHA384_mode   = 3,
     /*! SHA512 mode.*/
     CRYS_KDF_HASH_SHA512_mode   = 4,
     /*! Maximal number of HASH modes. */
     CRYS_KDF_HASH_NumOfModes,
     /*! Reserved.*/
     CRYS_KDF_HASH_OpModeLast    = 0x7FFFFFFF,
 
 }CRYS_KDF_HASH_OpMode_t;
 
 /*! Key derivation modes. */
 typedef enum
 {
     /*! ASN1 key derivation mode.*/
     CRYS_KDF_ASN1_DerivMode    = 0,
     /*! Concatination key derivation mode.*/
     CRYS_KDF_ConcatDerivMode   = 1,
     /*! X963 key derivation mode.*/
     CRYS_KDF_X963_DerivMode    = CRYS_KDF_ConcatDerivMode,
     /*! ISO 18033 KDF1 key derivation mode.*/
     CRYS_KDF_ISO18033_KDF1_DerivMode = 3,
     /*! ISO 18033 KDF2 key derivation mode.*/
     CRYS_KDF_ISO18033_KDF2_DerivMode = 4,
     /*! Maximal number of key derivation modes. */
     CRYS_KDF_DerivFunc_NumOfModes = 5,
     /*! Reserved.*/
     CRYS_KDF_DerivFuncModeLast= 0x7FFFFFFF,
 
 }CRYS_KDF_DerivFuncMode_t;
 
 /************************ Typedefs  ****************************/
 
 /*! Structure, containing the optional data (other info) for KDF,
    if any data is not needed, then the pointer value and
    the size must be set to NULL */
 typedef struct
 {
     /*! A unique object identifier (OID), indicating algorithm(s)
     for which the keying data is used. */
     uint8_t    AlgorithmID[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
     uint32_t   SizeOfAlgorithmID; /*!< Size of algorithm ID.*/
     /*! Public information contributed by the initiator. */
     uint8_t    PartyUInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
     uint32_t   SizeOfPartyUInfo; /*!< Size of the Public information contributed by the initiator. */
     /*! Public information contributed by the responder. */
     uint8_t    PartyVInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
     uint32_t   SizeOfPartyVInfo; /*!< Size of the responder's public information. */
     /*! Mutually-known private information, e.g. shared information
     communicated throgh a separate channel. */
     uint8_t    SuppPrivInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
     uint32_t   SizeOfSuppPrivInfo; /*!< Size of the private information. */
     /*! Mutually-known public information, */
     uint8_t    SuppPubInfo[CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY];
     uint32_t   SizeOfSuppPubInfo; /*!< Size of the public information. */
 
 }CRYS_KDF_OtherInfo_t;
 
 /************************ Structs  ******************************/
 
 /************************ Public Variables **********************/
 
 /************************ Public Functions **********************/
 
 /****************************************************************/
 
 
 /*********************************************************************************************************/
 /*!
  @brief CRYS_KDF_KeyDerivFunc performs key derivation according to one of the modes defined in standards:
         ANS X9.42-2001, ANS X9.63, ISO/IEC 18033-2.
 
 The present implementation of the function allows the following operation modes:
 <ul><li> CRYS_KDF_ASN1_DerivMode - mode based on  ASN.1 DER encoding; </li>
 <li> CRYS_KDF_ConcatDerivMode - mode based on concatenation;</li>
 <li> CRYS_KDF_X963_DerivMode = CRYS_KDF_ConcatDerivMode;</li>
 <li> CRYS_KDF_ISO18033_KDF1_DerivMode - specific mode according to ECIES-KEM algorithm (ISO/IEC 18033-2).</li></ul>
 
 The purpose of this function is to derive a keying data from the shared secret value and some
 other optional shared information (SharedInfo).
 
 \note
 <ul id="noteb"><li> The length in Bytes of the hash result buffer is denoted by "hashlen".</li>
 <li> All buffers arguments are represented in Big-Endian format.</li>
 
 @return CRYS_OK on success.
 @return A non-zero value on failure as defined crys_kdf_error.h or crys_hash_error.h.
 */
 CIMPORT_C CRYSError_t  CRYS_KDF_KeyDerivFunc(
                     uint8_t                  *ZZSecret_ptr,         /*!< [in]  A pointer to shared secret value octet string. */
                     uint32_t                  ZZSecretSize,         /*!< [in]  The size of the shared secret value in bytes.
                                                                                The maximal size is defined as: CRYS_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE. */
                     CRYS_KDF_OtherInfo_t     *OtherInfo_ptr,        /*!< [in]  The pointer to structure, containing the data, shared by two entities of
                                            agreement and the data sizes. This argument may be optional in several modes
                                            (if it is not needed - set NULL).
                                                                                On two ISO/IEC 18033-2 modes - set NULL.
                                                                                On KDF ASN1 mode the OtherInfo and its AlgorithmID entry are mandatory. */
                     CRYS_KDF_HASH_OpMode_t    KDFhashMode,          /*!< [in]  The KDF identifier of hash function to be used. The hash function output
                                            must be at least 160 bits. */
                     CRYS_KDF_DerivFuncMode_t  derivation_mode,      /*!< [in]  Specifies one of above described derivation modes. */
                     uint8_t                  *KeyingData_ptr,       /*!< [out] A pointer to the buffer for derived keying data. */
                     uint32_t                  KeyingDataSizeBytes   /*!< [in]  The size in bytes of the keying data to be derived.
                                                                                The maximal size is defined as: CRYS_KDF_MAX_SIZE_OF_KEYING_DATA. */
 );
 
 /*********************************************************************************************************/
 /*!
  CRYS_KDF_ASN1_KeyDerivFunc is A MACRO that performs key derivation according to ASN1 DER encoding method defined
  in standard  ANS X9.42-2001, 7.2.1. For a description of the parameters see ::CRYS_KDF_KeyDerivFunc.
 */
 #define CRYS_KDF_ASN1_KeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,KDFhashMode,KeyingData_ptr,KeyLenInBytes)\
         CRYS_KDF_KeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(KDFhashMode),CRYS_KDF_ASN1_DerivMode,(KeyingData_ptr),(KeyLenInBytes))
 
 
 /*********************************************************************************************************/
 /*!
  CRYS_KDF_ConcatKeyDerivFunc is a MACRO that performs key derivation according to concatenation mode defined
  in standard  ANS X9.42-2001, 7.2.2. For a description of the parameters see
  ::CRYS_KDF_KeyDerivFunc.
 */
 #define CRYS_KDF_ConcatKeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,KDFhashMode,KeyingData_ptr,KeyLenInBytes)\
         CRYS_KDF_KeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(KDFhashMode),CRYS_KDF_ConcatDerivMode,(KeyingData_ptr),(KeyLenInBytes))
 
 #ifdef __cplusplus
 }
 #endif
 /**
 @}
  */
 #endif
 
Important Information for this Arm website
