1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 8 #ifndef _CC_ECPKI_LOCAL_H 9 #define _CC_ECPKI_LOCAL_H 10 11 /** @file 12 * @brief this file contains the prototype of the service functions for 13 * the CryptoCell ECPKI module that are intendet for internaly usage. */ 14 15 16 #include "cc_error.h" 17 #include "cc_ecpki_types.h" 18 #include "cc_rnd_common.h" 19 20 #ifdef __cplusplus 21 extern "C" 22 { 23 #endif 24 25 /************************ Defines ******************************/ 26 27 /*-------------------------------------------------*/ 28 /* User passed structures validation tags */ 29 /*-------------------------------------------------*/ 30 31 /* the ECPKI user public key user validity TAG */ 32 #define CC_ECPKI_PUBL_KEY_VALIDATION_TAG 0xEC000001 33 /* the ECPKI user private key user validity TAG */ 34 #define CC_ECPKI_PRIV_KEY_VALIDATION_TAG 0xEC000002 35 36 /* the ECDSA signing user context validity TAG */ 37 #define CC_ECDSA_SIGN_CONTEXT_VALIDATION_TAG 0xEC000003 38 /* the ECDSA verifying user context validity TAG */ 39 #define CC_ECDSA_VERIFY_CONTEXT_VALIDATION_TAG 0xEC000004 40 41 typedef struct { 42 uint16_t hashResultSize; 43 CCHashOperationMode_t hashMode; 44 }CCEcpkiHash_t; 45 46 47 48 49 /************************ macros ********************************/ 50 51 /************************ Typedefs *****************************/ 52 53 /************************ Structs ******************************/ 54 55 /************************ Public Variables **********************/ 56 57 /************************ Public Functions **********************/ 58 /************************************************************************** 59 * EcdsaSignInit function 60 **************************************************************************/ 61 /*! 62 @brief 63 The EcdsaSignInit functions user shall call first to perform the EC DSA Signing operation. 64 65 The function performs the following steps: 66 -# Validates all the inputs of the function. If one of the received 67 parameters is not valid, the function returns an error. 68 -# Calls the CC_HashInit() function. 69 -# Exits the handler with the OK code. 70 71 This function does not do ECDSA cryptographic processing. Rather, it 72 prepares a context that is used by the Update() and Finish() functions. 73 74 @note 75 Using of HASH functions with HASH size great, than EC modulus size, is not recommended! 76 77 @return CC_OK on success. 78 @return a non-zero value on failure as defined cc_ecpki_error.h. 79 */ 80 CIMPORT_C CCError_t EcdsaSignInit( 81 CCEcdsaSignUserContext_t *pSignUserContext, /*!< [in/out] A pointer to the user buffer for signing data. */ 82 CCEcpkiUserPrivKey_t *pSignerPrivKey, /*!< [in] A pointer to the private key that is used to sign the data. */ 83 CCEcpkiHashOpMode_t hashMode /*!< [in] Defines the hash mode used for DSA. */ 84 ); 85 86 /************************************************************************** 87 * EcdsaSignUpdate function 88 **************************************************************************/ 89 /*! 90 @brief Performs a hash operation on data allocated by the user 91 before finally signing it. 92 93 In case user divides signing data by block, he must call the Update function 94 continuously a number of times until processing of the entire data block is complete. 95 96 @note 97 Using of HASH functions with HASH size great, than EC modulus size, is not recommended! 98 99 @return CC_OK on success. 100 @return a non-zero value on failure as defined cc_ecpki_error.h. 101 */ 102 CIMPORT_C CCError_t EcdsaSignUpdate( 103 CCEcdsaSignUserContext_t *pSignUserContext, /*!< [in/out] The pointer to the user buffer for signing the database. */ 104 uint8_t *pMessageDataIn, /*!< [in] The pointer to the message data block for calculating the HASH. */ 105 size_t dataInSize /*!< [in] The size of the message data block, in bytes. 106 The data size, passed on each call of the function, besides the last call, 107 must be a multiple of the HASH block size according to used HASH mode. */ 108 ); 109 110 /************************************************************************** 111 * _DX_ECDSA_Sign_Finish function 112 **************************************************************************/ 113 /*! 114 @brief Performs initialization of variables and structures, calls the hash function 115 for the last block of data (if necessary) and then calculates digital signature. 116 Algorithm according ANS X9.62 standard. 117 118 @note 119 Using of HASH functions with HASH size great, than EC modulus size, is not recommended! 120 121 @return CC_OK on success. 122 @return a non-zero value on failure as defined cc_ecpki_error.h. 123 **/ 124 CIMPORT_C CCError_t EcdsaSignFinishInt( 125 CCEcdsaSignUserContext_t *pSignUserContext, /*!< [in] A pointer to the user buffer for signing database. */ 126 CCRndContext_t *pRndContext, /*!< [in/out] A pointer to the random generation function context. */ 127 uint8_t *pSignOut, /*!< [out] A pointer to a buffer for output of signature. */ 128 size_t *pSignOutSize, /*!< [in/out] A pointer to the size of a user passed buffer for 129 signature (in), be not less than 2*orderSizeInBytes. */ 130 uint32_t isEphemerKeyInternal, /*!< [in] A parameter defining whether the ephemeral key is 131 internal or external (1 or 0). */ 132 uint32_t *pEphemerKeyData /*!< [in] A pointer to external ephemeral key data. 133 If it is given (case isEphemerKeyInternal=0), then the buffer 134 must containing the ephemeral private key of size equal to 135 EC generator order size, where LS-word is left most and MS-word 136 is right most one. */ 137 ); 138 139 /************************************************************************** 140 * EcdsaSignFinish function 141 **************************************************************************/ 142 /*! 143 @brief The macro definition for calling the ::EcdsaSignFinishInt function with internal generation of ephemeral keys. 144 145 @note 146 Using of HASH functions with HASH size great, than EC modulus size, is not recommended! 147 148 The macro calls the function with the following arguments as constant: 149 isEphemerKeyInternal = 1 and pEphemerKeyData = NULL. 150 */ 151 #define EcdsaSignFinish(pSignUserContext, pRndContext, pSignatureOut, pSignatureOutSize) \ 152 EcdsaSignFinishInt((pSignUserContext), (pRndContext), (pSignatureOut), (pSignatureOutSize), 1, NULL) 153 154 /************************************************************************** 155 * EcdsaVerifyInit function 156 **************************************************************************/ 157 /*! 158 @brief Prepares a context that is used by the Update and Finish functions 159 but does not perform elliptic curve cryptographic processing 160 161 The function: 162 - Receives and decrypts user data (working context). 163 - Checks input parameters of ECDSA Verifying primitive. 164 - Calls hash init function. 165 - Initializes variables and structures for calling next functions. 166 - Encrypts and releases working context. 167 168 @note 169 Using of HASH functions with HASH size great, than EC modulus size, is not recommended! 170 171 @return CC_OK on success. 172 @return a non-zero value on failure as defined cc_ecpki_error.h. 173 */ 174 CIMPORT_C CCError_t EcdsaVerifyInit( 175 CCEcdsaVerifyUserContext_t *pVerifyUserContext, /*!< [in/out] A pointer to the user buffer for verifying database. */ 176 CCEcpkiUserPublKey_t *pSignerPublKey, /*!< [in] A pointer to a Signer public key structure. */ 177 CCEcpkiHashOpMode_t hashMode /*!< [in] The enumerator variable defines the hash function to be used. */ 178 ); 179 180 181 /************************************************************************** 182 * EcdsaVerifyUpdate function 183 **************************************************************************/ 184 /*! 185 @brief Performs a hash operation on data allocated by the user 186 before finally verifying its signature. 187 188 In case user divides signing data by block, he must call the Update function 189 continuously a number of times until processing of the entire data block is complete. 190 191 @note 192 Using of HASH functions with HASH size greater, than EC modulus size, is not recommended. 193 194 @return CC_OK on success. 195 @return a non-zero value on failure as defined cc_ecpki_error.h. 196 */ 197 CIMPORT_C CCError_t EcdsaVerifyUpdate( 198 CCEcdsaVerifyUserContext_t *pVerifyUserContext, /*!< [in/out] The pointer to the user buffer for verifying database. */ 199 uint8_t *pMessageDataIn, /*!< [in] The message data for calculating Hash. */ 200 size_t dataInSize /*!< [in] The size of the message data block, in bytes. 201 The data size, passed on each call of the function, besides the last call, 202 must be a multiple of the HASH block size according to used HASH mode. */ 203 ); 204 205 206 /************************************************************************** 207 * EcdsaVerifyFinish function 208 **************************************************************************/ 209 210 /*! 211 @brief Performs initialization of variables and structures, 212 calls the hash function for the last block of data (if necessary), 213 than calls EcWrstDsaVerify function for verifying signature according to 214 ANS X9.62 standard. 215 216 @note 217 Using of HASH functions with HASH size greater, than EC modulus size, is not recommended! 218 219 @return CC_OK on success. 220 @return a non-zero value on failure as defined cc_ecpki_error.h. 221 **/ 222 CIMPORT_C CCError_t EcdsaVerifyFinish( 223 CCEcdsaVerifyUserContext_t *pVerifyUserContext, /*!< [in] A pointer to the user buffer for verifying the database. */ 224 uint8_t *pSignatureIn, /*!< [in] A pointer to a buffer for the signature to be compared. */ 225 size_t SignatureSizeBytes /*!< [in] The size of a user passed signature (must be 2*orderSizeInBytes). */ 226 ); 227 228 229 230 231 232 #ifdef __cplusplus 233 } 234 #endif 235 236 #endif /* #ifndef _CC_ECPKI_LOCAL_H */ 237 238
