crys_ec_mont_api.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 
00037 #ifndef CRYS_ECMONT_API_H
00038 #define CRYS_ECMONT_API_H
00039 
00040 #include "ssi_pal_types.h"
00041 #include "crys_rnd.h"
00042 #include "crys_pka_defs_hw.h"
00043 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 /*!
00049 @file
00050 @brief This file contains the CRYS APIs used for EC MONT (Montgomery Curve25519) algorithms.
00051 @defgroup crys_ec_mont CryptoCell EC Montgomery APIs
00052 @{
00053 @ingroup cryptocell_ec
00054 
00055 
00056 \note  Implemented algorithms according to Montgomery elliptic curves cryptography,
00057        developed by Daniel J.Bernstein etc.
00058 */
00059 
00060 /*! EC Montgomery curve25519 modulus size in bits, words and bytes  */
00061 /*! EC Montgomery modulus size in bits. */
00062 #define CRYS_ECMONT_MOD_SIZE_IN_BITS  255U
00063 /*! EC Montgomery modulus size in words. */
00064 #define CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS    ((CRYS_ECMONT_MOD_SIZE_IN_BITS + SASI_BITS_IN_32BIT_WORD - 1) / SASI_BITS_IN_32BIT_WORD)
00065 /*! EC Montgomery modulus size in bytes. */
00066 #define CRYS_ECMONT_MOD_SIZE_IN_BYTES          ((CRYS_ECMONT_MOD_SIZE_IN_BITS + SASI_BITS_IN_32BIT_WORD - 1) / sizeof(uint32_t))
00067 
00068 /*! Constant sizes of special EC_MONT buffers and arrays  */
00069 /*! EC Montgomery scalar size in bytes. */
00070 #define CRYS_ECMONT_SCALARBYTES     (CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
00071 /*! EC Montgomery scalar multiplication size in bytes. */
00072 #define CRYS_ECMONT_SCALARMULTBYTES (CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
00073 /*! EC Montgomery scalar seed size in bytes. */
00074 #define CRYS_ECMONT_SEEDBYTES       (CRYS_ECMONT_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
00075 
00076 /*! EC Montgomery domains ID-s enumerator. */
00077 typedef enum {
00078         CRYS_ECMONT_DOMAIN_CURVE_25519 ,  /*!< EC Curve25519. */
00079     /*! EC Montgomery last domain. */
00080         CRYS_ECMONT_DOMAIN_OFF_MODE ,
00081     /*! Reserved. */
00082         CRYS_ECMONT_DOMAIN_LAST  = 0x7FFFFFFF
00083 }CRYS_ECMONT_DomainId_t ;
00084 
00085 
00086 /*! EC_MONT scalar mult temp buffer type definition */
00087 typedef struct {
00088     /*! Internal temporary buffer. */
00089         uint32_t ecMontScalarMultTempBuff[CRYS_EC_MONT_TEMP_BUFF_SIZE_IN_32BIT_WORDS]; // set needed
00090 } CRYS_ECMONT_ScalrMultTempBuff_t ;
00091 
00092 /*! EC_MONT temp buffer type definition */
00093 typedef struct {
00094         /* Don't change sequence order of the buffers */
00095     /*! Internal temporary buffer. */
00096         uint32_t ecMontScalar[CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS];
00097     /*! Internal temporary buffer. */
00098         uint32_t ecMontResPoint[CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS];
00099     /*! Internal temporary buffer. */
00100         uint32_t ecMontInPoint[CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS];
00101     /*! Internal temporary buffer. */
00102         CRYS_ECMONT_ScalrMultTempBuff_t   ecMontScalrMultTempBuff ; // if needed
00103 } CRYS_ECMONT_TempBuff_t ;
00104 
00105 
00106 /*********************************************************************/
00107 /*!
00108 @brief The function performs EC Montgomery (Curve25519) scalar multiplication:
00109        resPoint = scalar * point.
00110 
00111 @return CRYS_OK on success,
00112 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h.
00113 */
00114 CIMPORT_C CRYSError_t  CRYS_ECMONT_Scalarmult(
00115                                             uint8_t       *pResPoint,       /*!< [out] Pointer to the public (secret) key. */
00116                                             size_t        *pResPointSize,   /*!< [in/out] Pointer to the size of the public key in bytes.
00117                                                                                    In  - the size of the buffer. must be at least EC modulus
00118                                                                                          size (for curve25519 - 32 bytes).
00119                                                                                    Out - the actual size. */
00120                                             const uint8_t *pScalar,         /*!< [in] Pointer to the secret (private) key. */
00121                                             size_t         scalarSize,      /*!< [in] Pointer to the size of the secret key in bytes;
00122                                                                                  must be equal to EC order size (for curve25519 - 32 bytes). */
00123                                             const uint8_t *pInPoint,        /*!< [in] Pointer to the input point (compressed). */
00124                                             size_t         inPointSize,     /*!< [in] Size of the point - must be equal to CRYS_ECMONT_MOD_SIZE_IN_BYTES. */
00125                                             CRYS_ECMONT_TempBuff_t  *pEcMontTempBuff  /*!< [in] Pointer to temp buffer, for internal use. */);
00126 
00127 
00128 /*********************************************************************/
00129 /*!
00130 @brief The function performs EC Montgomery (Curve25519) scalar multiplication of base point:
00131        res = scalar * base_point.
00132 
00133        Note: all byte arrays have LE order of bytes, i.e. LS byte is on left most place.
00134 
00135 @return CRYS_OK on success,
00136 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h.
00137 */
00138 CIMPORT_C CRYSError_t  CRYS_ECMONT_ScalarmultBase(
00139                                                 uint8_t       *pResPoint,      /*!< [out] Pointer to the public (secret) key. */
00140                                                 size_t        *pResPointSize,  /*!< [in/out] Pointer to the size of the public key in bytes.
00141                                                                                       In  - the size of buffer must be at least EC modulus size
00142                                                                                       (for curve25519 - 32 bytes);
00143                                                                                       Out - the actual size. */
00144                                                 const uint8_t *pScalar,        /*!< [in] Pointer to the secret (private) key. */
00145                                                 size_t         scalarSize,     /*!< [in] Pointer to the size of the scalar in bytes -
00146                                                                                     must be equal to EC order size (for curve25519 - 32 bytes). */
00147                                                 CRYS_ECMONT_TempBuff_t  *pEcMontTempBuff /*!< [in] Pointer to temp buffer, for internal use. */);
00148 
00149 
00150 /*******************************************************************/
00151 /*!
00152 @brief The function randomly generates  private and public keys for Montgomery
00153        Curve25519.
00154 
00155 
00156 \note <ul id="noteb"><li> All byte arrays are in LE order of bytes, i.e. LS byte is on the left most place.</li>
00157       <li> LS and MS bits of the Secret key are set according to EC Montgomery scalar mult. algorithm:
00158                 secrKey[0] &= 248; secrKey[31] &= 127; secrKey[31] |= 64;</li></ul>
00159 
00160 @return CRYS_OK on success,
00161 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_rnd_error.h.
00162 
00163 */
00164 CIMPORT_C CRYSError_t  CRYS_ECMONT_KeyPair (
00165                                           uint8_t *pPublKey,                    /*!< [out] Pointer to the public key. */
00166                                           size_t  *pPublKeySize,                /*!< [in/out] Pointer to the size of the public key in bytes.
00167                                                                                       In  - the size of the buffer must be at least EC order size
00168                                                                                             (for curve25519 - 32 bytes);
00169                                                                                       Out - the actual size. */
00170                                           uint8_t *pSecrKey,                    /*!< [out] Pointer to the secret key, including. */
00171                                           size_t  *pSecrKeySize,                /*!< [in/out] Pointer to the size of buffer for the secret key in bytes -
00172                                                                                      must be at least EC order size (for curve25519 - 32 bytes). */
00173                                          void   *pRndState,     /*!< [in/out] Pointer to the RND state structure. */
00174                      SaSiRndGenerateVectWorkFunc_t  rndGenerateVectFunc,   /*!< [in] Pointer to the random vector generation function. */
00175                                           CRYS_ECMONT_TempBuff_t  *pEcMontTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */);
00176 
00177 
00178 /*******************************************************************/
00179 /*!
00180 @brief The function generates private and public keys for Montgomery algorithms.
00181 
00182        The generation performed using given seed.
00183 
00184 
00185 @return CRYS_OK on success,
00186 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
00187 */
00188 CIMPORT_C CRYSError_t  CRYS_ECMONT_SeedKeyPair (
00189                                               uint8_t       *pPublKey,       /*!< [out] Pointer to the public (secret) key. */
00190                                               size_t        *pPublKeySize,   /*!< [in/out] Pointer to the size of the public key in bytes.
00191                                                                                      In  - the size of buffer must be at least EC order size
00192                                                                                            (for curve25519 - 32 bytes);
00193                                                                                      Out - the actual size. */
00194                                               uint8_t       *pSecrKey,       /*!< [out] Pointer to the secret (private) key. */
00195                                               size_t        *pSecrKeySize,   /*!< [in/out] Pointer to the size of the secret key in bytes
00196                                                                                       In  - the size of buffer must be at least EC order size
00197                                                                                             (for curve25519 - 32 bytes);
00198                                                                                       Out - the actual size. */
00199                                               const uint8_t *pSeed,          /*!< [in] Pointer to the given seed - 32 bytes. */
00200                                               size_t         seedSize,       /*!< [in/] Size of the seed in bytes (must be equal to CRYS_ECMONT_SEEDBYTES). */
00201                                               CRYS_ECMONT_TempBuff_t  *pEcMontTempBuff /*!< [in] Pointer to a temp buffer, for internal use. */);
00202 
00203 
00204 #ifdef __cplusplus
00205 }
00206 #endif
00207 /**
00208 @}
00209  */
00210 #endif
00211 
00212 
00213