Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
crys_ecpki_build.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_ECPKI_BUILD_H
37 #define CRYS_ECPKI_BUILD_H
38 
39 /*!
40 @defgroup cryptocell_ecpki CryptoCell ECC APIs
41 @{
42 @ingroup cryptocell_api
43 @brief This group is the cryptocell ECC root group
44 @}
45 
46 @file
47 @brief This module defines functions for building key structures used in Elliptic Curves Cryptography (ECC).
48 @defgroup crys_ecpki_build CryptoCell key build for ECC APIs
49 @{
50 @ingroup cryptocell_ecpki
51 */
52 
53 
54 #include "crys_error.h"
55 #include "crys_ecpki_types.h"
56 
57 #ifdef __cplusplus
58 extern "C"
59 {
60 #endif
61 
62 /**********************************************************************************
63  * CRYS_ECPKI_BuildPrivKey function *
64  **********************************************************************************/
65 /*!
66 @brief Builds (imports) the user private key structure from an existing private key so
67 that this structure can be used by other EC primitives.
68 This function should be called before using of the private key. Input
69 domain structure must be initialized by EC parameters and auxiliary
70 values, using CRYS_ECPKI_GetDomain or CRYS_ECPKI_SetDomain functions.
71 
72 @return CRYS_OK on success.
73 @return A non-zero value on failure as defined crys_ecpki_error.h.
74 */
75 CIMPORT_C CRYSError_t CRYS_ECPKI_BuildPrivKey(
76  const CRYS_ECPKI_Domain_t *pDomain, /*!< [in] The EC domain (curve). */
77  const uint8_t *pPrivKeyIn, /*!< [in] Pointer to private key data. */
78  uint32_t PrivKeySizeInBytes, /*!< [in] Size of private key data (in bytes). */
79  CRYS_ECPKI_UserPrivKey_t *pUserPrivKey /*!< [out] Pointer to the private key structure.
80  This structure is used as input to the ECPKI cryptographic primitives. */
81  );
82 
83 /**********************************************************************************
84  * _DX_ECPKI_BuildPublKey function *
85  **********************************************************************************/
86 /*!
87 @brief Builds a user public key structure from an imported public key,
88 so it can be used by other EC primitives.
89 When operating the EC cryptographic algorithms with imported EC public
90 key, this function should be called before using of the public key.
91 
92 \note The Incoming public key PublKeyIn structure is big endian bytes array, containing
93 concatenation of PC||X||Y, where:
94 <ul id="noteb"><li> PC - point control single byte, defining the type of point: 0x4 - uncompressed,
95 06,07 - hybrid, 2,3 - compressed. </li>
96 <li>X,Y - EC point coordinates of public key (y is omitted in compressed form),
97 size of X and Y must be equal to size of EC modulus. </li></ul>
98 
99 The user may call this function by appropriate macros, according to necessary validation level [SEC1. ECC standard: 3.2, ANS X9.62]:
100 <ul><li>Checking the input pointers and sizes only - ::CRYS_ECPKI_BuildPublKey.</li>
101 <li>Partially checking of public key - ::CRYS_ECPKI_BuildPublKeyPartlyCheck. </li>
102 <li>Full checking of public key - ::CRYS_ECPKI_BuildPublKeyFullCheck. </li></ul>
103 
104 \note Full check mode takes long time and should be used when it is actually needed.
105 
106 @return CRYS_OK on success.
107 @return A non-zero value on failure as defined crys_ecpki_error.h.
108 */
109 /*
110 The function performs the following operations:
111 - Checks validity of incoming variables and pointers;
112 - Converts incoming key data from big endian into little endian;
113 - If public key is given in compressed form (i.e. byte[0] = 2 or 3 and
114  coordinate Y is omitted), then the function uncompress it;
115 - Performs checking of input key according to CheckMode parameter.
116 - Initializes variables and structures.
117 */
118 CIMPORT_C CRYSError_t _DX_ECPKI_BuildPublKey(
119  const CRYS_ECPKI_Domain_t *pDomain, /*!< [in] The EC domain (curve). */
120  uint8_t *PublKeyIn_ptr, /*!< [in] Pointer to the input public key data, in compressed or
121  uncompressed or hybrid form:
122  [PC||X||Y] Big-Endian representation, structured according to
123  [IEEE1363], where:
124  <ul><li>X and Y are the public key's EC point coordinates.
125  In compressed form, Y is omitted.</li>
126  <li> The sizes of X and Y are equal to the size of the EC modulus.</li>
127  <li> PC is a one-byte point control that defines the type of point
128  compression. </li></ul>*/
129  uint32_t PublKeySizeInBytes, /*!< [in] The size of public key data (in bytes). */
130  EC_PublKeyCheckMode_t CheckMode, /*!< [in] The required level of public key verification
131  (higher verification level means longer verification time):
132  <ul><li> 0 = preliminary validation. </li>
133  <li> 1 = partial validation. </li>
134  <li> 2 = full validation. </li></ul>*/
135  CRYS_ECPKI_UserPublKey_t *pUserPublKey, /*!< [out] Pointer to the output public key structure.
136  This structure is used as input to the ECPKI cryptographic primitives. */
137  CRYS_ECPKI_BUILD_TempData_t *pTempBuff /*!< [in] Pointer for a temporary buffer required for the build function. */
138  );
139 
140 
141 /**********************************************************************************
142  * CRYS_ECPKI_BuildPublKey macro *
143  **********************************************************************************/
144 /*!
145 @brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key
146 while checking input pointers and sizes. For a description of the parameters see ::_DX_ECPKI_BuildPublKey.
147 */
148 #define CRYS_ECPKI_BuildPublKey(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey) \
149  _DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), CheckPointersAndSizesOnly, (pUserPublKey), NULL)
150 
151 
152 /**********************************************************************************
153  * CRYS_ECPKI_BuildPublKeyPartlyCheck macro *
154  **********************************************************************************/
155 /*!
156 @brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key with partial validation of the key [SEC1] - 3.2.3.
157 For a description of the parameters see ::_DX_ECPKI_BuildPublKey.
158 */
159 #define CRYS_ECPKI_BuildPublKeyPartlyCheck(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey, pTempBuff) \
160  _DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), ECpublKeyPartlyCheck, (pUserPublKey), (pTempBuff))
161 
162 
163 /**********************************************************************************
164  * CRYS_ECPKI_BuildPublKeyFullCheck macro *
165  **********************************************************************************/
166 /*!
167 @brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key with full validation of the key [SEC1] - 3.2.2.
168 For a description of the parameters and return values see _DX_ECPKI_BuildPublKey.
169 */
170 #define CRYS_ECPKI_BuildPublKeyFullCheck(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey, pTempBuff) \
171  _DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), (ECpublKeyFullCheck), (pUserPublKey), (pTempBuff))
172 
173 
174 /***********************************************************************************
175  * CRYS_ECPKI_ExportPublKey function *
176  ***********************************************************************************/
177 /*!
178 @brief Converts an existing public key from internal representation to Big-Endian export representation.
179 The function converts the X,Y coordinates of public key EC point to big endianness,
180 and sets the public key as follows:
181 <ul><li>In case "Uncompressed" point: PubKey = PC||X||Y, PC = 0x4 - single byte;</li>
182 <li>In case of "Hybrid" key PC = 0x6.</li>
183 <li>In case of "Compressed" key PC = 0x2.</li></ul>
184 \note Size of output X and Y coordinates is equal to ModSizeInBytes.
185 @return CRYS_OK on success.
186 @return A non-zero value on failure as defined crys_ecpki_error.h.
187 */
188 CIMPORT_C CRYSError_t CRYS_ECPKI_ExportPublKey(
189  CRYS_ECPKI_UserPublKey_t *pUserPublKey, /*!< [in] Pointer to the input public key structure (in Little-Endian form). */
190  CRYS_ECPKI_PointCompression_t compression, /*!< [in] Compression mode: Compressed, Uncompressed or Hybrid. */
191  uint8_t *pExternPublKey, /*!< [out] Pointer to the exported public key array, in compressed or uncompressed
192  or hybrid form:
193  [PC||X||Y] Big-Endian representation, structured according to [IEEE1363].
194  In compressed form, Y is omitted. */
195  uint32_t *pPublKeySizeBytes /*!< [in/out] Pointer used for the input of the user public key buffer size
196  (in bytes), and the output of the size of the converted public key in bytes. */
197  );
198 
199 
200 
201 #ifdef __cplusplus
202 }
203 #endif
204 /**
205 @}
206  */
207 #endif
CRYS_ECPKI_BUILD_TempData_t
Definition: crys_ecpki_types.h:286
EC_PublKeyCheckMode_t
EC_PublKeyCheckMode_t
Definition: crys_ecpki_types.h:139
crys_ecpki_types.h
Contains all of the enums and definitions that are used for the CRYS ECPKI APIs.
CRYS_ECPKI_UserPublKey_t
Definition: crys_ecpki_types.h:240
CRYS_ECPKI_ExportPublKey
CRYSError_t CRYS_ECPKI_ExportPublKey(CRYS_ECPKI_UserPublKey_t *pUserPublKey, CRYS_ECPKI_PointCompression_t compression, uint8_t *pExternPublKey, uint32_t *pPublKeySizeBytes)
Converts an existing public key from internal representation to Big-Endian export representation...
_DX_ECPKI_BuildPublKey
CRYSError_t _DX_ECPKI_BuildPublKey(const CRYS_ECPKI_Domain_t *pDomain, uint8_t *PublKeyIn_ptr, uint32_t PublKeySizeInBytes, EC_PublKeyCheckMode_t CheckMode, CRYS_ECPKI_UserPublKey_t *pUserPublKey, CRYS_ECPKI_BUILD_TempData_t *pTempBuff)
Builds a user public key structure from an imported public key, so it can be used by other EC primiti...
CRYS_ECPKI_PointCompression_t
CRYS_ECPKI_PointCompression_t
Definition: crys_ecpki_types.h:124
CRYS_ECPKI_Domain_t
Definition: crys_ecpki_types.h:164
CRYSError_t
uint32_t CRYSError_t
Definition: crys_error.h:253
CRYS_ECPKI_UserPrivKey_t
Definition: crys_ecpki_types.h:269
CRYS_ECPKI_BuildPrivKey
CRYSError_t CRYS_ECPKI_BuildPrivKey(const CRYS_ECPKI_Domain_t *pDomain, const uint8_t *pPrivKeyIn, uint32_t PrivKeySizeInBytes, CRYS_ECPKI_UserPrivKey_t *pUserPrivKey)
Builds (imports) the user private key structure from an existing private key so that this structure c...
crys_error.h
This module defines the error return code types and the numbering spaces of the error codes for each ...
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.