crys_hkdf.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_HKDF_H
00037 #define CRYS_HKDF_H
00038 
00039 #include "crys_hash.h"
00040 
00041 #ifdef __cplusplus
00042 extern "C"
00043 {
00044 #endif
00045 
00046 /*!
00047 @file
00048 @brief This module defines the API that supports HMAC Key derivation function as defined by RFC5869.
00049 @defgroup crys_hkdf CryptoCell HMAC Key Derivation APIs
00050 @{
00051 @ingroup cryptocell_api
00052 */
00053 
00054 /*! HKDF maximal key size in words. */
00055 #define CRYS_HKDF_MAX_HASH_KEY_SIZE_IN_BYTES        512
00056 
00057 /*! HKDF maximal HASH digest size in bytes. */
00058 #define CRYS_HKDF_MAX_HASH_DIGEST_SIZE_IN_BYTES     CRYS_HASH_SHA512_DIGEST_SIZE_IN_BYTES
00059 
00060 /************************ Defines ******************************/
00061 
00062 /************************ Enums ********************************/
00063 
00064 /*! Enum defining HKDF HASH available modes. */
00065 typedef enum
00066 {
00067         /*! SHA1 mode. */
00068     CRYS_HKDF_HASH_SHA1_mode       = 0,
00069     /*! SHA224 mode. */
00070     CRYS_HKDF_HASH_SHA224_mode   = 1,
00071     /*! SHA256 mode. */
00072     CRYS_HKDF_HASH_SHA256_mode   = 2,
00073     /*! SHA384 mode. */
00074     CRYS_HKDF_HASH_SHA384_mode   = 3,
00075     /*! SHA512 mode. */
00076     CRYS_HKDF_HASH_SHA512_mode   = 4,
00077 
00078     /*! Maximal number of HASH modes. */
00079     CRYS_HKDF_HASH_NumOfModes ,
00080 
00081     /*! Reserved */
00082     CRYS_HKDF_HASH_OpModeLast     = 0x7FFFFFFF,
00083 
00084 }CRYS_HKDF_HASH_OpMode_t ;
00085 
00086 /************************ Typedefs  ****************************/
00087 
00088 /************************ Structs  ******************************/
00089 
00090 /************************ Public Variables **********************/
00091 
00092 /************************ Public Functions **********************/
00093 
00094 /****************************************************************/
00095 
00096 
00097 /*********************************************************************************************************/
00098 /*!
00099 @brief CRYS_HKDF_KeyDerivFunc performs the HMAC-based key derivation, according to RFC5869
00100 
00101 @return CRYS_OK on success.
00102 @return A non-zero value on failure as defined crys_kdf_error.h, crys_hash_error or crys_hmac_error.h
00103 */
00104 CEXPORT_C CRYSError_t   CRYS_HKDF_KeyDerivFunc(
00105                         CRYS_HKDF_HASH_OpMode_t  HKDFhashMode,   /*!< [in]   The HKDF identifier of hash function to be used. */
00106                         uint8_t*                Salt_ptr,       /*!< [in]   A pointer to a non secret random value. can be NULL. */
00107                         size_t                  SaltLen,        /*!< [in]   The size of the salt_ptr. */
00108                         uint8_t*                Ikm_ptr,        /*!< [in]    A pointer to a input key message. */
00109                         uint32_t                IkmLen,         /*!< [in]   The size of the input key message */
00110                         uint8_t*                Info,           /*!< [in]   A pointer to an optional context and application specific information. can be NULL */
00111                         uint32_t                InfoLen,        /*!< [in]   The size of the info. */
00112                         uint8_t*                Okm,            /*!< [in]   A pointer to a output key material. */
00113                         uint32_t                OkmLen,         /*!< [in]   The size of the output key material. */
00114                         SaSiBool                 IsStrongKey    /*!< [in]    if TRUE , then no need to perform the extraction phase. */
00115                         );
00116 
00117 #ifdef __cplusplus
00118 }
00119 #endif
00120 /**
00121 @}
00122  */
00123 #endif
00124