1 /*############################################################################ 2 # Copyright 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 /// Definition of Fq math 17 /*! \file */ 18 19 #ifndef EPID_MEMBER_TINY_MATH_FQ_H_ 20 #define EPID_MEMBER_TINY_MATH_FQ_H_ 21 22 #include <stddef.h> 23 #include <stdint.h> 24 #include "epid/common/bitsupplier.h" 25 26 /// \cond 27 typedef struct FqElem FqElem; 28 typedef struct VeryLargeInt VeryLargeInt; 29 /// \endcond 30 31 /// Test if an element is in Fq. 32 /*! 33 \param[in] in the element to test. 34 \returns A value different from zero (i.e., true) indeed 35 the value is in the field. Zero (i.e., false) otherwise. 36 */ 37 int FqInField(FqElem const* in); 38 39 /// Add two elements of Fq. 40 /*! 41 \param[out] result of adding left and right. 42 \param[in] left The first operand to be added. 43 \param[in] right The second operand to be added. 44 */ 45 void FqAdd(FqElem* result, FqElem const* left, FqElem const* right); 46 47 /// Subtract two elements of Fq. 48 /*! 49 \param[out] result of subtracting left from right. 50 \param[in] left The operand to be subtracted from. 51 \param[in] right The operand to subtract. 52 */ 53 void FqSub(FqElem* result, FqElem const* left, FqElem const* right); 54 55 /// Multiply two elements of Fq. 56 /*! 57 \param[out] result of multiplying left and right. 58 \param[in] left The first operand to be multiplied. 59 \param[in] right The second operand to be multiplied. 60 */ 61 void FqMul(FqElem* result, FqElem const* left, FqElem const* right); 62 63 /// Exponentiate an element of Fq by a large integer. 64 /*! 65 \param[out] result target. 66 \param[in] base the base. 67 \param[in] exp the exponent. 68 */ 69 void FqExp(FqElem* result, FqElem const* base, VeryLargeInt const* exp); 70 71 /// Copy an element's value 72 /*! 73 \param[out] result copy target. 74 \param[in] in copy source. 75 */ 76 void FqCp(FqElem* result, FqElem const* in); 77 78 /// Test if an element is zero. 79 /*! 80 \param[in] value the element to test. 81 \returns A value different from zero (i.e., true) if indeed 82 the value is zero. Zero (i.e., false) otherwise. 83 */ 84 int FqIsZero(FqElem const* value); 85 86 /// Invert an element of Fq. 87 /*! 88 \param[out] result the inverse of the element. 89 \param[in] in the element to invert. 90 */ 91 void FqInv(FqElem* result, FqElem const* in); 92 93 /// Negate an element of Fq. 94 /*! 95 This function was formerly called as FqConst. 96 97 \param[out] result the negative of the element. 98 \param[in] in the element to negate. 99 */ 100 void FqNeg(FqElem* result, FqElem const* in); 101 102 /// Square an element of Fq. 103 /*! 104 \param[out] result the square of the element. 105 \param[in] in the element to square. 106 */ 107 void FqSquare(FqElem* result, FqElem const* in); 108 109 /// Clear an element's value. 110 /*! 111 \param[out] result element to clear. 112 */ 113 void FqClear(FqElem* result); 114 115 /// Set an element's value. 116 /*! 117 \param[out] result target. 118 \param[in] in value to set. 119 */ 120 void FqSet(FqElem* result, uint32_t in); 121 122 /// Test if two elements in Fq are equal 123 /*! 124 \param[in] left The first operand to be tested. 125 \param[in] right The second operand to be tested. 126 \returns A value different from zero (i.e., true) if indeed 127 the values are equal. Zero (i.e., false) otherwise. 128 */ 129 int FqEq(FqElem const* left, FqElem const* right); 130 131 /// Conditionally Set an element's value to one of two values. 132 /*! 133 \param[out] result target. 134 \param[in] true_val value to set if condition is true. 135 \param[in] false_val value to set if condition is false. 136 \param[in] truth_val value of condition. 137 */ 138 void FqCondSet(FqElem* result, FqElem const* true_val, FqElem const* false_val, 139 int truth_val); 140 141 /// Compute the Square root of an element of Fq. 142 /*! 143 \param[out] result the square root of the element. 144 \param[in] in the element to find the square root of. 145 \returns A value different from zero (i.e., true) if the square root 146 exists. Zero (i.e., false) otherwise. 147 */ 148 int FqSqrt(FqElem* result, FqElem const* in); 149 150 /// Generate a random element of Fq. 151 /*! 152 \param[in] result the random value. 153 \param[in] rnd_func Random number generator. 154 \param[in] rnd_param Pass through context data for rnd_func. 155 \returns A value different from zero (i.e., true) if on success. 156 Zero (i.e., false) otherwise. 157 */ 158 int FqRand(FqElem* result, BitSupplier rnd_func, void* rnd_param); 159 160 /// Reinterpret a buffer as an element of Fq 161 /*! 162 \param[out] result target. 163 \param[in] hash buffer to reinterpret. 164 \param[in] len length of hash in bytes. 165 */ 166 void FqFromHash(FqElem* result, unsigned char const* hash, size_t len); 167 168 #endif // EPID_MEMBER_TINY_MATH_FQ_H_ 169