Mistake on this page?
Report an issue in GitHub or email us
crys_kdf.h
Go to the documentation of this file.
1 /**************************************************************************************
2 * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
3 * *
4 * This file and the related binary are licensed under the following license: *
5 * *
6 * ARM Object Code and Header Files License, v1.0 Redistribution. *
7 * *
8 * Redistribution and use of object code, header files, and documentation, without *
9 * modification, are permitted provided that the following conditions are met: *
10 * *
11 * 1) Redistributions must reproduce the above copyright notice and the *
12 * following disclaimer in the documentation and/or other materials *
13 * provided with the distribution. *
14 * *
15 * 2) Unless to the extent explicitly permitted by law, no reverse *
16 * engineering, decompilation, or disassembly of is permitted. *
17 * *
18 * 3) Redistribution and use is permitted solely for the purpose of *
19 * developing or executing applications that are targeted for use *
20 * on an ARM-based product. *
21 * *
22 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
23 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
24 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
25 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
26 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
28 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
33 **************************************************************************************/
34 
35 
36 #ifndef CRYS_KDF_H
37 #define CRYS_KDF_H
38 
39 
40 #include "crys_hash.h"
41 
42 #ifdef __cplusplus
43 extern "C"
44 {
45 #endif
46 
47 /*!
48 @file
49 @brief This module defines the API that supports Key derivation function in modes
50 as defined in PKCS#3, ANSI X9.42-2001, and ANSI X9.63-1999.
51 @defgroup crys_kdf CryptoCell Key Derivation APIs
52 @{
53 @ingroup cryptocell_api
54 */
55 
56 #include "crys_hash.h"
57 
58 /************************ Defines ******************************/
59 
60 /*! Shared secret value max size in bytes */
61 #define CRYS_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE 1024
62 
63 /* Count and max. sizeof OtherInfo entries (pointers to data buffers) */
64 /*! Number of other info entries. */
65 #define CRYS_KDF_COUNT_OF_OTHER_INFO_ENTRIES 5
66 /*! Maximal size of other info entry. */
67 #define CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY 64 /*!< Size is in bytes*/
68 /*! Maximal size of keying data in bytes. */
69 #define CRYS_KDF_MAX_SIZE_OF_KEYING_DATA 2048
70 
71 /************************ Enums ********************************/
72 /*! HASH operation modes */
73 typedef enum
74 {
75  /*! SHA1 mode.*/
77  /*! SHA224 mode.*/
79  /*! SHA256 mode.*/
81  /*! SHA384 mode.*/
83  /*! SHA512 mode.*/
85  /*! Maximal number of HASH modes. */
87  /*! Reserved.*/
89 
91 
92 /*! Key derivation modes. */
93 typedef enum
94 {
95  /*! ASN1 key derivation mode.*/
97  /*! Concatination key derivation mode.*/
99  /*! X963 key derivation mode.*/
101  /*! ISO 18033 KDF1 key derivation mode.*/
103  /*! ISO 18033 KDF2 key derivation mode.*/
105  /*! Maximal number of key derivation modes. */
107  /*! Reserved.*/
109 
111 
112 /************************ Typedefs ****************************/
113 
114 /*! Structure, containing the optional data (other info) for KDF,
115  if any data is not needed, then the pointer value and
116  the size must be set to NULL */
117 typedef struct
118 {
119  /*! A unique object identifier (OID), indicating algorithm(s)
120  for which the keying data is used. */
122  uint32_t SizeOfAlgorithmID; /*!< Size of algorithm ID.*/
123  /*! Public information contributed by the initiator. */
125  uint32_t SizeOfPartyUInfo; /*!< Size of the Public information contributed by the initiator. */
126  /*! Public information contributed by the responder. */
128  uint32_t SizeOfPartyVInfo; /*!< Size of the responder's public information. */
129  /*! Mutually-known private information, e.g. shared information
130  communicated throgh a separate channel. */
132  uint32_t SizeOfSuppPrivInfo; /*!< Size of the private information. */
133  /*! Mutually-known public information, */
135  uint32_t SizeOfSuppPubInfo; /*!< Size of the public information. */
136 
138 
139 /************************ Structs ******************************/
140 
141 /************************ Public Variables **********************/
142 
143 /************************ Public Functions **********************/
144 
145 /****************************************************************/
146 
147 
148 /*********************************************************************************************************/
149 /*!
150  @brief CRYS_KDF_KeyDerivFunc performs key derivation according to one of the modes defined in standards:
151  ANS X9.42-2001, ANS X9.63, ISO/IEC 18033-2.
152 
153 The present implementation of the function allows the following operation modes:
154 <ul><li> CRYS_KDF_ASN1_DerivMode - mode based on ASN.1 DER encoding; </li>
155 <li> CRYS_KDF_ConcatDerivMode - mode based on concatenation;</li>
156 <li> CRYS_KDF_X963_DerivMode = CRYS_KDF_ConcatDerivMode;</li>
157 <li> CRYS_KDF_ISO18033_KDF1_DerivMode - specific mode according to ECIES-KEM algorithm (ISO/IEC 18033-2).</li></ul>
158 
159 The purpose of this function is to derive a keying data from the shared secret value and some
160 other optional shared information (SharedInfo).
161 
162 \note
163 <ul id="noteb"><li> The length in Bytes of the hash result buffer is denoted by "hashlen".</li>
164 <li> All buffers arguments are represented in Big-Endian format.</li>
165 
166 @return CRYS_OK on success.
167 @return A non-zero value on failure as defined crys_kdf_error.h or crys_hash_error.h.
168 */
170  uint8_t *ZZSecret_ptr, /*!< [in] A pointer to shared secret value octet string. */
171  uint32_t ZZSecretSize, /*!< [in] The size of the shared secret value in bytes.
172  The maximal size is defined as: CRYS_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE. */
173  CRYS_KDF_OtherInfo_t *OtherInfo_ptr, /*!< [in] The pointer to structure, containing the data, shared by two entities of
174  agreement and the data sizes. This argument may be optional in several modes
175  (if it is not needed - set NULL).
176  On two ISO/IEC 18033-2 modes - set NULL.
177  On KDF ASN1 mode the OtherInfo and its AlgorithmID entry are mandatory. */
178  CRYS_KDF_HASH_OpMode_t KDFhashMode, /*!< [in] The KDF identifier of hash function to be used. The hash function output
179  must be at least 160 bits. */
180  CRYS_KDF_DerivFuncMode_t derivation_mode, /*!< [in] Specifies one of above described derivation modes. */
181  uint8_t *KeyingData_ptr, /*!< [out] A pointer to the buffer for derived keying data. */
182  uint32_t KeyingDataSizeBytes /*!< [in] The size in bytes of the keying data to be derived.
183  The maximal size is defined as: CRYS_KDF_MAX_SIZE_OF_KEYING_DATA. */
184 );
185 
186 /*********************************************************************************************************/
187 /*!
188  CRYS_KDF_ASN1_KeyDerivFunc is A MACRO that performs key derivation according to ASN1 DER encoding method defined
189  in standard ANS X9.42-2001, 7.2.1. For a description of the parameters see ::CRYS_KDF_KeyDerivFunc.
190 */
191 #define CRYS_KDF_ASN1_KeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,KDFhashMode,KeyingData_ptr,KeyLenInBytes)\
192  CRYS_KDF_KeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(KDFhashMode),CRYS_KDF_ASN1_DerivMode,(KeyingData_ptr),(KeyLenInBytes))
193 
194 
195 /*********************************************************************************************************/
196 /*!
197  CRYS_KDF_ConcatKeyDerivFunc is a MACRO that performs key derivation according to concatenation mode defined
198  in standard ANS X9.42-2001, 7.2.2. For a description of the parameters see
199  ::CRYS_KDF_KeyDerivFunc.
200 */
201 #define CRYS_KDF_ConcatKeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,KDFhashMode,KeyingData_ptr,KeyLenInBytes)\
202  CRYS_KDF_KeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(KDFhashMode),CRYS_KDF_ConcatDerivMode,(KeyingData_ptr),(KeyLenInBytes))
203 
204 #ifdef __cplusplus
205 }
206 #endif
207 /**
208 @}
209  */
210 #endif
211 
CRYS_KDF_HASH_OpMode_t
Definition: crys_kdf.h:73
uint32_t SizeOfSuppPubInfo
Definition: crys_kdf.h:135
#define CRYS_KDF_MAX_SIZE_OF_OTHER_INFO_ENTRY
Definition: crys_kdf.h:67
uint32_t SizeOfPartyUInfo
Definition: crys_kdf.h:125
This file contains all of the enums and definitions that are used for the CRYS HASH APIs...
uint32_t SizeOfPartyVInfo
Definition: crys_kdf.h:128
uint32_t CRYSError_t
Definition: crys_error.h:253
CRYS_KDF_DerivFuncMode_t
Definition: crys_kdf.h:93
uint32_t SizeOfSuppPrivInfo
Definition: crys_kdf.h:132
CRYSError_t CRYS_KDF_KeyDerivFunc(uint8_t *ZZSecret_ptr, uint32_t ZZSecretSize, CRYS_KDF_OtherInfo_t *OtherInfo_ptr, CRYS_KDF_HASH_OpMode_t KDFhashMode, CRYS_KDF_DerivFuncMode_t derivation_mode, uint8_t *KeyingData_ptr, uint32_t KeyingDataSizeBytes)
CRYS_KDF_KeyDerivFunc performs key derivation according to one of the modes defined in standards: ANS...
uint32_t SizeOfAlgorithmID
Definition: crys_kdf.h:122
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.