crys_ec_edw_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_EC_EDW_API_H
00038 #define CRYS_EC_EDW_API_H
00039 
00040 #include "ssi_pal_types.h"
00041 #include "crys_hash.h"
00042 #include "crys_rnd.h"
00043 #include "crys_pka_defs_hw.h"
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 /*!
00050 @defgroup cryptocell_ec CryptoCell EC 25519 curve APIs
00051 @{
00052 @ingroup cryptocell_api
00053 @brief This group is the cryptocell EC 25519 curve root group
00054 @}
00055 
00056 @file
00057 @brief This file contains the CRYS APIs used for EC EDW (Edwards) ed25519 algorithms.
00058 @defgroup crys_ec_edw CryptoCell EC Edwards APIs
00059 @{
00060 @ingroup cryptocell_ec
00061 
00062 \note  Algorithms of Montgomery and Edwards elliptic curves cryptography were developed by
00063        Daniel.J.Bernstein.
00064 */
00065 
00066 /*! EC Edwards ed25519 modulus and order sizes in bits, words and bytes.  */
00067 /*! EC Edwards modulus size in bits. */
00068 #define CRYS_ECEDW_MOD_SIZE_IN_BITS  255U   /*!<\internal MOD - EC Edw modulus size*/
00069 /*! EC Edwards order size in bits. */
00070 #define CRYS_ECEDW_ORD_SIZE_IN_BITS  255U   /*!<\internal ORD - EC Edw generator order size*/
00071 /*! EC Edwards nodulus size in words. */
00072 #define CRYS_ECEDW_MOD_SIZE_IN_32BIT_WORDS  ((CRYS_ECEDW_MOD_SIZE_IN_BITS + SASI_BITS_IN_32BIT_WORD - 1) / SASI_BITS_IN_32BIT_WORD)
00073 /*! EC Edwards modulus size in bytes. */
00074 #define CRYS_ECEDW_MOD_SIZE_IN_BYTES  (CRYS_ECEDW_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
00075 /*! EC Edwards order size in words. */
00076 #define CRYS_ECEDW_ORD_SIZE_IN_32BIT_WORDS      ((CRYS_ECEDW_ORD_SIZE_IN_BITS + SASI_BITS_IN_32BIT_WORD - 1) / SASI_BITS_IN_32BIT_WORD)
00077 /*! EC Edwards order size in bytes. */
00078 #define CRYS_ECEDW_ORD_SIZE_IN_BYTES  (CRYS_ECEDW_ORD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
00079 
00080 /*! Constant sizes of special EC_MONT buffers and arrays  */
00081 /*! EC Edwards seed size in bytes. */
00082 #define CRYS_ECEDW_SEED_BYTES       CRYS_ECEDW_MOD_SIZE_IN_BYTES
00083 /*! EC Edwards secret key size in bytes. */
00084 #define CRYS_ECEDW_SECRET_KEY_BYTES (2 * CRYS_ECEDW_MOD_SIZE_IN_BYTES)
00085 /*! EC Edwards signatue size in bytes. */
00086 #define CRYS_ECEDW_SIGNATURE_BYTES  (2 * CRYS_ECEDW_ORD_SIZE_IN_BYTES)
00087 /*! EC Edwards scalar size in bytes. */
00088 #define CRYS_ECEDW_SCALAR_BYTES     CRYS_ECEDW_ORD_SIZE_IN_BYTES
00089 /*! EC Edwards scalar multiplication size in bytes. */
00090 #define CRYS_ECEDW_SCALARMULT_BYTES CRYS_ECEDW_MOD_SIZE_IN_BYTES
00091 
00092 /*! EC_EDW temp buffer size definition. */
00093 #define CRYS_ECEDW_TEMP_BUFF_SIZE_IN_32BIT_WORD  (10*CRYS_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS + (sizeof(CRYS_HASHUserContext_t)+SASI_32BIT_WORD_SIZE-1)/SASI_32BIT_WORD_SIZE)
00094 
00095 /*! EC_EDW temp buffer type definition. */
00096 typedef struct {
00097     /*! Internal buffer. */
00098     uint32_t buff[CRYS_ECEDW_TEMP_BUFF_SIZE_IN_32BIT_WORD];
00099 } CRYS_ECEDW_TempBuff_t ;
00100 
00101 
00102 /******************************************************************************/
00103 /*!
00104 @brief The function creates EC Edwards signature on the message.
00105 \note Used detached form of signature, separated from the message.
00106       Implemented algorithm of Bernstein D. etc. sign ed25519.
00107 
00108 @return CRYS_OK on success,
00109 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
00110 */
00111 CIMPORT_C CRYSError_t  CRYS_ECEDW_Sign (
00112                       uint8_t       *pSign,                /*!< [out] Pointer to the detached signature. */
00113                       size_t        *pSignSize,            /*!< [in/out] Pointer to the total size of the signature ;
00114                                             In  - the buffer size, which (must be at least 2*EC order size);
00115                                             Out - the actual size of output data. */
00116                       const uint8_t *pMsg,                 /*!< [in] Pointer to the message. */
00117                       size_t         msgSize,              /*!< [in] Message size in bytes: must be less, than
00118                                             (CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES - 2*(EC_EDW modulus size)). */
00119                       const uint8_t *pSignSecrKey,         /*!< [in] Pointer to the signer secret key (seed || pulKey) */
00120                       size_t         secrKeySize,          /*!< [in] Size of signer secret key in bytes: (must be 2*EC order size). */
00121                       CRYS_ECEDW_TempBuff_t  *pTempBuff     /*!< [in] Pointer to the temp buffer. */);
00122 
00123 
00124 
00125 /******************************************************************************/
00126 /*!
00127 @brief The function verifies the EC Edwards ed25519 signature on the message.
00128 \note The input signature is in detached form, i.e. separated from the message.
00129 
00130 @return CRYS_OK on success,
00131 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
00132 */
00133 CIMPORT_C CRYSError_t  CRYS_ECEDW_Verify(
00134                        const uint8_t *pSign,                /*!< [in] Pointer to detached signature, i.e. the
00135                                          signature is separated from the message. */
00136                        size_t         signSize,             /*!< [in] Size of the signature in bytes, it must be
00137                                          equal to two EC Order size in bytes. */
00138                        const uint8_t *pSignPublKey,         /*!< [in] Pointer to signer public key. */
00139                        size_t         publKeySize,          /*!< [in] Size of the signer public key in bytes; must be
00140                                          equal to EC modulus size. */
00141                        uint8_t       *pMsg,                 /*!< [in] Pointer to the message. */
00142                        size_t         msgSize,              /*!< [in] Pointer to the message size in bytes. Must be less than
00143                                          (CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES - 2*(EC_EDW modulus size)). */
00144                        CRYS_ECEDW_TempBuff_t  *pTempBuff     /*!< [in] Pointer to the temp buffer, for internal use. */);
00145 
00146 
00147 /******************************************************************************/
00148 /*!
00149 @brief The function randomly generates Ec ed25519 private and public keys
00150        using given seed.
00151        The generation is performed using EC Edwards ed25519 algorithm.
00152 
00153 @return CRYS_OK on success,
00154 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
00155 */
00156 CIMPORT_C CRYSError_t  CRYS_ECEDW_SeedKeyPair (
00157                          const uint8_t *pSeed,                  /*!< [in] Pointer to the given seed. */
00158                          size_t         seedSize,               /*!< [in] Size of the seed in bytes, must be equal the EC order size
00159                                              in bytes. */
00160                          uint8_t       *pSecrKey,               /*!< [out] Pointer to the secret key, including the seed, concatenated
00161                                              with the public key. */
00162                          size_t        *pSecrKeySize,           /*!< [in/out] Pointer to the size of the secret key buffer in bytes
00163                                              (must be at least 2*EC order size). */
00164                          uint8_t       *pPublKey,               /*!< [out] Pointer to the public key. */
00165                          size_t        *pPublKeySize,           /*!< [in/out] Pointer to the size of the public key in bytes.
00166                                                 In  - the size of buffer must be at least EC modulus size;
00167                                                 Out - the actual size. */
00168                          CRYS_ECEDW_TempBuff_t  *pTempBuff       /*!< [in] Pointer to the temp buffer, for internal use. */);
00169 
00170 /*******************************************************************/
00171 /*!
00172  @brief The function randomly generates the EC Edwards ed25519 private and
00173     public keys.
00174     The generation is performed using EC Edwards ed25519 algorithm.
00175 
00176 @return CRYS_OK on success,
00177 @return A non-zero value on failure as defined crys_ec_mont_edw_error.h, crys_hash_error.h or crys_rnd_error.
00178 */
00179 CIMPORT_C CRYSError_t  CRYS_ECEDW_KeyPair (
00180                      uint8_t       *pSecrKey,               /*!< [out] Pointer to the secret key (including seed and public key). */
00181                      size_t        *pSecrKeySize,           /*!< [in/out] Pointer to the size of the secret key in bytes,
00182                                               (must be at least 2*EC order size). */
00183                      uint8_t       *pPublKey,               /*!< [out] Pointer to the public key. */
00184                      size_t        *pPublKeySize,           /*!< [in/out] - Pointer to the size of the public key in bytes.
00185                                             In  - the size of buffer must be at least EC modulus size;
00186                                             Out - the actual size. */
00187                      void   *pRndState,      /*!< [in/out] Pointer to the RND state structure. */
00188                      SaSiRndGenerateVectWorkFunc_t  rndGenerateVectFunc,   /*!< [in] Pointer to the random vector generation function. */
00189                      CRYS_ECEDW_TempBuff_t  *pTempBuff   /*!< [in] Pointer to the temp buffer. */);
00190 
00191 
00192 #ifdef __cplusplus
00193 }
00194 #endif
00195 /**
00196 @}
00197  */
00198 #endif
00199 
00200 
00201