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 Pairing interface. 20 */ 21 22 #ifndef EPID_COMMON_MATH_PAIRING_H_ 23 #define EPID_COMMON_MATH_PAIRING_H_ 24 25 #include "epid/common/errors.h" 26 #include "epid/common/math/ecgroup.h" 27 #include "epid/common/math/finitefield.h" 28 #include "epid/common/types.h" 29 30 /// Pairing operations 31 /*! 32 \defgroup PairingPrimitives pairing 33 Provides APIs for defining and using a pairing relationship between two 34 elliptic curve groups. 35 36 \ingroup EpidMath 37 @{ 38 */ 39 40 /// A pairing 41 typedef struct PairingState PairingState; 42 43 /// Constructs a new pairing state. 44 /*! 45 Allocates memory and creates a new pairing state for Optimal Ate Pairing. 46 47 Use DeletePairingState() to free memory. 48 49 \param[in] ga 50 The EcGroup from which the first parameter of the pairing is taken. 51 \param[in] gb 52 The EcGroup from which the second parameter of the pairing is taken. 53 \param[in] ff 54 The result finite field. Must be a Fq12 field. 55 \param[in] t 56 A positive integer such that 6(t^2) == q - p, where p and q are parameters 57 of G1. 58 \param[in] neg 59 Select the alternate "negate" processing path for Optimal Ate Pairing. 60 \param[out] ps 61 Newly constructed pairing state. 62 63 \returns ::EpidStatus 64 65 \attention It is the responsibility of the caller to ensure that ga, gb, and 66 ff exist for the entire lifetime of the new PairingState. 67 68 \see DeletePairingState 69 */ 70 EpidStatus NewPairingState(EcGroup const* ga, EcGroup const* gb, 71 FiniteField* ff, BigNumStr const* t, bool neg, 72 PairingState** ps); 73 74 /// Frees a previously allocated by PairingState. 75 /*! 76 Frees memory pointed to by pairing state. Nulls the pointer. 77 78 \param[in] ps 79 The pairing state. Can be NULL. 80 81 \see NewPairingState 82 */ 83 void DeletePairingState(PairingState** ps); 84 85 /// Computes an Optimal Ate Pairing for two parameters. 86 /*! 87 \param[in] ps 88 The pairing state. 89 \param[in] a 90 The first value to pair. Must be in ga used to create ps. 91 \param[in] b 92 The second value to pair. Must be in gb used to create ps 93 \param[out] d 94 The result of the pairing. Will be in ff used to create the pairing state. 95 96 \returns ::EpidStatus 97 */ 98 EpidStatus Pairing(PairingState* ps, EcPoint const* a, EcPoint const* b, 99 FfElement* d); 100 101 /*! 102 @} 103 */ 104 105 #endif // EPID_COMMON_MATH_PAIRING_H_ 106