crys_ec_edw_api.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. /**************************************************************************************
  2. * Copyright (c) 2016-2017, ARM Limited or its affiliates. All rights reserved *
  3. * *
  4. * This file and the related binary are licensed under the following license: *
  5. * *
  6. * ARM Object Code and Header Files License, v1.0 Redistribution. *
  7. * *
  8. * Redistribution and use of object code, header files, and documentation, without *
  9. * modification, are permitted provided that the following conditions are met: *
  10. * *
  11. * 1) Redistributions must reproduce the above copyright notice and the *
  12. * following disclaimer in the documentation and/or other materials *
  13. * provided with the distribution. *
  14. * *
  15. * 2) Unless to the extent explicitly permitted by law, no reverse *
  16. * engineering, decompilation, or disassembly of is permitted. *
  17. * *
  18. * 3) Redistribution and use is permitted solely for the purpose of *
  19. * developing or executing applications that are targeted for use *
  20. * on an ARM-based product. *
  21. * *
  22. * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND *
  23. * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT *
  24. * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, *
  25. * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE *
  26. * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, *
  27. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED *
  28. * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR *
  29. * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF *
  30. * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING *
  31. * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS *
  32. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. *
  33. **************************************************************************************/
  34. #ifndef CRYS_EC_EDW_API_H
  35. #define CRYS_EC_EDW_API_H
  36. #include "ssi_pal_types.h"
  37. #include "crys_hash.h"
  38. #include "crys_rnd.h"
  39. #include "crys_pka_defs_hw.h"
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43. /*!
  44. @defgroup cryptocell_ec CryptoCell EC 25519 curve APIs
  45. @{
  46. @ingroup cryptocell_api
  47. @brief This group is the cryptocell EC 25519 curve root group
  48. @}
  49. @file
  50. @brief This file contains the CRYS APIs used for EC EDW (Edwards) ed25519 algorithms.
  51. @defgroup crys_ec_edw CryptoCell EC Edwards APIs
  52. @{
  53. @ingroup cryptocell_ec
  54. \note Algorithms of Montgomery and Edwards elliptic curves cryptography were developed by
  55. Daniel.J.Bernstein.
  56. */
  57. /*! EC Edwards ed25519 modulus and order sizes in bits, words and bytes. */
  58. /*! EC Edwards modulus size in bits. */
  59. #define CRYS_ECEDW_MOD_SIZE_IN_BITS 255U /*!<\internal MOD - EC Edw modulus size*/
  60. /*! EC Edwards order size in bits. */
  61. #define CRYS_ECEDW_ORD_SIZE_IN_BITS 255U /*!<\internal ORD - EC Edw generator order size*/
  62. /*! EC Edwards nodulus size in words. */
  63. #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)
  64. /*! EC Edwards modulus size in bytes. */
  65. #define CRYS_ECEDW_MOD_SIZE_IN_BYTES (CRYS_ECEDW_MOD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
  66. /*! EC Edwards order size in words. */
  67. #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)
  68. /*! EC Edwards order size in bytes. */
  69. #define CRYS_ECEDW_ORD_SIZE_IN_BYTES (CRYS_ECEDW_ORD_SIZE_IN_32BIT_WORDS * SASI_32BIT_WORD_SIZE)
  70. /*! Constant sizes of special EC_MONT buffers and arrays */
  71. /*! EC Edwards seed size in bytes. */
  72. #define CRYS_ECEDW_SEED_BYTES CRYS_ECEDW_MOD_SIZE_IN_BYTES
  73. /*! EC Edwards secret key size in bytes. */
  74. #define CRYS_ECEDW_SECRET_KEY_BYTES (2 * CRYS_ECEDW_MOD_SIZE_IN_BYTES)
  75. /*! EC Edwards signatue size in bytes. */
  76. #define CRYS_ECEDW_SIGNATURE_BYTES (2 * CRYS_ECEDW_ORD_SIZE_IN_BYTES)
  77. /*! EC Edwards scalar size in bytes. */
  78. #define CRYS_ECEDW_SCALAR_BYTES CRYS_ECEDW_ORD_SIZE_IN_BYTES
  79. /*! EC Edwards scalar multiplication size in bytes. */
  80. #define CRYS_ECEDW_SCALARMULT_BYTES CRYS_ECEDW_MOD_SIZE_IN_BYTES
  81. /*! EC_EDW temp buffer size definition. */
  82. #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)
  83. /*! EC_EDW temp buffer type definition. */
  84. typedef struct {
  85. /*! Internal buffer. */
  86. uint32_t buff[CRYS_ECEDW_TEMP_BUFF_SIZE_IN_32BIT_WORD];
  87. } CRYS_ECEDW_TempBuff_t;
  88. /******************************************************************************/
  89. /*!
  90. @brief The function creates EC Edwards signature on the message.
  91. \note Used detached form of signature, separated from the message.
  92. Implemented algorithm of Bernstein D. etc. sign ed25519.
  93. @return CRYS_OK on success,
  94. @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
  95. */
  96. CIMPORT_C CRYSError_t CRYS_ECEDW_Sign (
  97. uint8_t *pSign, /*!< [out] Pointer to the detached signature. */
  98. size_t *pSignSize, /*!< [in/out] Pointer to the total size of the signature ;
  99. In - the buffer size, which (must be at least 2*EC order size);
  100. Out - the actual size of output data. */
  101. const uint8_t *pMsg, /*!< [in] Pointer to the message. */
  102. size_t msgSize, /*!< [in] Message size in bytes: must be less, than
  103. (CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES - 2*(EC_EDW modulus size)). */
  104. const uint8_t *pSignSecrKey, /*!< [in] Pointer to the signer secret key (seed || pulKey) */
  105. size_t secrKeySize, /*!< [in] Size of signer secret key in bytes: (must be 2*EC order size). */
  106. CRYS_ECEDW_TempBuff_t *pTempBuff /*!< [in] Pointer to the temp buffer. */);
  107. /******************************************************************************/
  108. /*!
  109. @brief The function verifies the EC Edwards ed25519 signature on the message.
  110. \note The input signature is in detached form, i.e. separated from the message.
  111. @return CRYS_OK on success,
  112. @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
  113. */
  114. CIMPORT_C CRYSError_t CRYS_ECEDW_Verify(
  115. const uint8_t *pSign, /*!< [in] Pointer to detached signature, i.e. the
  116. signature is separated from the message. */
  117. size_t signSize, /*!< [in] Size of the signature in bytes, it must be
  118. equal to two EC Order size in bytes. */
  119. const uint8_t *pSignPublKey, /*!< [in] Pointer to signer public key. */
  120. size_t publKeySize, /*!< [in] Size of the signer public key in bytes; must be
  121. equal to EC modulus size. */
  122. uint8_t *pMsg, /*!< [in] Pointer to the message. */
  123. size_t msgSize, /*!< [in] Pointer to the message size in bytes. Must be less than
  124. (CRYS_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES - 2*(EC_EDW modulus size)). */
  125. CRYS_ECEDW_TempBuff_t *pTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */);
  126. /******************************************************************************/
  127. /*!
  128. @brief The function randomly generates Ec ed25519 private and public keys
  129. using given seed.
  130. The generation is performed using EC Edwards ed25519 algorithm.
  131. @return CRYS_OK on success,
  132. @return A non-zero value on failure as defined crys_ec_mont_edw_error.h or crys_hash_error.h.
  133. */
  134. CIMPORT_C CRYSError_t CRYS_ECEDW_SeedKeyPair (
  135. const uint8_t *pSeed, /*!< [in] Pointer to the given seed. */
  136. size_t seedSize, /*!< [in] Size of the seed in bytes, must be equal the EC order size
  137. in bytes. */
  138. uint8_t *pSecrKey, /*!< [out] Pointer to the secret key, including the seed, concatenated
  139. with the public key. */
  140. size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of the secret key buffer in bytes
  141. (must be at least 2*EC order size). */
  142. uint8_t *pPublKey, /*!< [out] Pointer to the public key. */
  143. size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes.
  144. In - the size of buffer must be at least EC modulus size;
  145. Out - the actual size. */
  146. CRYS_ECEDW_TempBuff_t *pTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */);
  147. /*******************************************************************/
  148. /*!
  149. @brief The function randomly generates the EC Edwards ed25519 private and
  150. public keys.
  151. The generation is performed using EC Edwards ed25519 algorithm.
  152. @return CRYS_OK on success,
  153. @return A non-zero value on failure as defined crys_ec_mont_edw_error.h, crys_hash_error.h or crys_rnd_error.
  154. */
  155. CIMPORT_C CRYSError_t CRYS_ECEDW_KeyPair (
  156. uint8_t *pSecrKey, /*!< [out] Pointer to the secret key (including seed and public key). */
  157. size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of the secret key in bytes,
  158. (must be at least 2*EC order size). */
  159. uint8_t *pPublKey, /*!< [out] Pointer to the public key. */
  160. size_t *pPublKeySize, /*!< [in/out] - Pointer to the size of the public key in bytes.
  161. In - the size of buffer must be at least EC modulus size;
  162. Out - the actual size. */
  163. void *pRndState, /*!< [in/out] Pointer to the RND state structure. */
  164. SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, /*!< [in] Pointer to the random vector generation function. */
  165. CRYS_ECEDW_TempBuff_t *pTempBuff /*!< [in] Pointer to the temp buffer. */);
  166. #ifdef __cplusplus
  167. }
  168. #endif
  169. /**
  170. @}
  171. */
  172. #endif