1 /* Microsoft Reference Implementation for TPM 2.0 2 * 3 * The copyright in this software is being made available under the BSD License, 4 * included below. This software may be subject to other third party and 5 * contributor rights, including patent rights, and no such rights are granted 6 * under this license. 7 * 8 * Copyright (c) Microsoft Corporation 9 * 10 * All rights reserved. 11 * 12 * BSD License 13 * 14 * Redistribution and use in source and binary forms, with or without modification, 15 * are permitted provided that the following conditions are met: 16 * 17 * Redistributions of source code must retain the above copyright notice, this list 18 * of conditions and the following disclaimer. 19 * 20 * Redistributions in binary form must reproduce the above copyright notice, this 21 * list of conditions and the following disclaimer in the documentation and/or 22 * other materials provided with the distribution. 23 * 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS"" 25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 27 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 28 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 31 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 34 */ 35 /*(Auto-generated) 36 * Created by TpmPrototypes; Version 3.0 July 18, 2017 37 * Date: Apr 2, 2019 Time: 03:18:00PM 38 */ 39 40 #ifndef _CRYPT_ECC_MAIN_FP_H_ 41 #define _CRYPT_ECC_MAIN_FP_H_ 42 43 #if ALG_ECC 44 45 //** Functions 46 #if SIMULATION 47 void 48 EccSimulationEnd( 49 void 50 ); 51 #endif // SIMULATION 52 53 //*** CryptEccInit() 54 // This function is called at _TPM_Init 55 BOOL 56 CryptEccInit( 57 void 58 ); 59 60 //*** CryptEccStartup() 61 // This function is called at TPM2_Startup(). 62 BOOL 63 CryptEccStartup( 64 void 65 ); 66 67 //*** ClearPoint2B(generic) 68 // Initialize the size values of a TPMS_ECC_POINT structure. 69 void 70 ClearPoint2B( 71 TPMS_ECC_POINT *p // IN: the point 72 ); 73 74 //*** CryptEccGetParametersByCurveId() 75 // This function returns a pointer to the curve data that is associated with 76 // the indicated curveId. 77 // If there is no curve with the indicated ID, the function returns NULL. This 78 // function is in this module so that it can be called by GetCurve data. 79 // Return Type: const ECC_CURVE_DATA 80 // NULL curve with the indicated TPM_ECC_CURVE is not implemented 81 // != NULL pointer to the curve data 82 LIB_EXPORT const ECC_CURVE * 83 CryptEccGetParametersByCurveId( 84 TPM_ECC_CURVE curveId // IN: the curveID 85 ); 86 87 //*** CryptEccGetKeySizeForCurve() 88 // This function returns the key size in bits of the indicated curve. 89 LIB_EXPORT UINT16 90 CryptEccGetKeySizeForCurve( 91 TPM_ECC_CURVE curveId // IN: the curve 92 ); 93 94 //*** GetCurveData() 95 // This function returns the a pointer for the parameter data 96 // associated with a curve. 97 const ECC_CURVE_DATA * 98 GetCurveData( 99 TPM_ECC_CURVE curveId // IN: the curveID 100 ); 101 102 //***CryptEccGetOID() 103 const BYTE * 104 CryptEccGetOID( 105 TPM_ECC_CURVE curveId 106 ); 107 108 //*** CryptEccGetCurveByIndex() 109 // This function returns the number of the 'i'-th implemented curve. The normal 110 // use would be to call this function with 'i' starting at 0. When the 'i' is greater 111 // than or equal to the number of implemented curves, TPM_ECC_NONE is returned. 112 LIB_EXPORT TPM_ECC_CURVE 113 CryptEccGetCurveByIndex( 114 UINT16 i 115 ); 116 117 //*** CryptEccGetParameter() 118 // This function returns an ECC curve parameter. The parameter is 119 // selected by a single character designator from the set of ""PNABXYH"". 120 // Return Type: BOOL 121 // TRUE(1) curve exists and parameter returned 122 // FALSE(0) curve does not exist or parameter selector 123 LIB_EXPORT BOOL 124 CryptEccGetParameter( 125 TPM2B_ECC_PARAMETER *out, // OUT: place to put parameter 126 char p, // IN: the parameter selector 127 TPM_ECC_CURVE curveId // IN: the curve id 128 ); 129 130 //*** CryptCapGetECCCurve() 131 // This function returns the list of implemented ECC curves. 132 // Return Type: TPMI_YES_NO 133 // YES if no more ECC curve is available 134 // NO if there are more ECC curves not reported 135 TPMI_YES_NO 136 CryptCapGetECCCurve( 137 TPM_ECC_CURVE curveID, // IN: the starting ECC curve 138 UINT32 maxCount, // IN: count of returned curves 139 TPML_ECC_CURVE *curveList // OUT: ECC curve list 140 ); 141 142 //*** CryptGetCurveSignScheme() 143 // This function will return a pointer to the scheme of the curve. 144 const TPMT_ECC_SCHEME * 145 CryptGetCurveSignScheme( 146 TPM_ECC_CURVE curveId // IN: The curve selector 147 ); 148 149 //*** CryptGenerateR() 150 // This function computes the commit random value for a split signing scheme. 151 // 152 // If 'c' is NULL, it indicates that 'r' is being generated 153 // for TPM2_Commit. 154 // If 'c' is not NULL, the TPM will validate that the 'gr.commitArray' 155 // bit associated with the input value of 'c' is SET. If not, the TPM 156 // returns FALSE and no 'r' value is generated. 157 // Return Type: BOOL 158 // TRUE(1) r value computed 159 // FALSE(0) no r value computed 160 BOOL 161 CryptGenerateR( 162 TPM2B_ECC_PARAMETER *r, // OUT: the generated random value 163 UINT16 *c, // IN/OUT: count value. 164 TPMI_ECC_CURVE curveID, // IN: the curve for the value 165 TPM2B_NAME *name // IN: optional name of a key to 166 // associate with 'r' 167 ); 168 169 //*** CryptCommit() 170 // This function is called when the count value is committed. The 'gr.commitArray' 171 // value associated with the current count value is SET and g_commitCounter is 172 // incremented. The low-order 16 bits of old value of the counter is returned. 173 UINT16 174 CryptCommit( 175 void 176 ); 177 178 //*** CryptEndCommit() 179 // This function is called when the signing operation using the committed value 180 // is completed. It clears the gr.commitArray bit associated with the count 181 // value so that it can't be used again. 182 void 183 CryptEndCommit( 184 UINT16 c // IN: the counter value of the commitment 185 ); 186 187 //*** CryptEccGetParameters() 188 // This function returns the ECC parameter details of the given curve. 189 // Return Type: BOOL 190 // TRUE(1) success 191 // FALSE(0) unsupported ECC curve ID 192 BOOL 193 CryptEccGetParameters( 194 TPM_ECC_CURVE curveId, // IN: ECC curve ID 195 TPMS_ALGORITHM_DETAIL_ECC *parameters // OUT: ECC parameters 196 ); 197 198 //*** BnGetCurvePrime() 199 // This function is used to get just the prime modulus associated with a curve. 200 const bignum_t * 201 BnGetCurvePrime( 202 TPM_ECC_CURVE curveId 203 ); 204 205 //*** BnGetCurveOrder() 206 // This function is used to get just the curve order 207 const bignum_t * 208 BnGetCurveOrder( 209 TPM_ECC_CURVE curveId 210 ); 211 212 //*** BnIsOnCurve() 213 // This function checks if a point is on the curve. 214 BOOL 215 BnIsOnCurve( 216 pointConst Q, 217 const ECC_CURVE_DATA *C 218 ); 219 220 //*** BnIsValidPrivateEcc() 221 // Checks that 0 < 'x' < 'q' 222 BOOL 223 BnIsValidPrivateEcc( 224 bigConst x, // IN: private key to check 225 bigCurve E // IN: the curve to check 226 ); 227 228 LIB_EXPORT BOOL 229 CryptEccIsValidPrivateKey( 230 TPM2B_ECC_PARAMETER *d, 231 TPM_ECC_CURVE curveId 232 ); 233 234 //*** BnPointMul() 235 // This function does a point multiply of the form 'R' = ['d']'S' + ['u']'Q' where the 236 // parameters are bigNum values. If 'S' is NULL and d is not NULL, then it computes 237 // 'R' = ['d']'G' + ['u']'Q' or just 'R' = ['d']'G' if 'u' and 'Q' are NULL. 238 // If 'skipChecks' is TRUE, then the function will not verify that the inputs are 239 // correct for the domain. This would be the case when the values were created by the 240 // CryptoEngine code. 241 // It will return TPM_RC_NO_RESULT if the resulting point is the point at infinity. 242 // Return Type: TPM_RC 243 // TPM_RC_NO_RESULT result of multiplication is a point at infinity 244 // TPM_RC_ECC_POINT 'S' or 'Q' is not on the curve 245 // TPM_RC_VALUE 'd' or 'u' is not < n 246 TPM_RC 247 BnPointMult( 248 bigPoint R, // OUT: computed point 249 pointConst S, // IN: optional point to multiply by 'd' 250 bigConst d, // IN: scalar for [d]S or [d]G 251 pointConst Q, // IN: optional second point 252 bigConst u, // IN: optional second scalar 253 bigCurve E // IN: curve parameters 254 ); 255 256 //***BnEccGetPrivate() 257 // This function gets random values that are the size of the key plus 64 bits. The 258 // value is reduced (mod ('q' - 1)) and incremented by 1 ('q' is the order of the 259 // curve. This produces a value ('d') such that 1 <= 'd' < 'q'. This is the method 260 // of FIPS 186-4 Section B.4.1 ""Key Pair Generation Using Extra Random Bits"". 261 // Return Type: BOOL 262 // TRUE(1) success 263 // FALSE(0) failure generating private key 264 BOOL 265 BnEccGetPrivate( 266 bigNum dOut, // OUT: the qualified random value 267 const ECC_CURVE_DATA *C, // IN: curve for which the private key 268 // needs to be appropriate 269 RAND_STATE *rand // IN: state for DRBG 270 ); 271 272 //*** BnEccGenerateKeyPair() 273 // This function gets a private scalar from the source of random bits and does 274 // the point multiply to get the public key. 275 BOOL 276 BnEccGenerateKeyPair( 277 bigNum bnD, // OUT: private scalar 278 bn_point_t *ecQ, // OUT: public point 279 bigCurve E, // IN: curve for the point 280 RAND_STATE *rand // IN: DRBG state to use 281 ); 282 283 //***CryptEccNewKeyPair(***) 284 // This function creates an ephemeral ECC. It is ephemeral in that 285 // is expected that the private part of the key will be discarded 286 LIB_EXPORT TPM_RC 287 CryptEccNewKeyPair( 288 TPMS_ECC_POINT *Qout, // OUT: the public point 289 TPM2B_ECC_PARAMETER *dOut, // OUT: the private scalar 290 TPM_ECC_CURVE curveId // IN: the curve for the key 291 ); 292 293 //*** CryptEccPointMultiply() 294 // This function computes 'R' := ['dIn']'G' + ['uIn']'QIn'. Where 'dIn' and 295 // 'uIn' are scalars, 'G' and 'QIn' are points on the specified curve and 'G' is the 296 // default generator of the curve. 297 // 298 // The 'xOut' and 'yOut' parameters are optional and may be set to NULL if not 299 // used. 300 // 301 // It is not necessary to provide 'uIn' if 'QIn' is specified but one of 'uIn' and 302 // 'dIn' must be provided. If 'dIn' and 'QIn' are specified but 'uIn' is not 303 // provided, then 'R' = ['dIn']'QIn'. 304 // 305 // If the multiply produces the point at infinity, the TPM_RC_NO_RESULT is returned. 306 // 307 // The sizes of 'xOut' and yOut' will be set to be the size of the degree of 308 // the curve 309 // 310 // It is a fatal error if 'dIn' and 'uIn' are both unspecified (NULL) or if 'Qin' 311 // or 'Rout' is unspecified. 312 // 313 // Return Type: TPM_RC 314 // TPM_RC_ECC_POINT the point 'Pin' or 'Qin' is not on the curve 315 // TPM_RC_NO_RESULT the product point is at infinity 316 // TPM_RC_CURVE bad curve 317 // TPM_RC_VALUE 'dIn' or 'uIn' out of range 318 // 319 LIB_EXPORT TPM_RC 320 CryptEccPointMultiply( 321 TPMS_ECC_POINT *Rout, // OUT: the product point R 322 TPM_ECC_CURVE curveId, // IN: the curve to use 323 TPMS_ECC_POINT *Pin, // IN: first point (can be null) 324 TPM2B_ECC_PARAMETER *dIn, // IN: scalar value for [dIn]Qin 325 // the Pin 326 TPMS_ECC_POINT *Qin, // IN: point Q 327 TPM2B_ECC_PARAMETER *uIn // IN: scalar value for the multiplier 328 // of Q 329 ); 330 331 //*** CryptEccIsPointOnCurve() 332 // This function is used to test if a point is on a defined curve. It does this 333 // by checking that 'y'^2 mod 'p' = 'x'^3 + 'a'*'x' + 'b' mod 'p'. 334 // 335 // It is a fatal error if 'Q' is not specified (is NULL). 336 // Return Type: BOOL 337 // TRUE(1) point is on curve 338 // FALSE(0) point is not on curve or curve is not supported 339 LIB_EXPORT BOOL 340 CryptEccIsPointOnCurve( 341 TPM_ECC_CURVE curveId, // IN: the curve selector 342 TPMS_ECC_POINT *Qin // IN: the point. 343 ); 344 345 //*** CryptEccGenerateKey() 346 // This function generates an ECC key pair based on the input parameters. 347 // This routine uses KDFa to produce candidate numbers. The method is according 348 // to FIPS 186-3, section B.1.2 "Key Pair Generation by Testing Candidates." 349 // According to the method in FIPS 186-3, the resulting private value 'd' should be 350 // 1 <= 'd' < 'n' where 'n' is the order of the base point. 351 // 352 // It is a fatal error if 'Qout', 'dOut', is not provided (is NULL). 353 // 354 // If the curve is not supported 355 // If 'seed' is not provided, then a random number will be used for the key 356 // Return Type: TPM_RC 357 // TPM_RC_CURVE curve is not supported 358 // TPM_RC_NO_RESULT could not verify key with signature (FIPS only) 359 LIB_EXPORT TPM_RC 360 CryptEccGenerateKey( 361 TPMT_PUBLIC *publicArea, // IN/OUT: The public area template for 362 // the new key. The public key 363 // area will be replaced computed 364 // ECC public key 365 TPMT_SENSITIVE *sensitive, // OUT: the sensitive area will be 366 // updated to contain the private 367 // ECC key and the symmetric 368 // encryption key 369 RAND_STATE *rand // IN: if not NULL, the deterministic 370 // RNG state 371 ); 372 #endif // ALG_ECC 373 374 #endif // _CRYPT_ECC_MAIN_FP_H_ 375