Big integers

What does the big integer library do?
How do I use the big integer library?
Base classes and their derived classes
- RInteger class

What does the -big integer library do?

Some types of cryptography require the handling -of finite arbitrary length integers. This big integer library attempts to -provide support for that requirement.

It is capable of representing -both negative and positive integers with an absolute value of less than 2^(2³⁷).

How do I use -the big integer library?

There are four categories of exposed APIs:

Creation of new integers -given some other representation (descriptor, TUint, etc). RInteger::NewL()
Creation of new integers -given some criteria (range, bitcount, prime). RInteger::NewRandomL(), RInteger::NewPrimeL()
Exporting of previously -created integers to descriptors. TInteger::BufferLC()
Querying attributes -about the size of a previously created integer. TInteger::BitCount(), TInteger::ByteCount(), TInteger::WordCount().

The following code demonstrates how to create an RInteger from -a bit string representation of a big integer.

-//This creates an RInteger from the following binary hexadecimal (base 16) -//descriptor. Note that the number is written overall in big endian (most -//significant digit is first, least significant digit (ones digit) is last). -//P.S. The hexadecimal binary descriptor below is the base 16 representation -//of the base 10 number 123456789012345678901234567890. -RInteger integer = RInteger::NewL(_L8("18EE90FF6C373E0EE4E3F0AD2")); -CleanupStack::PushL(integer); - -//This next line converts the number stored by an RInteger into a binary, big -//endian, hexadecimal descriptor. -HBufC8* descriptor = integer.BufferLC(); -CleanupStack::Pop(descriptor); -CleanupStack::PopAndDestroy(integer); -//descriptor is the same as the original _L8 input value now. -

For more information on integers, including important memory -management information and additional creation overloads, see RInteger in -the Cryptography API Reference material.

Base classes -and their derived classes

The diagram below shows the main classes -used in bigint and which are implemented in cryptography.dll. -The color of the boxes indicates the type of Symbian class, that is, M, C, R or T class. For detailed information on each component see the Cryptography API -Reference material.

-The inheritance diagram above shows the <codeph>TInteger</codeph> and <codeph>RInteger</codeph> classes. - -

RInteger class

RInteger is -a TInteger derived class allowing the construction of variable -length big integers.

This class follows standard R class -rules. As a quick refresher, the following rules apply to RInteger s:

You can construct an -empty RInteger.
-RInteger integer; -
This is a constructed, but uninitialized integer. It does -not own memory and no operations can be performed on it. It is useful, mostly, -to assign the result of another integer operation to. Push ing -and then PopAndDestroy ing an empty RInteger works, -although it's not needed.
RInteger s -can be bitwised copied (the default assignment operator and copy constructor -are valid), but you need to be careful you don't lose your original memory -in the process. You should only use the assignment operator on a newly declared -integer. To set an RInteger to another value without losing -memory see TInteger::Set().
-RInteger a = anotherInteger; // OK -- you now have two integers that point to the same memory -RInteger b = RInteger::NewL(aDesc); // OK -b = a; // NOT OK, b's original memory has been lost -
You own any RInteger returned -by value from a TInteger function.
-RInteger integer = a.MinusL(b); // We now own integer -CleanupStack::PushL(integer); -
You must call Close() on -all RInteger s that own memory before they go out of scope. -(The cleanup stack can do this for you as well, see further bullet points -below).
-void foo(void) - { - RInteger integer = a.TimesL(TInteger::Two); - //< all sorts of non-leaving code here > - integer.Close(); - } -
RInteger has -a operator TCleanupItem() cast function that allows you to -call CleanupStack::PushL(RInteger&). Use this in preference -to CleanupClosePushL(RInteger&), which although it does -the same thing, generates more code.
-RInteger integer = a.ModularExponentiateL(b, p); -CleanupStack::PushL(integer); -//< all sorts of leaving code here > -CleanupStack::PopAndDestroy(&integer); -
Be careful calling TInteger::Set(). -After calling this, two RInteger s have a pointer to the -same heap-based integer. Calling Close() on one, either explicitly -or through the cleanup stack, leaves a dangling pointer to the other. You -probably want to use code similar to the following:
-RInteger first = RInteger::NewL(298728); -CleanupStack::PushL(first); -//< all sorts of leaving code here > -RInteger second.Set(first); -CleanupStack::Pop(first); -CleanupStack::PushL(second); -