owner-nrf52sdk/nRF5_SDK_15.2.0/external/nrf_cc310/include/crys_kdf.h

/**************************************************************************************
* 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