go to > bobcat(7) > RAND_seed(3) |

Homepage > Man Pages > Name > F

## NAME

FBB::BigInt - Arithmetic on Integers of Unlimited SizeSYNOPSIS

#include <bobcat/bigint>Linking option:-lssl -lbobcat## DESCRIPTION

This class is defined as a wrapper class around theopenSSL BNseries of functions, offering members to perform arithmetic on integral values of unlimited sizes. Members are offered to generate primes and to perform all kinds of common arithmetic operations onBigIntobjects. Also, conversions to characters and standard numerical value types are offered. Below, the phrasethe objectmay also refer to the object's value. The context in which this occurs will make clear that the object's value rather than the object as-is is referred to. Various constructors acceptBIGNUMarguments. TypeBIGNUMis the type containing an integer of unlimited precision as defined by OpenSSL. Signs ofBigIntare handled in a special way. Whether aBigIntis negative or positive is determined by its sign-flag, and not by a sign bit as is the case withinttyped values. SinceBigIntvalues have unlimited precision shifting values to the left won't change their signs. Operators return either a reference to the current (modified) object or return aBigInt constobject containing the computed value. The rule followed here was to implement the operators analogously to the way the operators work oninttype values and variables. E.g.,operator+()returns aBigInt constvalue whereasoperator+=()returns aBigInt &reference. All members modifying their objects return a reference to the current (modified) object. All members not modifying the current object return aBigInt constobject. If both members exists performing the same functionality the name of the member returning aBigInt constobject ends in ac(const) (e.g.,addModandaddModc. Almost all operators, members and constructors (except for the default constructor) throwErrnoexceptions on failure.## INHERITS FROM

-## ENUMERATIONS

MsbThis (most significant bit) enumeration is used when generating a cryptographically strong random number. Its values are: oMSB_UNKNOWN: The most significant bit may be 0 or 1. oMSB_IS_ONE: The most significant bit is guaranteed to be 1. oTOP_TWO_BITS_ONE: The two most significant bits are guaranteed to be 1, resulting in a product of two values each containingnBitshaving2 * nBitsbits.LsbThis (least significant bit) enumeration is used when generating random numbers, ensuring that the resulting value is either odd or even. oEVEN: The random value will be an even value; oODD: The random value will be an odd value.## CONSTRUCTORS

oBigInt(): The default constructor initializes aBigIntvalue to 0. oBigInt(BIGNUM const &value): This constructor initializes aBigIntfrom aBIGNUM. oBigInt(BIGNUM const *value): This constructor initializes aBigIntfrom a pointer to aconst BIGNUM. oBigInt(Type value): This constructor is defined as a member template. Any type that can be converted using a static cast to anunsigned longcan be used as argument to this constructor. Promotion is allowed, so in many situations whereBigInts are expected a plain numerical value can be used as well. The standard copy constructor is available.## MEMBER FUNCTIONS

