1 /*############################################################################ 2 # Copyright 2016-2017 Intel Corporation 3 # 4 # Licensed under the Apache License, Version 2.0 (the "License"); 5 # you may not use this file except in compliance with the License. 6 # You may obtain a copy of the License at 7 # 8 # http://www.apache.org/licenses/LICENSE-2.0 9 # 10 # Unless required by applicable law or agreed to in writing, software 11 # distributed under the License is distributed on an "AS IS" BASIS, 12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 # See the License for the specific language governing permissions and 14 # limitations under the License. 15 ############################################################################*/ 16 17 /*! 18 * \file 19 * \brief Elliptic curve group interface. 20 */ 21 22 #ifndef EPID_COMMON_MATH_ECGROUP_H_ 23 #define EPID_COMMON_MATH_ECGROUP_H_ 24 25 #include "epid/common/errors.h" 26 #include "epid/common/math/bignum.h" 27 #include "epid/common/math/finitefield.h" 28 #include "epid/common/stdtypes.h" 29 #include "epid/common/types.h" 30 31 /// Elliptic curve group operations 32 /*! 33 \defgroup EcGroupPrimitives ecgroup 34 Provides APIs for working with Elliptic curve groups. 35 Elliptic curve groups allow simple mathematical operations based on points 36 that lie on a defined elliptic curve. The results of these operations also 37 lie on the same curve. 38 39 Curves themselves are defined based on elements (::FfElement) of a finite 40 field (::FiniteField). 41 42 \ingroup EpidMath 43 @{ 44 */ 45 46 /// Elliptic curve group over finite field. 47 typedef struct EcGroup EcGroup; 48 49 /// Constructs a new EcGroup. 50 /*! 51 52 Allocates memory and creates a new elliptic curve group. 53 54 Use DeleteFiniteField() to free memory. 55 56 \param[in] ff 57 The finite field on which the curve is based. 58 \param[in] a 59 The A value of the elliptic curve. 60 \param[in] b 61 The B value of the elliptic curve. 62 \param[in] x 63 The X-coordinate of the base point of the elliptic curve. 64 \param[in] y 65 The Y-coordinate of the base point of the elliptic curve. 66 \param[in] order 67 The order of the elliptic curve group. 68 \param[in] cofactor 69 The co-factor of the elliptic curve. 70 \param[out] g 71 The newly constructed elliptic curve group. 72 73 \returns ::EpidStatus 74 75 \attention It is the responsibility of the caller to ensure that ff exists 76 for the entire lifetime of the new EcGroup. 77 78 \see DeleteEcGroup 79 */ 80 EpidStatus NewEcGroup(FiniteField const* ff, FfElement const* a, 81 FfElement const* b, FfElement const* x, 82 FfElement const* y, BigNum const* order, 83 BigNum const* cofactor, EcGroup** g); 84 85 /// Deletes a previously allocated EcGroup. 86 /*! 87 Frees memory pointed to by elliptic curve group. Nulls the pointer. 88 89 \param[in] g 90 The elliptic curve group. Can be NULL. 91 92 \see NewEcGroup 93 */ 94 void DeleteEcGroup(EcGroup** g); 95 96 /// Point on elliptic curve over finite field. 97 typedef struct EcPoint EcPoint; 98 99 /// Creates a new EcPoint. 100 /*! 101 Allocates memory and creates a new point on elliptic curve group. 102 103 Use DeleteEcPoint() to free memory. 104 105 \param[in] g 106 Elliptic curve group. 107 \param[out] p 108 Newly constructed point on the elliptic curve group g. 109 110 \returns ::EpidStatus 111 112 \attention It is the responsibility of the caller to ensure that g exists 113 for the entire lifetime of the new EcPoint. 114 115 \see NewEcGroup 116 \see DeleteEcPoint 117 */ 118 EpidStatus NewEcPoint(EcGroup const* g, EcPoint** p); 119 120 /// Deletes a previously allocated EcPoint. 121 /*! 122 123 Frees memory used by a point on elliptic curve group. Nulls the pointer. 124 125 \param[in] p 126 The EcPoint. Can be NULL. 127 128 \see NewEcPoint 129 */ 130 void DeleteEcPoint(EcPoint** p); 131 132 /// Deserializes an EcPoint from a string. 133 /*! 134 \param[in] g 135 The elliptic curve group. 136 \param[in] p_str 137 The serialized value. 138 \param[in] strlen 139 The size of p_str in bytes. 140 \param[out] p 141 The target EcPoint. 142 143 \returns ::EpidStatus 144 145 \see NewEcPoint 146 */ 147 EpidStatus ReadEcPoint(EcGroup* g, ConstOctStr p_str, size_t strlen, 148 EcPoint* p); 149 150 /// Serializes an EcPoint to a string. 151 /*! 152 \param[in] g 153 The elliptic curve group. 154 \param[in] p 155 The EcPoint to be serialized. 156 \param[out] p_str 157 The target string. 158 \param[in] strlen 159 the size of p_str in bytes. 160 161 \returns ::EpidStatus 162 163 \see NewEcPoint 164 */ 165 EpidStatus WriteEcPoint(EcGroup* g, EcPoint const* p, OctStr p_str, 166 size_t strlen); 167 168 /// Multiplies two elements in an elliptic curve group. 169 /*! 170 This multiplication operation is also known as element addition for 171 elliptic curve groups. 172 173 \param[in] g 174 The elliptic curve group. 175 \param[in] a 176 The first operand to be multiplied. 177 \param[in] b 178 The second operand to be multiplied. 179 \param[out] r 180 The result of multiplying a and b. 181 182 \returns ::EpidStatus 183 184 \see NewEcGroup 185 \see NewEcPoint 186 */ 187 EpidStatus EcMul(EcGroup* g, EcPoint const* a, EcPoint const* b, EcPoint* r); 188 189 /// Raises a point in an elliptic curve group to a power. 190 /*! 191 This exponentiation operation is also known as element multiplication 192 for elliptic curve groups. 193 \param[in] g 194 The elliptic curve group. 195 \param[in] a 196 The base. 197 \param[in] b 198 The power. Power must be less than the order of the elliptic curve 199 group. 200 \param[out] r 201 The result of raising a to the power b. 202 203 \returns ::EpidStatus 204 205 \see NewEcGroup 206 \see NewEcPoint 207 */ 208 EpidStatus EcExp(EcGroup* g, EcPoint const* a, BigNumStr const* b, EcPoint* r); 209 210 /// Software side-channel mitigated implementation of EcExp. 211 /*! 212 This exponentiation operation is also known as element multiplication 213 for elliptic curve groups. 214 215 \attention 216 The reference implementation of EcSscmExp calls EcExp directly because 217 the implementation of EcExp is already side channel mitigated. Implementers 218 providing their own versions of this function are responsible for ensuring 219 that EcSscmExp is side channel mitigated per section 8 of the 220 Intel(R) EPID 2.0 spec. 221 222 \param[in] g 223 The elliptic curve group. 224 \param[in] a 225 The base. 226 \param[in] b 227 The power. Power must be less than the order of the elliptic curve 228 group. 229 \param[out] r 230 The result of raising a to the power b. 231 232 \returns ::EpidStatus 233 234 \see NewEcGroup 235 \see NewEcPoint 236 */ 237 EpidStatus EcSscmExp(EcGroup* g, EcPoint const* a, BigNumStr const* b, 238 EcPoint* r); 239 240 /// Multi-exponentiates elements in elliptic curve group. 241 /*! 242 Takes a group elements a[0], ... , a[m-1] in G and positive 243 integers b[0], ..., b[m-1], where m is a small positive integer. 244 Outputs r (in G) = EcExp(a[0],b[0]) * ... * EcExp(a[m-1],b[m-1]). 245 246 \param[in] g 247 The elliptic curve group. 248 \param[in] a 249 The bases. 250 \param[in] b 251 The powers. Power must be less than the order of the elliptic curve 252 group. 253 \param[in] m 254 Number of entries in a and b. 255 \param[out] r 256 The result of raising each a to the corresponding power b and multiplying 257 the results. 258 259 \returns ::EpidStatus 260 261 \see NewEcGroup 262 \see NewEcPoint 263 */ 264 EpidStatus EcMultiExp(EcGroup* g, EcPoint const** a, BigNumStr const** b, 265 size_t m, EcPoint* r); 266 267 /// Multi-exponentiates elements in elliptic curve group. 268 /*! 269 Takes a group elements a[0], ... , a[m-1] in G and positive 270 integers b[0], ..., b[m-1], where m is a small positive integer. 271 Outputs r (in G) = EcExp(a[0],b[0]) * ... * EcExp(a[m-1],b[m-1]). 272 273 \param[in] g 274 The elliptic curve group. 275 \param[in] a 276 The bases. 277 \param[in] b 278 The powers. Power must be less than the order of the elliptic curve 279 group. 280 \param[in] m 281 Number of entries in a and b. 282 \param[out] r 283 The result of raising each a to the corresponding power b and multiplying 284 the results. 285 286 \returns ::EpidStatus 287 288 \see NewEcGroup 289 \see NewEcPoint 290 */ 291 EpidStatus EcMultiExpBn(EcGroup* g, EcPoint const** a, BigNum const** b, 292 size_t m, EcPoint* r); 293 294 /// Software side-channel mitigated implementation of EcMultiExp. 295 /*! 296 Takes a group elements a[0], ... , a[m-1] in G and positive 297 integers b[0], ..., b[m-1], where m is a small positive integer. 298 Outputs r (in G) = EcExp(a[0],b[0]) * ... * EcExp(a[m-1],b[m-1]). 299 300 \attention 301 The reference implementation of EcSscmMultiExp calls EcMultiExp 302 directly because the implementation of EcMultiExp is already side channel 303 mitigated. Implementers providing their own versions of this function are 304 responsible for ensuring that EcSscmMultiExp is side channel mitigated per 305 section 8 of the Intel(R) EPID 2.0 spec. 306 307 \param[in] g 308 The elliptic curve group. 309 \param[in] a 310 The bases. 311 \param[in] b 312 The powers. Power must be less than the order of the elliptic curve 313 group. 314 \param[in] m 315 Number of entries in a and b. 316 \param[out] r 317 The result of raising each a to the corresponding power b and 318 multiplying the results. 319 320 \returns ::EpidStatus 321 322 \see NewEcGroup 323 \see NewEcPoint 324 */ 325 EpidStatus EcSscmMultiExp(EcGroup* g, EcPoint const** a, BigNumStr const** b, 326 size_t m, EcPoint* r); 327 328 /// Generates a random element from an elliptic curve group. 329 /*! 330 This function is only available for G1 and GT. 331 332 \param[in] g 333 The elliptic curve group. 334 \param[in] rnd_func 335 Random number generator. 336 \param[in] rnd_func_param 337 Pass through context data for rnd_func. 338 \param[in,out] r 339 Output random elliptic curve element. 340 341 \returns ::EpidStatus 342 343 \see NewEcPoint 344 \see BitSupplier 345 */ 346 EpidStatus EcGetRandom(EcGroup* g, BitSupplier rnd_func, void* rnd_func_param, 347 EcPoint* r); 348 349 /// Checks if a point is in an elliptic curve group. 350 /*! 351 \param[in] g 352 The elliptic curve group. 353 \param[in] p_str 354 A serialized point. Must be a G1ElemStr or G2ElemStr. 355 \param[in] strlen 356 The size of p_str in bytes. 357 \param[out] in_group 358 The result of the check. 359 360 \returns ::EpidStatus 361 362 \see NewEcPoint 363 */ 364 EpidStatus EcInGroup(EcGroup* g, ConstOctStr p_str, size_t strlen, 365 bool* in_group); 366 367 /// Hashes an arbitrary message to an Intel(R) EPID 1.1 element in an elliptic 368 /// curve group. 369 /*! 370 \param[in] g 371 The elliptic curve group. 372 \param[in] msg 373 The message. 374 \param[in] msg_len 375 The size of msg in bytes. 376 \param[out] r 377 The hashed value. 378 379 \returns ::EpidStatus 380 381 \see NewEcGroup 382 \see NewEcPoint 383 */ 384 EpidStatus Epid11EcHash(EcGroup* g, ConstOctStr msg, size_t msg_len, 385 EcPoint* r); 386 387 /// Hashes an arbitrary message to an element in an elliptic curve group. 388 /*! 389 \param[in] g 390 The elliptic curve group. 391 \param[in] msg 392 The message. 393 \param[in] msg_len 394 The size of msg in bytes. 395 \param[in] hash_alg 396 The hash algorithm. 397 \param[out] r 398 The hashed value. 399 \param[out] iterations 400 The number of hash iterations needed to find a valid hash. Can be NULL. 401 402 \returns ::EpidStatus 403 404 \see NewEcGroup 405 \see NewEcPoint 406 */ 407 EpidStatus EcHash(EcGroup* g, ConstOctStr msg, size_t msg_len, HashAlg hash_alg, 408 EcPoint* r, uint32_t* iterations); 409 410 /// Sets an EcPoint variable to a point on a curve. 411 /*! 412 This function is only available for G1. 413 414 \param[in] g 415 The elliptic curve group. 416 \param[in] x 417 The x coordinate. 418 \param[out] r 419 The point. 420 421 \returns ::EpidStatus 422 423 \see NewEcGroup 424 \see NewEcPoint 425 \see NewFfElement 426 */ 427 EpidStatus EcMakePoint(EcGroup* g, FfElement const* x, EcPoint* r); 428 429 /// Computes the additive inverse of an EcPoint. 430 /*! 431 This inverse operation is also known as element negation 432 for elliptic curve groups. 433 434 \param[in] g 435 The elliptic curve group. 436 \param[in] p 437 The point. 438 \param[out] r 439 The inverted point. 440 441 \returns ::EpidStatus 442 443 \see NewEcGroup 444 \see NewEcPoint 445 */ 446 EpidStatus EcInverse(EcGroup* g, EcPoint const* p, EcPoint* r); 447 448 /// Checks if two EcPoints are equal. 449 /*! 450 \param[in] g 451 The elliptic curve group. 452 \param[in] a 453 A point to check. 454 \param[in] b 455 Another point to check. 456 \param[out] is_equal 457 The result of the check. 458 459 \returns ::EpidStatus 460 461 \see NewEcGroup 462 \see NewEcPoint 463 */ 464 EpidStatus EcIsEqual(EcGroup* g, EcPoint const* a, EcPoint const* b, 465 bool* is_equal); 466 467 /// Checks if an EcPoint is the identity element. 468 /*! 469 470 Takes a group element P as input. It outputs true if P is the 471 identity element of G. Otherwise, it outputs false. 472 473 \param[in] g 474 The elliptic curve group. 475 \param[in] p 476 The point to check. 477 \param[out] is_identity 478 The result of the check. 479 480 \returns ::EpidStatus 481 482 \see NewEcGroup 483 \see NewEcPoint 484 */ 485 EpidStatus EcIsIdentity(EcGroup* g, EcPoint const* p, bool* is_identity); 486 487 /*! 488 @} 489 */ 490 #endif // EPID_COMMON_MATH_ECGROUP_H_ 491