Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
crys_ecpki_build.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_ECPKI_BUILD_H 00037 #define CRYS_ECPKI_BUILD_H 00038 00039 /*! 00040 @defgroup cryptocell_ecpki CryptoCell ECC APIs 00041 @{ 00042 @ingroup cryptocell_api 00043 @brief This group is the cryptocell ECC root group 00044 @} 00045 00046 @file 00047 @brief This module defines functions for building key structures used in Elliptic Curves Cryptography (ECC). 00048 @defgroup crys_ecpki_build CryptoCell key build for ECC APIs 00049 @{ 00050 @ingroup cryptocell_ecpki 00051 */ 00052 00053 00054 #include "crys_error.h" 00055 #include "crys_ecpki_types.h" 00056 00057 #ifdef __cplusplus 00058 extern "C" 00059 { 00060 #endif 00061 00062 /********************************************************************************** 00063 * CRYS_ECPKI_BuildPrivKey function * 00064 **********************************************************************************/ 00065 /*! 00066 @brief Builds (imports) the user private key structure from an existing private key so 00067 that this structure can be used by other EC primitives. 00068 This function should be called before using of the private key. Input 00069 domain structure must be initialized by EC parameters and auxiliary 00070 values, using CRYS_ECPKI_GetDomain or CRYS_ECPKI_SetDomain functions. 00071 00072 @return CRYS_OK on success. 00073 @return A non-zero value on failure as defined crys_ecpki_error.h. 00074 */ 00075 CIMPORT_C CRYSError_t CRYS_ECPKI_BuildPrivKey( 00076 const CRYS_ECPKI_Domain_t *pDomain, /*!< [in] The EC domain (curve). */ 00077 const uint8_t *pPrivKeyIn, /*!< [in] Pointer to private key data. */ 00078 uint32_t PrivKeySizeInBytes, /*!< [in] Size of private key data (in bytes). */ 00079 CRYS_ECPKI_UserPrivKey_t *pUserPrivKey /*!< [out] Pointer to the private key structure. 00080 This structure is used as input to the ECPKI cryptographic primitives. */ 00081 ); 00082 00083 /********************************************************************************** 00084 * _DX_ECPKI_BuildPublKey function * 00085 **********************************************************************************/ 00086 /*! 00087 @brief Builds a user public key structure from an imported public key, 00088 so it can be used by other EC primitives. 00089 When operating the EC cryptographic algorithms with imported EC public 00090 key, this function should be called before using of the public key. 00091 00092 \note The Incoming public key PublKeyIn structure is big endian bytes array, containing 00093 concatenation of PC||X||Y, where: 00094 <ul id="noteb"><li> PC - point control single byte, defining the type of point: 0x4 - uncompressed, 00095 06,07 - hybrid, 2,3 - compressed. </li> 00096 <li>X,Y - EC point coordinates of public key (y is omitted in compressed form), 00097 size of X and Y must be equal to size of EC modulus. </li></ul> 00098 00099 The user may call this function by appropriate macros, according to necessary validation level [SEC1. ECC standard: 3.2, ANS X9.62]: 00100 <ul><li>Checking the input pointers and sizes only - ::CRYS_ECPKI_BuildPublKey.</li> 00101 <li>Partially checking of public key - ::CRYS_ECPKI_BuildPublKeyPartlyCheck. </li> 00102 <li>Full checking of public key - ::CRYS_ECPKI_BuildPublKeyFullCheck. </li></ul> 00103 00104 \note Full check mode takes long time and should be used when it is actually needed. 00105 00106 @return CRYS_OK on success. 00107 @return A non-zero value on failure as defined crys_ecpki_error.h. 00108 */ 00109 /* 00110 The function performs the following operations: 00111 - Checks validity of incoming variables and pointers; 00112 - Converts incoming key data from big endian into little endian; 00113 - If public key is given in compressed form (i.e. byte[0] = 2 or 3 and 00114 coordinate Y is omitted), then the function uncompress it; 00115 - Performs checking of input key according to CheckMode parameter. 00116 - Initializes variables and structures. 00117 */ 00118 CIMPORT_C CRYSError_t _DX_ECPKI_BuildPublKey( 00119 const CRYS_ECPKI_Domain_t *pDomain, /*!< [in] The EC domain (curve). */ 00120 uint8_t *PublKeyIn_ptr, /*!< [in] Pointer to the input public key data, in compressed or 00121 uncompressed or hybrid form: 00122 [PC||X||Y] Big-Endian representation, structured according to 00123 [IEEE1363], where: 00124 <ul><li>X and Y are the public key's EC point coordinates. 00125 In compressed form, Y is omitted.</li> 00126 <li> The sizes of X and Y are equal to the size of the EC modulus.</li> 00127 <li> PC is a one-byte point control that defines the type of point 00128 compression. </li></ul>*/ 00129 uint32_t PublKeySizeInBytes, /*!< [in] The size of public key data (in bytes). */ 00130 EC_PublKeyCheckMode_t CheckMode, /*!< [in] The required level of public key verification 00131 (higher verification level means longer verification time): 00132 <ul><li> 0 = preliminary validation. </li> 00133 <li> 1 = partial validation. </li> 00134 <li> 2 = full validation. </li></ul>*/ 00135 CRYS_ECPKI_UserPublKey_t *pUserPublKey, /*!< [out] Pointer to the output public key structure. 00136 This structure is used as input to the ECPKI cryptographic primitives. */ 00137 CRYS_ECPKI_BUILD_TempData_t *pTempBuff /*!< [in] Pointer for a temporary buffer required for the build function. */ 00138 ); 00139 00140 00141 /********************************************************************************** 00142 * CRYS_ECPKI_BuildPublKey macro * 00143 **********************************************************************************/ 00144 /*! 00145 @brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key 00146 while checking input pointers and sizes. For a description of the parameters see ::_DX_ECPKI_BuildPublKey. 00147 */ 00148 #define CRYS_ECPKI_BuildPublKey(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey) \ 00149 _DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), CheckPointersAndSizesOnly, (pUserPublKey), NULL) 00150 00151 00152 /********************************************************************************** 00153 * CRYS_ECPKI_BuildPublKeyPartlyCheck macro * 00154 **********************************************************************************/ 00155 /*! 00156 @brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key with partial validation of the key [SEC1] - 3.2.3. 00157 For a description of the parameters see ::_DX_ECPKI_BuildPublKey. 00158 */ 00159 #define CRYS_ECPKI_BuildPublKeyPartlyCheck(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey, pTempBuff) \ 00160 _DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), ECpublKeyPartlyCheck, (pUserPublKey), (pTempBuff)) 00161 00162 00163 /********************************************************************************** 00164 * CRYS_ECPKI_BuildPublKeyFullCheck macro * 00165 **********************************************************************************/ 00166 /*! 00167 @brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key with full validation of the key [SEC1] - 3.2.2. 00168 For a description of the parameters and return values see _DX_ECPKI_BuildPublKey. 00169 */ 00170 #define CRYS_ECPKI_BuildPublKeyFullCheck(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey, pTempBuff) \ 00171 _DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), (ECpublKeyFullCheck), (pUserPublKey), (pTempBuff)) 00172 00173 00174 /*********************************************************************************** 00175 * CRYS_ECPKI_ExportPublKey function * 00176 ***********************************************************************************/ 00177 /*! 00178 @brief Converts an existing public key from internal representation to Big-Endian export representation. 00179 The function converts the X,Y coordinates of public key EC point to big endianness, 00180 and sets the public key as follows: 00181 <ul><li>In case "Uncompressed" point: PubKey = PC||X||Y, PC = 0x4 - single byte;</li> 00182 <li>In case of "Hybrid" key PC = 0x6.</li> 00183 <li>In case of "Compressed" key PC = 0x2.</li></ul> 00184 \note Size of output X and Y coordinates is equal to ModSizeInBytes. 00185 @return CRYS_OK on success. 00186 @return A non-zero value on failure as defined crys_ecpki_error.h. 00187 */ 00188 CIMPORT_C CRYSError_t CRYS_ECPKI_ExportPublKey( 00189 CRYS_ECPKI_UserPublKey_t *pUserPublKey, /*!< [in] Pointer to the input public key structure (in Little-Endian form). */ 00190 CRYS_ECPKI_PointCompression_t compression, /*!< [in] Compression mode: Compressed, Uncompressed or Hybrid. */ 00191 uint8_t *pExternPublKey, /*!< [out] Pointer to the exported public key array, in compressed or uncompressed 00192 or hybrid form: 00193 [PC||X||Y] Big-Endian representation, structured according to [IEEE1363]. 00194 In compressed form, Y is omitted. */ 00195 uint32_t *pPublKeySizeBytes /*!< [in/out] Pointer used for the input of the user public key buffer size 00196 (in bytes), and the output of the size of the converted public key in bytes. */ 00197 ); 00198 00199 00200 00201 #ifdef __cplusplus 00202 } 00203 #endif 00204 /** 00205 @} 00206 */ 00207 #endif
Generated on Tue Jul 12 2022 13:54:14 by