oBigInt &addMod(BigInt const &rhs, BigInt const &mod):Rhsis added (modulomod) to the current object. oBigInt const addModc(BigInt const &rhs, BigInt const &mod): The sum (modulomod) of the current object andrhsis returned. oBIGNUM const &bignum() const: A reference to theBIGNUMvalue maintained by the currentBigIntobject is returned. ochar *bigEndian() const: The value represented by the current object is stored in a series ofchartyped values in big-endian order. If a value consists of 5chars the eight most significant bits will be stored in thecharhaving index value 0, the eight least significant bits will be stored in thecharhaving index value 4. When needed simply swapchar[i]withchar[j](i = 0 .. nBytes/2, j = nBytes-1 .. nBytes/2) to convert to little-endian order. The return value consists of a series ofsizeInBytes()(see below) dynamically allocatedcharvalues. The caller ofbigEndianowns the allocated memory and should eventually delete it again usingdelete[]. Note that the current object'ssigncannot be inferred from the return value. oBigInt &clearBit(size_t index): The current object's bit at index positionindexis cleared. oBigInt const clearBit(size_t index) const: A copy of the current object having its bit at index positionindexcleared. oBigInt &div(BigInt *remainder, BigInt const &rhs): The current object is divided byrhs. The division's remainder is returned in*remainder. oBigInt const divc(BigInt *remainder, BigInt const &rhs) const: The quotient of the current object andrhsis returned. The division's remainder is returned in*remainder. oint compare(BigInt const &rsh) const: Using signed values, if the current object is smaller thanrhs-1 is returned; if they are equal 0 is returned; if the current object is larger thanths1 is returned (see alsouCompare). oBigInt &exp(BigInt const &exponent): The current object is raised to the powerexponent. oBigInt const expc(BigInt const &exponent) const: The current object raised to the powerexponentis returned. oBigInt &expMod(BigInt const &exponent, BigInt const &mod): The current object is raised to the powerexponentmodulomod. oBigInt const expModc(BigInt const &exponent, BigInt const &mod) const: The current object raised to the powerexponentmodulomodis returned. oBigInt &gcd(BigInt const &rhs): The greatest common divisor (gcd) of the current object andrhsis assigned to the current object. To compute the least common multiple (lcm) the following relationship can be used: lcm(a, b) = a * b / a.gcd(b) oBigInt const gcdc(BigInt const &rhs) const: The greatest common divisor (gcd) of the current object andrhsis returned. To compute the least common multiple (lcm) the following relationship can be used: lcm(a, b) = a * b / a.gcd(b) obool hasBit(size_t index):Trueis returned if the bit at index positionindexhas been set,falseotherwise. oBigInt &inverseMod(BigInt const &mod): The inverse of the current object modulomodis assigned to the current object. This is the valueretfor which the following expression holds true: (*this * ret) % mod = 1 oBigInt const inverseModc(BigInt const &mod) const: This inverse of the current object modulomodis returned. obool isNegative() const: Returnstrueif the current object contains a negative value. obool isOdd() const: Returnstrueif the current object is an odd value. obool isOne() const: Returnstrueif the current object equals one (1). oBigInt &isqrt(): The current object's integer square root value is assigned to the current object. The integer square root of a valuexis the smallest integral value whose square does not exceedx. E.g.,isqrt(17) == 4. oBigInt const isqrtc() const: The integer square root of the current object is returned. obool isZero() const: Returnstrueif the current object equals zero (0). oBigInt &lshift(): The current object's bits are shifted one bit to the left. The object's sign remains unaltered. oBigInt const lshiftc(): The current object's bits shifted one bit to the left are returned. The object's sign will be equal to the current object's sign. oBigInt &lshift(size_t nBits): The current object's bits are shiftednBitsto the left. The object's sign remains unaltered. oBigInt const lshiftc(size_t nBits) const: The current object's bits shiftednBitsbit to the left are returned. The object's sign will be equal to the current object's sign. oBigInt &maskBits(size_t lowerNBits): The current object'slowerNBitslower bits are kept, its higher order bits are cleared. The object's sign is not affected. oBigInt const maskBitsc(size_t lowerNBits) const: A copy of the current object is returned having all but itslowerNBitslower bits cleared. The sign of the returned object will be equal to the current object's sign. oBigInt &mulMod(BigInt const &rhs, BigInt const &mod): The current object is multiplied (modulomod) byrhs. oBigInt const mulModc(BigInt const &rhs, BigInt const &mod) const: The current object multiplied (modulomod) byrhsis returned. oBigInt &negate(): The current object's value is negated (i.e., the value changes its sign). oBigInt const negatec() const: The negated value of the current object is returned. oBigInt &rshift(): The current object's bits are shifted one bit to the right. The object's sign remains unaltered. oBigInt const rshiftc(): The current object's bits shifted one bit to the right are returned. The object's sign will be equal to the current object's sign. oBigInt &rshift(size_t nBits): The current object's bits are shiftednBitsto the right. The object's sign remains unaltered. oBigInt const rshiftc(size_t nBits) const: The current object's bits shiftednBitsbit to the right are returned. The object's sign will be equal to the current object's sign. oBigInt &setBit(size_t index): The bit at index positionindexis set. oBigInt const setBitc(size_t index) const: A copy of the current object is returned having its bit at index positionindexset. oBigInt &setBit(size_t index, bool value): The bit at index positionindexis set tovalue. oBigInt const setBitc(size_t index, bool value) const: A copy of the current object is returned having its bit at index positionindexset tovalue. oBigInt &setNegative(bool negative): The current object's sign will be set to negative if the function's argument istrue, it will be set to positive if the function's argument isfalse. oBigInt const setNegativec(bool negative) const: A copy of the current object is return having a negative sign if the function's argument istrueand a positive sign if the function's argument isfalse. osize_t size() const: The number of bytes required to store the currentBIGNUMvalue is returned. osize_t sizeInBits() const: The number of bits required to represent the currentBIGNUMvalue is returned. If you want to know the key size of RSA, DH or DSA keys functions likeRSA_size(), DH_size(),orDSA_size()should be used. oBigInt &sqr(): The current object's value is squared. oBigInt const sqrc() const: The square of the current object is returned. oBigInt &sqrMod(BigInt const &mod) const: The current object's value is squared modulomod. oBigInt const sqrModc(BigInt const &mod) const: The square (modulomod) of the current object is returned. oBigInt &subMod(BigInt const &rhs, BigInt const &mod):Rhsis subtracted modulomodfrom the current object. oBigInt const subModc(BigInt const &rhs, BigInt const &mod) const: The difference (modulomod) of the current object andrhsis returned. ovoid swap(BigInt &other): The current object swaps its value withother. oBigInt &tildeBits(): All the bits in the bytes of the current object and the sign of the current object are toggled. So, after Bigint b(5); b.tildeBits();bcontains the value -250. Also see the discussion withoperator~()below. oBigInt const tildeBitsc() const: A copy of the current object whose bits are toggled is returned. oBigInt &tildeInt(): The 'tilde' operation is performed on the current object using the standardintsemantics. E.g., ~5 results in -6. Also see the discussion withoperator~()below. oBigInt const tildeIntc() const: A copy of the current object is returned to which the 'tilde' operation has been performed using the standardintsemantics. ounsigned long ulong() const: The absolute value stored in the current object is returned as an unsigned long. If it cannot be represented by an unsigned long it returns0xffffffffL. oint uCompare(BigInt const &rsh) const: Using absolute values, if the current object is smaller thanrhs-1 is returned; if they are equal 0 is returned; if the current object is larger thanths1 is returned (see alsouCompare).OVERLOADED OPERATORS

