1 /*
2  * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 /*!
8  @file
9  @brief This file contains the CryptoCell HKDF key-derivation function API.
10 
11  This function is as defined in
12  <em>RFC-5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)</em>.
13  */
14 
15 /*!
16  @defgroup cc_hkdf CryptoCell HKDF key-derivation function API
17  @brief Contains the CryptoCell HMAC key-derivation function API. See mbedtls_cc_hkdf.h.
18 
19  @{
20  @ingroup cryptocell_api
21  @}
22  */
23 
24 #ifndef _MBEDTLS_CC_HKDF_H
25 #define _MBEDTLS_CC_HKDF_H
26 
27 
28 #ifdef __cplusplus
29 extern "C"
30 {
31 #endif
32 
33 #include "cc_pal_types.h"
34 
35 /*! The maximal size of the HKDF key in words. */
36 #define CC_HKDF_MAX_HASH_KEY_SIZE_IN_BYTES        512
37 
38 /*! The maximal size of the HKDF hash-digest in Bytes. */
39 #define CC_HKDF_MAX_HASH_DIGEST_SIZE_IN_BYTES     CC_HASH_SHA512_DIGEST_SIZE_IN_BYTES
40 
41 /************************ Defines ******************************/
42 
43 /************************ Enums ********************************/
44 /*! Supported HKDF hash modes. */
45 typedef enum
46 {
47     /*! SHA-1 mode. */
48     CC_HKDF_HASH_SHA1_mode      = 0,
49     /*! SHA-224 mode. */
50     CC_HKDF_HASH_SHA224_mode  = 1,
51     /*! SHA-256 mode. */
52     CC_HKDF_HASH_SHA256_mode  = 2,
53     /*! SHA-384 mode. */
54     CC_HKDF_HASH_SHA384_mode  = 3,
55     /*! SHA-512 mode. */
56     CC_HKDF_HASH_SHA512_mode  = 4,
57     /*! The maximal number of hash modes. */
58     CC_HKDF_HASH_NumOfModes,
59     /*! Reserved. */
60     CC_HKDF_HASH_OpModeLast    = 0x7FFFFFFF,
61 
62 }mbedtls_hkdf_hashmode_t;
63 
64 /************************ Typedefs  ****************************/
65 
66 /************************ Structs  ******************************/
67 
68 /************************ Public Variables **********************/
69 
70 /************************ Public Functions **********************/
71 
72 /****************************************************************/
73 
74 
75 /*********************************************************************************************************/
76 /*!
77   @brief mbedtls_hkdf_key_derivation() performs the HMAC-based key derivation, as define by
78   <em>RFC-5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)</em>.
79 
80   @return \c CC_OK on success.
81   @return A non-zero value on failure as defined in cc_kdf_error.h, or in md.h.
82 */
83 CCError_t  mbedtls_hkdf_key_derivation(
84             mbedtls_hkdf_hashmode_t    HKDFhashMode,   /*!< [in] The HKDF identifier of the hash function to be used. */
85             uint8_t*                   Salt_ptr,       /*!< [in] A pointer to a non-secret random value. Can be NULL. */
86             size_t                     SaltLen,        /*!< [in] The size of the \p Salt_ptr. */
87             uint8_t*                   Ikm_ptr,        /*!< [in] A pointer to an input key message. */
88             uint32_t                   IkmLen,         /*!< [in] The size of the input key message */
89             uint8_t*                   Info,           /*!< [in] A pointer to an optional context and application-specific information. Can be NULL */
90             uint32_t                   InfoLen,        /*!< [in] The size of the application-specific information. */
91             uint8_t*                   Okm,            /*!< [in] A pointer to an output key material. */
92             uint32_t                   OkmLen,         /*!< [in] The size of the output key material. */
93             CCBool                     IsStrongKey     /*!< [in] If TRUE, no need to perform the extraction phase. */
94 );
95 
96 #ifdef __cplusplus
97 }
98 #endif
99 
100 #endif
101 
102