1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _CC_EC_EDW_API_H 8 #define _CC_EC_EDW_API_H 9 10 #include "cc_pal_types.h" 11 #include "cc_hash_defs.h" 12 #include "cc_rnd_common.h" 13 #include "cc_pka_defs_hw.h" 14 #include "cc_bitops.h" 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 /*! 21 @file 22 @brief This file contains the CryptoCell APIs used for EC EDW (Edwards) ed25519 algorithms. 23 @defgroup cryptocell_ec CryptoCell EC 25519 curve APIs 24 @{ 25 @ingroup cryptocell_api 26 27 28 @note Algorithms of Montgomery and Edwards elliptic curves cryptography were developed by 29 Daniel.J.Bernstein. 30 */ 31 32 /*! EC Edwards ed25519 modulus and order sizes in bits, words and bytes. */ 33 /*! EC Edwards modulus size in bits. */ 34 #define CC_EC_EDW_MOD_SIZE_IN_BITS 255U /*!<\internal MOD - EC Edw modulus size*/ 35 /*! EC Edwards order size in bits. */ 36 #define CC_EC_EDW_ORD_SIZE_IN_BITS 255U /*!<\internal ORD - EC Edw generator order size*/ 37 /*! EC Edwards modulus size in words. */ 38 #define CC_EC_EDW_MOD_SIZE_IN_32BIT_WORDS ((CC_EC_EDW_MOD_SIZE_IN_BITS + CC_BITS_IN_32BIT_WORD - 1) / CC_BITS_IN_32BIT_WORD) 39 /*! EC Edwards modulus size in bytes. */ 40 #define CC_EC_EDW_MOD_SIZE_IN_BYTES (CC_EC_EDW_MOD_SIZE_IN_32BIT_WORDS * CC_32BIT_WORD_SIZE) 41 /*! EC Edwards order size in words. */ 42 #define CC_EC_EDW_ORD_SIZE_IN_32BIT_WORDS ((CC_EC_EDW_MOD_SIZE_IN_BITS + CC_BITS_IN_32BIT_WORD - 1) / CC_BITS_IN_32BIT_WORD) 43 /*! EC Edwards order size in bytes. */ 44 #define CC_EC_EDW_ORD_SIZE_IN_BYTES (CC_EC_EDW_ORD_SIZE_IN_32BIT_WORDS * CC_32BIT_WORD_SIZE) 45 46 /*! Constant sizes of special EC_MONT buffers and arrays */ 47 /*! EC Edwards seed size in bytes. */ 48 #define CC_EC_EDW_SEED_BYTES CC_EC_EDW_MOD_SIZE_IN_BYTES 49 /*! EC Edwards secret key size in bytes. */ 50 #define CC_EC_EDW_SECRET_KEY_BYTES (2 * CC_EC_EDW_MOD_SIZE_IN_BYTES) 51 /*! EC Edwards signatue size in bytes. */ 52 #define CC_EC_EDW_SIGNATURE_BYTES (2 * CC_EC_EDW_ORD_SIZE_IN_BYTES) 53 /*! EC Edwards scalar size in bytes. */ 54 #define CC_EC_EDW_SCALARBYTES CC_EC_EDW_ORD_SIZE_IN_BYTES 55 /*! EC Edwards scalar multiplication size in bytes. */ 56 #define CC_EC_EDW_SCALARMULTBYTES CC_EC_EDW_MOD_SIZE_IN_BYTES 57 58 /*! EC_EDW temp buffer size definition. */ 59 #define CC_EC_EDW_TEMP_BUFF_SIZE_IN_32BIT_WORD (10*CC_EC_MONT_EDW_MODULUS_MAX_SIZE_IN_WORDS + (sizeof(CCHashUserContext_t)+CC_32BIT_WORD_SIZE-1)/CC_32BIT_WORD_SIZE) 60 61 /*! EC_EDW temp buffer type definition. */ 62 typedef struct { 63 /*! Internal buffer. */ 64 uint32_t buff[CC_EC_EDW_TEMP_BUFF_SIZE_IN_32BIT_WORD]; 65 } CCEcEdwTempBuff_t; 66 67 68 69 /******************************************************************************/ 70 /*! 71 @brief The function creates EC Edwards signature on the message. 72 \note Used detached form of signature, separated from the message. 73 Implemented algorithm of Bernstein D. etc. sign ed25519. 74 75 @return CC_OK on success, 76 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h or cc_hash_error.h. 77 */ 78 CIMPORT_C CCError_t CC_EcEdwSign ( 79 uint8_t *pSign, /*!< [out] Pointer to the detached signature. */ 80 size_t *pSignSize, /*!< [in/out] Pointer to the total size of the signature ; 81 In - the buffer size, which (must be at least 2*EC order size); 82 Out - the actual size of output data. */ 83 const uint8_t *pMsg, /*!< [in] Pointer to the message. */ 84 size_t msgSize, /*!< [in] Message size in bytes: must be less, than 85 (CC_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES - 2*(EC_EDW modulus size)). */ 86 const uint8_t *pSignSecrKey, /*!< [in] Pointer to the signer secret key (seed || pulKey) */ 87 size_t secrKeySize, /*!< [in] Size of signer secret key in bytes: (must be 2*EC order size). */ 88 CCEcEdwTempBuff_t *pTempBuff /*!< [in] pointer to the temp buffer. */); 89 90 91 92 /******************************************************************************/ 93 /*! 94 @brief The function verifies the EC Edwards ed25519 signature on the message. 95 \note The input signature is in detached form, i.e. separated from the message. 96 97 @return CC_OK on success, 98 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h or cc_hash_error.h. 99 */ 100 CIMPORT_C CCError_t CC_EcEdwVerify( 101 const uint8_t *pSign, /*!< [in] Pointer to detached signature, i.e. the 102 signature is separated from the message. */ 103 size_t signSize, /*!< [in] Size of the signature in bytes, it must be 104 equal to two EC Order size in bytes. */ 105 const uint8_t *pSignPublKey, /*!< [in] Pointer to signer public key. */ 106 size_t publKeySize, /*!< [in] Size of the signer public key in bytes; must be 107 equal to EC modulus size. */ 108 uint8_t *pMsg, /*!< [in] Pointer to the message. */ 109 size_t msgSize, /*!< [in] Pointer to the message size in bytes. Must be less than 110 (CC_HASH_UPDATE_DATA_MAX_SIZE_IN_BYTES - 2*(EC_EDW modulus size)). */ 111 CCEcEdwTempBuff_t *pEcEdwTempBuff /*!< [in] Pointer to temp buffer. */); 112 113 114 115 /*******************************************************************/ 116 /*! 117 @brief The function randomly generates Ec ed25519 private and public keys 118 using given seed. 119 The generation is performed using EC Edwards ed25519 algorithm. 120 121 @return CC_OK on success, 122 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h or cc_hash_error.h. 123 */ 124 CIMPORT_C CCError_t CC_EcEdwSeedKeyPair ( 125 const uint8_t *pSeed, /*!< [in] Pointer to the given seed. */ 126 size_t seedSize, /*!< [in] Size of the seed in bytes, must be equal the EC order size 127 in bytes. */ 128 uint8_t *pSecrKey, /*!< [out] Pointer to the secret key, including the seed, concatenated 129 with the public key. */ 130 size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of the secret key buffer in bytes 131 (must be at least 2*EC order size). */ 132 uint8_t *pPublKey, /*!< [out] Pointer to the public key. */ 133 size_t *pPublKeySize, /*!< [in/out] Pointer to the size of the public key in bytes. 134 In - the size of buffer must be at least EC modulus size; 135 Out - the actual size. */ 136 CCEcEdwTempBuff_t *pTempBuff /*!< [in] Pointer to the temp buffer, for internal use. */); 137 138 /*******************************************************************/ 139 /*! 140 @brief The function randomly generates the EC Edwards ed25519 private and 141 public keys. 142 The generation is performed using EC Edwards ed25519 algorithm. 143 144 @return CC_OK on success, 145 @return A non-zero value on failure as defined cc_ec_mont_edw_error.h, cc_hash_error.h or cc_rnd_error. 146 */ 147 CIMPORT_C CCError_t CC_EcEdwKeyPair ( 148 uint8_t *pSecrKey, /*!< [out] Pointer to the secret key (including seed and public key). */ 149 size_t *pSecrKeySize, /*!< [in/out] Pointer to the size of the secret key in bytes, 150 (must be at least 2*EC order size). */ 151 uint8_t *pPublKey, /*!< [out] Pointer to the public key. */ 152 size_t *pPublKeySize, /*!< [in/out] - Pointer to the size of the public key in bytes. 153 In - the size of buffer must be at least EC modulus size; 154 Out - the actual size. */ 155 CCRndContext_t *pRndContext, /*!< [in/out] Pointer to the RND context buffer. */ 156 CCEcEdwTempBuff_t *pTempBuff /*!< [in] Pointer to the temp buffer. */); 157 158 159 #ifdef __cplusplus 160 } 161 #endif 162 /** 163 @} 164 */ 165 166 #endif 167 168 169 170