Except for some operators all operators perform their intuitive operations. Where that isn't completely true an explanatory remark is provided. E.g.,operator*()multiplies twoBigInts, possibly promoting one of the operands;operator*=()multiplies the lhs by the rhsBigInt, possibly promoting the rhs operand. Here are the available operators:Unary operators:oBigInt &operator++(): oBigInt const operator++(int): oBigInt &operator--(): oBigInt const operator--(int): oBigInt const operator-(): oint operator[](size_t idx) const: WithBigInt constobjects it returns the bit-value of the object'sidxth bit as the value 0 or 1. oBigInt::Bit operator[](size_t idx): With non-constBigIntobjects it returns a reference to the bit-value of the object'sidxth bit. When used aslvalueassigning a 0 or non-zero value to the operator's return value will either clear or set the bit. Likewise, the following arithmetic assignment operators may be used: binary or (|=), binary and (&=) or binary xor (^=). When used asrvaluethe value of the object'sidxth bit is returned as aboolvalue. When inseerted into astd::ostreamthe bit's value is displayed as 0 or 1. oBigInt const operator~(): This operator isnotimplemented as it cannot be implemented so that it matches the actions of this operator when applied tointtype values. When used onintvalues this operator toggles all theint's bits. E.g., ~5 represents -6, and ~-6 again equals five. The -6 is the result of the sign bit ofintvalues. The obvious implementation ofBigInt::operator~()is to toggle all the value's bits and to toggle its sign bit. For 5 this would result in -250: 5, being 101 (binary), fits in one byte, so ~5 becomes 11111010 (binary), which is 250. Its sign must be reversed as well, so it becomes -250. This clearly differs from the value represented by theintconstant ~5: when constructingBigInt(~5), the value -6 is obtained. It is possible to change the implementation. E.g., after Bigint b(5); b = ~b;~bcould be implemented so that it results in the value -6. But this too leads to unexpected results. While5 & ~5 == 0, this would no longer hold true forBigIntobjects: Assumingbcontains 5 thenb & ~bwould expand to (binary)101 & (negative)110which equals (binary) 100. Since either implementation produces unexpected resultsBigInt::operator~()was not implemented. Instead two members are offered:tildeBits(), toggling all the bits of all theBigIntbytes and toggling its sign (so Bigint b(5); b.tildeBits(); changesb's value into -250), andtildeInt()changing the object's value into the value that would have been obtained if aBigIntwas a mereint(so Bigint b(5); b.tildeInt(); changesb's value into -6).Binary operators:oBigInt const operator*(BigInt const &lhs, BigInt const &rhs): oBigInt const operator/(BigInt const &lhs, BigInt const &rhs): This operator returns the quotient of thelhsobject divided by therhsobject. The remainder is lost (The memberdivperforms the division and makes the remainder available as well). oBigInt const operator%(BigInt const &lhs, BigInt const &rhs): oBigInt const operator+(BigInt const &lhs, BigInt const &rhs): oBigInt const operator-(BigInt const &lhs, BigInt const &rhs): oBigInt const operator<<(BigInt const &lhs, size_t nBits): See also thelshiftmembers. Iflhsis positive, oBigInt const operator>>=(BigInt const &lhs, size_t nBits): See also thershiftmembers. oBigInt const operator&(BigInt const &lhs, BigInt const &rhs): This operator returns aBigIntvalue consisting of thebit_and-ed bits and sign flags of lhs and rhs operands. Consequently, if one operand is positive, the resulting value will be positive. oBigInt const operator|(BigInt const &lhs, BigInt const &rhs): This operator returns aBigIntvalue consisting of thebit_or-ed bits and sign flags of lhs and rhs operands. Consequently, if either operand is negative, the result will be negative. oBigInt const operator^(BigInt const &lhs, BigInt const &rhs): This operator returns aBigIntvalue consisting of thebit_xor-ed bits and sign flags of lhs and rhs operands. Consequently, if exactly one operand is negative, the result will be negative.(Arithmetic) assignment operator(s):oBigInt &operator=(BigInt const &rhs): oBigInt &operator*=(BigInt const &rhs): oBigInt &operator/=(BigInt const &rhs): This operator assigns the result of the (integer) division of the currentBigIntobject bythsto the current object. The remainder is lost. The memberdivdivides and makes the remainder available as well. oBigInt &operator%=(BigInt const &rhs): oBigInt &operator+=(BigInt const &rhs): oBigInt &operator-=(BigInt const &rhs): oBigInt &operator<<=(size_t nBits): See also thelshiftmembers. oBigInt &operator>>=(size_t nBits): See also thershiftmembers. oBigInt &operator&(BigInt const &rhs): This operatorbit_ands the bits and sign flags of the current object and the rhs operand. oBigInt &operator|(BigInt const &rhs): This operatorbit_ors the bits and sign flags of the current object and the rhs operand. oBigInt &operator^(BigInt const &rhs): This operatorbit_xors the bits and sign flags of the current object and the rhs operand.## STATIC MEMBERS

All members returning aBigIntcomputed from a set of arguments and not requiring an existingBigIntobject are defined as static members. oBigInt const fromText(std::string text, int mode = 0): This member converts a textual representation of a number to aBigIntvalue. Conversion continues until the end oftextor until a character outside of an expected range is encountered. The expected range may be preset by specifyingmodeasios::dec, ios::oct,orios::hexor (the default) the expected range is determined byfromTextitself by inspecting the characters intext. By default iftextcontains hexadecimal characters thenfromTextassumes that the number is represented as a hexadecimal value (e.g.,"abc"is converted to the (decimal) value 2748); iftextstarts with 0 and contains only characters in the range 0 until (including) 7 thenfromTextassumes the number is represented as an octal value (e.g.,"01234"is converted to the (decimal) value 668). Otherwise a decimal value is assumed. If the text does not represent a valid numerical value (of the given extraction mode) then aFBB::Errnoexception is thrown (fromText: text does not represent a BigInt value). oBigInt const rand(size_t size, Msb msb = MSB_IS_ONE, Lsb lsb = ODD): This member returns a cryptographically strong pseudo-random number ofsizebits. The most significant bit(s) can be controlled bymsb(by defaultMSB_IS_ONE), the least significant bit can be controlled bylsb(by defaultODD). Before calling this member the random number generator must have been seeded. oBigInt const randRange(BigInt const &max): This member returns a cryptographically strong pseudo-random number in the range0 <= number < max. Before calling this member the random number generator must have been seeded. oBigInt const setBigEndian(std::string const &bytes): Thebytes.length()bytes ofbytesare used to compute aBigIntobject which is returned by this function. The characters inbytesare interpreted as a series of bytes in big-endian order. See also the member functionbigEndian()above. The returnedBigInthas a positive value. oBigInt const prime(size_t nBits, BigInt const *mod = 0, BigInt const *rem = 0, PrimeType primeType = ANY): This member returns a prime number ofbBitsbits. If bothmodandremare non-zero, the condition prime % mod == rem. (E.g., useprime % mod == 1in order to suit a given generator). The parameterprimeTypecan beANY,(prime-1) / 2may or may not be a prime. If it isSAFEthen(prime-1) / 2will be a (so-calledsafe) prime. oBigInt const pseudoRand(size_t size, Msb msb = MSB_IS_ONE, Lsb lsb = ODD): This member returns a potentially predictable pseudo-random number ofsizebits. The most significant bit(s) can be controlled bymsb(by defaultMSB_IS_ONE), the least significant bit can be controlled bylsb(by defaultODD). It can be used for non-cryptographic purposes and for certain purposes in cryptographic protocols, but usually not for key generation. oBigInt const pseudoRandRange(BigInt const &max): This member returns a potentially predictable pseudo-random number in the range0 <= number < max.## FREE FUNCTIONS IN THE FBB NAMESPACE

ostd::ostream &operator<<(ostream &out, BigInt const &value): Insertsvalueinto the providedostream. If thehexmanipulator has been inserted into the stream before inserting theBigIntvalue the value will be displayed as a hexadecimal value (without a leading0x); if theoctmanipulator has been inserted the value will be represented as an octal value (starting with a 0). The value will be displayed as a decimal value if thedecmanipulator is active. If theBigIntvalue is negative its value will be preceded by a minus character. ostd::istream &operator>>(istream &in, BigInt &value): Extractsvaluefrom the providedistream. Depending on the currently set extraction mode (dec, oct,orhex) the matching set of characters will be extracted frominand converted to a number which is stored invalue. Extraction stops at EOF or at the first character outside of the range of characters matching the extraction mode. if no numerical characters were extracted the stream'sfailbitis set. The extracted value may be preceded by a minus character, resulting in an extracted negative value.## EXAMPLE

#include <iostream> #include <bobcat/bigint> using namespace std; using namespace FBB; int main(int argc, char **argv) { BigInt value(BigInt::prime(100)); BigInt mod(BigInt::rand(50)); BigInt inverse(value.inverseModc(mod)); cout << '(' << value << " * " << inverse << ") % " << mod << " = " << ( value * inverse ) % mod << endl; }## FILES

bobcat/bigint- defines the class interface## SEE ALSO

bobcat(7),RAND_seed(3)BUGS

None Reported.## DISTRIBUTION FILES

obobcat_2.18.00-x.dsc: detached signature; obobcat_2.18.00-x.tar.gz: source archive; obobcat_2.18.00-x_i386.changes: change log; olibbobcat1_2.18.00-x_*.deb: debian package holding the libraries; olibbobcat1-dev_2.18.00-x_*.deb: debian package holding the libraries, headers and manual pages; o//sourceforge.net/projects/bobcat: public archive location;## BOBCAT

Bobcat is an acronym of 'Brokken's Own Base Classes And Templates'.## COPYRIGHT

This is free software, distributed under the terms of the GNU General Public License (GPL).## AUTHOR

Frank B. Brokken (f.b.brokken@rug.nl). FBB::BIGINT(3)

Copyright © 2011–2018 by topics-of-interest.com . All rights reserved. Hosted by all-inkl.

Contact · Imprint · Privacy

Page generated in 28.46ms.

dfptutorial.com | www.daelim-forum.com | roboter.name