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 Big number interface. 20 */ 21 22 #ifndef EPID_COMMON_MATH_BIGNUM_H_ 23 #define EPID_COMMON_MATH_BIGNUM_H_ 24 25 #include <stddef.h> 26 #include <stdint.h> 27 #include "epid/common/errors.h" 28 #include "epid/common/stdtypes.h" 29 #include "epid/common/types.h" 30 31 /// Big number operations 32 /*! 33 \defgroup BigNumPrimitives bignum 34 This module provides an API for working with large numbers. BigNums 35 represent non-negative integers. 36 37 Each BigNum variable represents a number of a byte-size set when the variable 38 was created. BigNum variables cannot be re-sized after they are created. 39 40 41 \ingroup EpidMath 42 @{ 43 */ 44 45 /// Internal representation of large numbers 46 typedef struct BigNum BigNum; 47 48 /// Constructs a new BigNum. 49 /*! 50 Allocates memory and creates a new BigNum. 51 52 Use DeleteBigNum() to free memory. 53 54 \param[in] data_size_bytes 55 The size in bytes of the new number. 56 \param[out] bignum 57 The BigNum. 58 59 \returns ::EpidStatus 60 61 \see DeleteBigNum 62 */ 63 EpidStatus NewBigNum(size_t data_size_bytes, BigNum** bignum); 64 65 /// Deletes a previously allocated BigNum. 66 /*! 67 Frees memory pointed to by bignum. Nulls the pointer. 68 69 \param[in] bignum 70 The BigNum. Can be NULL. 71 72 \see NewBigNum 73 */ 74 void DeleteBigNum(BigNum** bignum); 75 76 /// Deserializes a BigNum from a string. 77 /*! 78 \param[in] bn_str 79 The serialized value. 80 \param[in] strlen 81 The size of bn_str in bytes. 82 \param[out] bn 83 The target BigNum. 84 85 \returns ::EpidStatus 86 */ 87 EpidStatus ReadBigNum(ConstOctStr bn_str, size_t strlen, BigNum* bn); 88 89 /// Serializes a BigNum to a string. 90 /*! 91 \param[in] bn 92 The BigNum to be serialized. 93 \param[in] strlen 94 The size of bn_str in bytes. 95 \param[out] bn_str 96 The target string. 97 98 \returns ::EpidStatus 99 */ 100 EpidStatus WriteBigNum(BigNum const* bn, size_t strlen, OctStr bn_str); 101 102 /// Adds two BigNum values. 103 /*! 104 \param[in] a 105 The first operand to be added. 106 \param[in] b 107 The second operand to be added. 108 \param[out] r 109 The result of adding a and b. 110 111 \returns ::EpidStatus 112 */ 113 EpidStatus BigNumAdd(BigNum const* a, BigNum const* b, BigNum* r); 114 115 /// Subtracts two BigNum values. 116 /*! 117 \param[in] a 118 The first operand to use in subtraction. 119 \param[in] b 120 The second operand to use in subtraction. 121 \param[out] r 122 The result of subtracting a and b. 123 124 \returns ::EpidStatus 125 */ 126 EpidStatus BigNumSub(BigNum const* a, BigNum const* b, BigNum* r); 127 128 /// Multiplies two BigNum values. 129 /*! 130 \param[in] a 131 The first operand to be multiplied. 132 \param[in] b 133 The second operand to be multiplied. 134 \param[out] r 135 The result of multiplying a and b. 136 137 \returns ::EpidStatus 138 */ 139 EpidStatus BigNumMul(BigNum const* a, BigNum const* b, BigNum* r); 140 141 /// Divides two BigNum values. 142 /*! 143 \note Only needed for Intel(R) EPID 1.1 verification. 144 145 \param[in] a 146 Dividend parameter. 147 \param[in] b 148 Divisor parameter. 149 \param[out] q 150 Quotient of result. 151 \param[out] r 152 Remainder of result. 153 154 \returns ::EpidStatus 155 */ 156 EpidStatus BigNumDiv(BigNum const* a, BigNum const* b, BigNum* q, BigNum* r); 157 158 /// Computes modular reduction for BigNum value by specified modulus. 159 /*! 160 \param[in] a 161 The BigNum value. 162 \param[in] b 163 The modulus. 164 \param[out] r 165 Modular reduction result. 166 167 \returns ::EpidStatus 168 */ 169 EpidStatus BigNumMod(BigNum const* a, BigNum const* b, BigNum* r); 170 171 /// Checks if a BigNum is even. 172 /*! 173 \param[in] a 174 The BigNum to check. 175 \param[out] is_even 176 The result of the check. 177 178 \returns ::EpidStatus 179 */ 180 EpidStatus BigNumIsEven(BigNum const* a, bool* is_even); 181 182 /// Checks if a BigNum is zero. 183 /*! 184 \param[in] a 185 The BigNum to check. 186 \param[out] is_zero 187 The result of the check. 188 189 \returns ::EpidStatus 190 */ 191 EpidStatus BigNumIsZero(BigNum const* a, bool* is_zero); 192 193 /// Raises 2 to the given power 194 /*! 195 \param[in] n 196 The power. 197 \param[out] r 198 The result of 2^n. 199 200 \returns ::EpidStatus 201 */ 202 EpidStatus BigNumPow2N(unsigned int n, BigNum* r); 203 204 /*! 205 @} 206 */ 207 #endif // EPID_COMMON_MATH_BIGNUM_H_ 208