mirror of https://github.com/ARMmbed/mbed-os.git
208 lines
12 KiB
C
208 lines
12 KiB
C
|
/**************************************************************************************
|
||
|
|
* Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
|
||
|
|
* *
|
||
|
|
* This file and the related binary are licensed under the following license: *
|
||
|
|
* *
|
||
|
|
* ARM Object Code and Header Files License, v1.0 Redistribution. *
|
||
|
|
* *
|
||
|
|
* Redistribution and use of object code, header files, and documentation, without *
|
||
|
|
* modification, are permitted provided that the following conditions are met: *
|
||
|
|
* *
|
||
|
|
* 1) Redistributions must reproduce the above copyright notice and the *
|
||
|
|
* following disclaimer in the documentation and/or other materials *
|
||
|
|
* provided with the distribution. *
|
||
|
|
* *
|
||
|
|
* 2) Unless to the extent explicitly permitted by law, no reverse *
|
||
|
|
* engineering, decompilation, or disassembly of is permitted. *
|
||
|
|
* *
|
||
|
|
* 3) Redistribution and use is permitted solely for the purpose of *
|
||
|
|
* developing or executing applications that are targeted for use *
|
||
|
|
* on an ARM-based product. *
|
||
|
|
* *
|
||
|
|
* DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
|
||
|
|
* CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
|
||
|
|
* NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
|
||
|
|
* AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
|
||
|
|
* COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
|
||
|
|
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
|
||
|
|
* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
|
||
|
|
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
|
||
|
|
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
|
||
|
|
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
|
||
|
|
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
|
||
|
|
**************************************************************************************/
|
||
|
|
|
||
|
|
|
||
|
|
#ifndef CRYS_ECPKI_BUILD_H
|
||
|
|
#define CRYS_ECPKI_BUILD_H
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@defgroup cryptocell_ecpki CryptoCell ECC APIs
|
||
|
|
@{
|
||
|
|
@ingroup cryptocell_api
|
||
|
|
@brief This group is the cryptocell ECC root group
|
||
|
|
@}
|
||
|
|
|
||
|
|
@file
|
||
|
|
@brief This module defines functions for building key structures used in Elliptic Curves Cryptography (ECC).
|
||
|
|
@defgroup crys_ecpki_build CryptoCell key build for ECC APIs
|
||
|
|
@{
|
||
|
|
@ingroup cryptocell_ecpki
|
||
|
|
*/
|
||
|
|
|
||
|
|
|
||
|
|
#include "crys_error.h"
|
||
|
|
#include "crys_ecpki_types.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C"
|
||
|
|
{
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**********************************************************************************
|
||
|
|
* CRYS_ECPKI_BuildPrivKey function *
|
||
|
|
**********************************************************************************/
|
||
|
|
/*!
|
||
|
|
@brief Builds (imports) the user private key structure from an existing private key so
|
||
|
|
that this structure can be used by other EC primitives.
|
||
|
|
This function should be called before using of the private key. Input
|
||
|
|
domain structure must be initialized by EC parameters and auxiliary
|
||
|
|
values, using CRYS_ECPKI_GetDomain or CRYS_ECPKI_SetDomain functions.
|
||
|
|
|
||
|
|
@return CRYS_OK on success.
|
||
|
|
@return A non-zero value on failure as defined crys_ecpki_error.h.
|
||
|
|
*/
|
||
|
|
CIMPORT_C CRYSError_t CRYS_ECPKI_BuildPrivKey(
|
||
|
|
const CRYS_ECPKI_Domain_t *pDomain, /*!< [in] The EC domain (curve). */
|
||
|
|
const uint8_t *pPrivKeyIn, /*!< [in] Pointer to private key data. */
|
||
|
|
uint32_t PrivKeySizeInBytes, /*!< [in] Size of private key data (in bytes). */
|
||
|
|
CRYS_ECPKI_UserPrivKey_t *pUserPrivKey /*!< [out] Pointer to the private key structure.
|
||
|
|
This structure is used as input to the ECPKI cryptographic primitives. */
|
||
|
|
);
|
||
|
|
|
||
|
|
/**********************************************************************************
|
||
|
|
* _DX_ECPKI_BuildPublKey function *
|
||
|
|
**********************************************************************************/
|
||
|
|
/*!
|
||
|
|
@brief Builds a user public key structure from an imported public key,
|
||
|
|
so it can be used by other EC primitives.
|
||
|
|
When operating the EC cryptographic algorithms with imported EC public
|
||
|
|
key, this function should be called before using of the public key.
|
||
|
|
|
||
|
|
\note The Incoming public key PublKeyIn structure is big endian bytes array, containing
|
||
|
|
concatenation of PC||X||Y, where:
|
||
|
|
<ul id="noteb"><li> PC - point control single byte, defining the type of point: 0x4 - uncompressed,
|
||
|
|
06,07 - hybrid, 2,3 - compressed. </li>
|
||
|
|
<li>X,Y - EC point coordinates of public key (y is omitted in compressed form),
|
||
|
|
size of X and Y must be equal to size of EC modulus. </li></ul>
|
||
|
|
|
||
|
|
The user may call this function by appropriate macros, according to necessary validation level [SEC1. ECC standard: 3.2, ANS X9.62]:
|
||
|
|
<ul><li>Checking the input pointers and sizes only - ::CRYS_ECPKI_BuildPublKey.</li>
|
||
|
|
<li>Partially checking of public key - ::CRYS_ECPKI_BuildPublKeyPartlyCheck. </li>
|
||
|
|
<li>Full checking of public key - ::CRYS_ECPKI_BuildPublKeyFullCheck. </li></ul>
|
||
|
|
|
||
|
|
\note Full check mode takes long time and should be used when it is actually needed.
|
||
|
|
|
||
|
|
@return CRYS_OK on success.
|
||
|
|
@return A non-zero value on failure as defined crys_ecpki_error.h.
|
||
|
|
*/
|
||
|
|
/*
|
||
|
|
The function performs the following operations:
|
||
|
|
- Checks validity of incoming variables and pointers;
|
||
|
|
- Converts incoming key data from big endian into little endian;
|
||
|
|
- If public key is given in compressed form (i.e. byte[0] = 2 or 3 and
|
||
|
|
coordinate Y is omitted), then the function uncompress it;
|
||
|
|
- Performs checking of input key according to CheckMode parameter.
|
||
|
|
- Initializes variables and structures.
|
||
|
|
*/
|
||
|
|
CIMPORT_C CRYSError_t _DX_ECPKI_BuildPublKey(
|
||
|
|
const CRYS_ECPKI_Domain_t *pDomain, /*!< [in] The EC domain (curve). */
|
||
|
|
uint8_t *PublKeyIn_ptr, /*!< [in] Pointer to the input public key data, in compressed or
|
||
|
|
uncompressed or hybrid form:
|
||
|
|
[PC||X||Y] Big-Endian representation, structured according to
|
||
|
|
[IEEE1363], where:
|
||
|
|
<ul><li>X and Y are the public key's EC point coordinates.
|
||
|
|
In compressed form, Y is omitted.</li>
|
||
|
|
<li> The sizes of X and Y are equal to the size of the EC modulus.</li>
|
||
|
|
<li> PC is a one-byte point control that defines the type of point
|
||
|
|
compression. </li></ul>*/
|
||
|
|
uint32_t PublKeySizeInBytes, /*!< [in] The size of public key data (in bytes). */
|
||
|
|
EC_PublKeyCheckMode_t CheckMode, /*!< [in] The required level of public key verification
|
||
|
|
(higher verification level means longer verification time):
|
||
|
|
<ul><li> 0 = preliminary validation. </li>
|
||
|
|
<li> 1 = partial validation. </li>
|
||
|
|
<li> 2 = full validation. </li></ul>*/
|
||
|
|
CRYS_ECPKI_UserPublKey_t *pUserPublKey, /*!< [out] Pointer to the output public key structure.
|
||
|
|
This structure is used as input to the ECPKI cryptographic primitives. */
|
||
|
|
CRYS_ECPKI_BUILD_TempData_t *pTempBuff /*!< [in] Pointer for a temporary buffer required for the build function. */
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
/**********************************************************************************
|
||
|
|
* CRYS_ECPKI_BuildPublKey macro *
|
||
|
|
**********************************************************************************/
|
||
|
|
/*!
|
||
|
|
@brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key
|
||
|
|
while checking input pointers and sizes. For a description of the parameters see ::_DX_ECPKI_BuildPublKey.
|
||
|
|
*/
|
||
|
|
#define CRYS_ECPKI_BuildPublKey(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey) \
|
||
|
|
_DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), CheckPointersAndSizesOnly, (pUserPublKey), NULL)
|
||
|
|
|
||
|
|
|
||
|
|
/**********************************************************************************
|
||
|
|
* CRYS_ECPKI_BuildPublKeyPartlyCheck macro *
|
||
|
|
**********************************************************************************/
|
||
|
|
/*!
|
||
|
|
@brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key with partial validation of the key [SEC1] - 3.2.3.
|
||
|
|
For a description of the parameters see ::_DX_ECPKI_BuildPublKey.
|
||
|
|
*/
|
||
|
|
#define CRYS_ECPKI_BuildPublKeyPartlyCheck(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey, pTempBuff) \
|
||
|
|
_DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), ECpublKeyPartlyCheck, (pUserPublKey), (pTempBuff))
|
||
|
|
|
||
|
|
|
||
|
|
/**********************************************************************************
|
||
|
|
* CRYS_ECPKI_BuildPublKeyFullCheck macro *
|
||
|
|
**********************************************************************************/
|
||
|
|
/*!
|
||
|
|
@brief This macro calls _DX_ECPKI_BuildPublKey function for building the public key with full validation of the key [SEC1] - 3.2.2.
|
||
|
|
For a description of the parameters and return values see _DX_ECPKI_BuildPublKey.
|
||
|
|
*/
|
||
|
|
#define CRYS_ECPKI_BuildPublKeyFullCheck(pDomain, PublKeyIn_ptr, PublKeySizeInBytes, pUserPublKey, pTempBuff) \
|
||
|
|
_DX_ECPKI_BuildPublKey((pDomain), (PublKeyIn_ptr), (PublKeySizeInBytes), (ECpublKeyFullCheck), (pUserPublKey), (pTempBuff))
|
||
|
|
|
||
|
|
|
||
|
|
/***********************************************************************************
|
||
|
|
* CRYS_ECPKI_ExportPublKey function *
|
||
|
|
***********************************************************************************/
|
||
|
|
/*!
|
||
|
|
@brief Converts an existing public key from internal representation to Big-Endian export representation.
|
||
|
|
The function converts the X,Y coordinates of public key EC point to big endianness,
|
||
|
|
and sets the public key as follows:
|
||
|
|
<ul><li>In case "Uncompressed" point: PubKey = PC||X||Y, PC = 0x4 - single byte;</li>
|
||
|
|
<li>In case of "Hybrid" key PC = 0x6.</li>
|
||
|
|
<li>In case of "Compressed" key PC = 0x2.</li></ul>
|
||
|
|
\note Size of output X and Y coordinates is equal to ModSizeInBytes.
|
||
|
|
@return CRYS_OK on success.
|
||
|
|
@return A non-zero value on failure as defined crys_ecpki_error.h.
|
||
|
|
*/
|
||
|
|
CIMPORT_C CRYSError_t CRYS_ECPKI_ExportPublKey(
|
||
|
|
CRYS_ECPKI_UserPublKey_t *pUserPublKey, /*!< [in] Pointer to the input public key structure (in Little-Endian form). */
|
||
|
|
CRYS_ECPKI_PointCompression_t compression, /*!< [in] Compression mode: Compressed, Uncompressed or Hybrid. */
|
||
|
|
uint8_t *pExternPublKey, /*!< [out] Pointer to the exported public key array, in compressed or uncompressed
|
||
|
|
or hybrid form:
|
||
|
|
[PC||X||Y] Big-Endian representation, structured according to [IEEE1363].
|
||
|
|
In compressed form, Y is omitted. */
|
||
|
|
uint32_t *pPublKeySizeBytes /*!< [in/out] Pointer used for the input of the user public key buffer size
|
||
|
|
(in bytes), and the output of the size of the converted public key in bytes. */
|
||
|
|
);
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
/**
|
||
|
|
@}
|
||
|
|
*/
|
||
|
|
#endif
|