1 /*
2  * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef _CC_ECPKI_BUILD_H
8 #define _CC_ECPKI_BUILD_H
9 
10 /*!
11 @file
12 @brief This file defines functions for building key structures used in Elliptic Curves Cryptography (ECC).
13 @defgroup cryptocell_ecpki CryptoCell ECC APIs
14 @{
15 @ingroup cryptocell_api
16 
17 */
18 
19 
20 #include "cc_error.h"
21 #include "cc_ecpki_types.h"
22 
23 #ifdef __cplusplus
24 extern "C"
25 {
26 #endif
27 
28 /**********************************************************************************
29  *                    CC_EcpkiPrivKeyBuild function                            *
30  **********************************************************************************/
31 /*!
32 @brief Builds (imports) the user private key structure from an existing private key so
33 that this structure can be used by other EC primitives.
34 This function should be called before using of the private key. Input
35 domain structure must be initialized by EC parameters and auxiliary
36 values, using CC_EcpkiGetDomain or CC_EcpkiSetDomain functions.
37 
38 @return CC_OK on success.
39 @return A non-zero value on failure as defined cc_ecpki_error.h.
40 */
41 CIMPORT_C CCError_t CC_EcpkiPrivKeyBuild(
42                      const CCEcpkiDomain_t *pDomain,            /*!< [in] The EC domain (curve). */
43                      const uint8_t         *pPrivKeyIn,         /*!< [in] Pointer to private key data. */
44                      size_t                 PrivKeySizeInBytes, /*!< [in] Size of private key data (in bytes). */
45                      CCEcpkiUserPrivKey_t  *pUserPrivKey        /*!< [out] Pointer to the private key structure.
46                                                    This structure is used as input to the ECPKI cryptographic primitives. */
47                      );
48 
49 /**********************************************************************************
50  *                CC_EcpkiPublKeyBuildAndCheck function                             *
51  **********************************************************************************/
52 /*!
53 @brief Builds a user public key structure from an imported public key,
54 so it can be used by other EC primitives.
55 When operating the EC cryptographic algorithms with imported EC public
56 key, this function should be called before using of the public key.
57 
58 \note The Incoming public key PublKeyIn structure is big endian bytes array, containing
59 concatenation of PC||X||Y. \par
60 \note PC - point control single byte, defining the type of point: 0x4 - uncompressed,
61 06,07 - hybrid, 2,3 - compressed. \par
62 \note X,Y - EC point coordinates of public key (y is omitted in compressed form),
63 size of X and Y must be equal to size of EC modulus.
64 
65 The user may call this function by appropriate macros, according to the necessary validation level in section SEC1. ECC standard: 3.2 of Standards for
66 Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and ANSI X9.62-2005: Public Key Cryptography for the Financial Services Industry,
67 The Elliptic Curve Digital Signature Algorithm (ECDSA):
68 <ul><li>Checking the input pointers and sizes only - ::CC_EcpkiPubKeyBuild.</li>
69 <li>Partially checking of public key - ::CC_EcpkiPubKeyBuildAndPartlyCheck. </li>
70 <li>Full checking of public key - ::CC_EcpkiPubKeyBuildAndFullCheck. </li></ul>
71 
72 \note Full check mode takes long time and should be used only when it is actually needed.
73 
74 @return CC_OK on success.
75 @return A non-zero value on failure as defined cc_ecpki_error.h.
76 */
77 /*
78 The function performs the following operations:
79 - Checks validity of incoming variables and pointers;
80 - Converts incoming key data from big endian into little endian;
81 - If public key is given in compressed form (i.e. byte[0] = 2 or 3 and
82   coordinate Y is omitted), then the function uncompress it;
83 - Performs checking of input key according to CheckMode parameter.
84 - Initializes variables and structures.
85 */
86 CIMPORT_C CCError_t CC_EcpkiPublKeyBuildAndCheck(
87             const CCEcpkiDomain_t       *pDomain,               /*!< [in]  The EC domain (curve). */
88             uint8_t                     *pPubKeyIn,         /*!< [in]  Pointer to the input public key data, in compressed or
89                                            uncompressed or hybrid form:
90                                            [PC||X||Y] Big-Endian representation, structured according to
91                                            [IEEE1363], where:
92                                            <ul><li>X and Y are the public key's EC point coordinates.
93                                            In compressed form, Y is omitted.</li>
94                                            <li> The sizes of X and Y are equal to the size of the EC modulus.</li>
95                                            <li> PC is a one-byte point control that defines the type of point
96                                            compression. </li></ul>*/
97             size_t                      PublKeySizeInBytes,    /*!< [in]  The size of public key data (in bytes). */
98             ECPublKeyCheckMode_t        CheckMode,             /*!< [in]  The required level of public key verification
99                                     (higher verification level means longer verification time):
100                                     <ul><li> 0 = preliminary validation. </li>
101                                     <li> 1 = partial validation. </li>
102                                     <li> 2 = full validation. </li></ul>*/
103             CCEcpkiUserPublKey_t        *pUserPublKey,          /*!< [out] Pointer to the output public key structure.
104                                         This structure is used as input to the ECPKI cryptographic primitives. */
105             CCEcpkiBuildTempData_t      *pTempBuff              /*!< [in]  Pointer for a temporary buffer required for the build function. */
106             );
107 
108 
109 /**********************************************************************************
110  *                 CC_EcpkiPubKeyBuild macro                              *
111  **********************************************************************************/
112 /*!
113 @brief This macro calls CC_EcpkiPublKeyBuildAndCheck function for building the public key
114 while checking input pointers and sizes. For a description of the parameters see ::CC_EcpkiPublKeyBuildAndCheck.
115 */
116 #define  CC_EcpkiPubKeyBuild(pDomain, pPubKeyIn, PublKeySizeInBytes, pUserPublKey) \
117          CC_EcpkiPublKeyBuildAndCheck((pDomain), (pPubKeyIn), (PublKeySizeInBytes), CheckPointersAndSizesOnly, (pUserPublKey), NULL)
118 
119 
120 /**********************************************************************************
121  *                 CC_EcpkiPubKeyBuildAndPartlyCheck macro                         *
122  **********************************************************************************/
123 /*!
124 @brief This macro calls CC_EcpkiPublKeyBuildAndCheck function for building the public key with partial validation of the key [SEC1] - 3.2.3.
125 For a description of the parameters see ::CC_EcpkiPublKeyBuildAndCheck.
126 */
127 #define  CC_EcpkiPubKeyBuildAndPartlyCheck(pDomain, pPubKeyIn, PublKeySizeInBytes, pUserPublKey, pTempBuff) \
128          CC_EcpkiPublKeyBuildAndCheck((pDomain), (pPubKeyIn), (PublKeySizeInBytes), ECpublKeyPartlyCheck, (pUserPublKey), (pTempBuff))
129 
130 
131 /**********************************************************************************
132  *                 CC_EcpkiPubKeyBuildAndFullCheck macro                     *
133  **********************************************************************************/
134 /*!
135 @brief This macro calls CC_EcpkiPublKeyBuildAndCheck function for building the public key with full validation of the key [SEC1] - 3.2.2.
136 For a description of the parameters and return values see CC_EcpkiPublKeyBuildAndCheck.
137 */
138 #define  CC_EcpkiPubKeyBuildAndFullCheck(pDomain, pPubKeyIn, PublKeySizeInBytes, pUserPublKey,  pTempBuff) \
139      CC_EcpkiPublKeyBuildAndCheck((pDomain), (pPubKeyIn), (PublKeySizeInBytes), (ECpublKeyFullCheck), (pUserPublKey),  (pTempBuff))
140 
141 
142 /***********************************************************************************
143  *                     CC_EcpkiPubKeyExport function                           *
144  ***********************************************************************************/
145 /*!
146 @brief Converts an existing public key from internal representation to Big-Endian export representation.
147 The function converts the X,Y coordinates of public key EC point to big endianness,
148 and sets the public key as follows:
149 <ul><li>In case "Uncompressed" point:  PubKey = PC||X||Y, PC = 0x4 - single byte;</li>
150 <li>In case of "Hybrid" key PC = 0x6.</li>
151 <li>In case of "Compressed" key PC = 0x2.</li></ul>
152 \note Size of output X and Y coordinates is equal to ModSizeInBytes.
153 @return CC_OK on success.
154 @return A non-zero value on failure as defined cc_ecpki_error.h.
155 */
156 CIMPORT_C CCError_t CC_EcpkiPubKeyExport(
157                   CCEcpkiUserPublKey_t           *pUserPublKey,        /*!< [in]  Pointer to the input public key structure (in Little-Endian form). */
158                   CCEcpkiPointCompression_t      compression,         /*!< [in]  Compression mode: Compressed, Uncompressed or Hybrid. */
159                   uint8_t                        *pExternPublKey,      /*!< [out] Pointer to the exported public key array, in compressed or uncompressed
160                                                or hybrid form:
161                                             [PC||X||Y] Big-Endian representation, structured according to [IEEE1363].
162                                             In compressed form, Y is omitted. */
163                   size_t                         *pPublKeySizeBytes    /*!< [in/out] Pointer used for the input of the user public key buffer size
164                                                (in bytes), and the output of the size of the converted public key in bytes. */
165                   );
166 
167 
168 
169 #ifdef __cplusplus
170 }
171 #endif
172 /**
173 @}
174  */
175 #endif
176