<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-C75726D3-E815-503D-8267-26DA27AD4787" xml:lang="en"><title>Big integers</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-44E43C1D-81C0-566D-AD44-65046947046D"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31">What does the big integer library do?</xref>  </p> </li>

<li id="GUID-F28BE30D-0E28-57A0-8302-BBA5BEF9DA2E"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-324AFDAC-314C-5CC5-B322-E908AA6F53C3">How do I use the big integer library?</xref>  </p> </li>

<li id="GUID-FEC8841D-52D9-5232-9E56-1E59E2A36DE2"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-268F2081-4385-5D43-8ADA-4F17BAA4B0BC">Base classes and their derived classes</xref>  </p> <ul>

<li id="GUID-3EEF522F-49CE-5131-BD57-501582746773"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787/GUID-FE43C9B9-7F50-5311-A2AF-7BA9785A68BC">RInteger class</xref>  </p> </li>

</ul> </li>

</ul>

<section id="GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31"><title>What does the

big integer library do?</title><p>Some types of cryptography require the handling

of finite arbitrary length integers. This big integer library attempts to

provide support for that requirement. </p><p>It is capable of representing

both negative and positive integers with an absolute value of less than 2^(2<sup>37</sup>). </p> </section>

<section id="GUID-324AFDAC-314C-5CC5-B322-E908AA6F53C3"><title>How do I use

the big integer library?</title> <p>There are four categories of exposed APIs: </p> <ol id="GUID-93981CBD-4B6D-5E95-BD02-44492535C517">

<li id="GUID-3374E318-C0C5-5E7D-92D4-0F541F0F6B61"><p>Creation of new integers

given some other representation (descriptor, TUint, etc). <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita#GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91/GUID-B5E4DBDC-2C7D-30BD-A3D3-8ADE6265CFD2"><apiname>RInteger::NewL()</apiname></xref>  </p> </li>

<li id="GUID-808268B2-FF70-522B-92BD-5B5EA67DA61B"><p>Creation of new integers

given some criteria (range, bitcount, prime). <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita#GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91/GUID-3F59160C-AE87-32A1-8138-C28F977C7607"><apiname>RInteger::NewRandomL()</apiname></xref>, <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita#GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91/GUID-612D2DC1-69D5-3AAE-83AE-6DA5D9983072"><apiname>RInteger::NewPrimeL()</apiname></xref> </p> </li>

<li id="GUID-3F7FD594-479E-5631-87DE-95D0AC843A0C"><p>Exporting of previously

created integers to descriptors. <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-2E9955F7-9219-37B0-84EA-62A3F3327EE8"><apiname>TInteger::BufferLC()</apiname></xref>  </p> </li>

<li id="GUID-7D5C5166-15D1-5219-B085-E5D5513E50CE"><p>Querying attributes

about the size of a previously created integer. <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-F990DD4D-0886-3BF6-B9EE-D48E086D8C78"><apiname>TInteger::BitCount()</apiname></xref>, <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-11AB504D-2919-3F39-A0B6-EA79B498074B"><apiname>TInteger::ByteCount()</apiname></xref>, <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-99874A2D-37D5-3A05-8275-351E29972FA8"><apiname>TInteger::WordCount()</apiname></xref>. </p> </li>

</ol> <p>The following code demonstrates how to create an <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> from

a bit string representation of a big integer. </p> <codeblock id="GUID-A496A62E-0912-5241-871B-073270AA72E0" xml:space="preserve">

//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.

</codeblock> <p>For more information on integers, including important memory

management information and additional creation overloads, see <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> in

the Cryptography API Reference material. </p> </section>

<section id="GUID-268F2081-4385-5D43-8ADA-4F17BAA4B0BC"><title>Base classes

and their derived classes</title> <p>The diagram below shows the main classes

used in bigint and which are implemented in <filepath>cryptography.dll</filepath>.

The color of the boxes indicates the type of Symbian class, that is, <codeph>M</codeph>, <codeph>C</codeph>, <codeph>R</codeph> or <codeph>T</codeph> class. For detailed information on each component see the Cryptography API

Reference material. </p> <fig id="GUID-45174FC0-A4B0-572E-801F-EC6CD5A96127">

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

<image href="GUID-598140D3-6C92-5D8E-B204-C7197C6E404D_d0e384680_href.png" placement="inline"/>

</fig> <p id="GUID-FE43C9B9-7F50-5311-A2AF-7BA9785A68BC"><b>RInteger class</b> </p><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> is

a <codeph>TInteger</codeph> derived class allowing the construction of variable

length big integers. </p><p>This class follows standard <codeph>R</codeph> class

rules. As a quick refresher, the following rules apply to <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s: </p><ul>

<li id="GUID-07C1504B-0A75-5FAF-BCFC-11E0C6977DD4"><p>You can construct an

empty <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref>. </p> <codeblock id="GUID-1A9CA02D-E0AA-508D-A870-4572FF3FD4A4" xml:space="preserve">

RInteger integer;

</codeblock> <p>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. <codeph>Push</codeph> ing

and then <codeph>PopAndDestroy</codeph> ing an empty <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> works,

although it's not needed. </p> </li>

<li id="GUID-CB62909E-910A-5C29-81E1-6DFD17081B6D"><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> 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 <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> to another value without losing

memory see <codeph>TInteger::Set()</codeph>. </p> <codeblock id="GUID-ECCE21CF-BCD0-57D3-AF54-766B32939D2C" xml:space="preserve">

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

</codeblock> </li>

<li id="GUID-D6F49AA0-5C91-5054-A59A-C01757D53AD9"><p>You own any <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> returned

by value from a <codeph>TInteger</codeph> function. </p> <codeblock id="GUID-D03786AD-EF19-59B6-B8A9-F91020D14754" xml:space="preserve">

RInteger integer = a.MinusL(b); // We now own integer

CleanupStack::PushL(integer); 

</codeblock> </li>

<li id="GUID-076C4F7F-8EC7-5E5E-833C-DD3E32996DCE"><p>You must call <codeph>Close()</codeph> on

all <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> 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). </p> <codeblock id="GUID-B018E759-4201-53D2-AA08-04B6F6ABAD04" xml:space="preserve">

void foo(void)

    {

    RInteger integer = a.TimesL(TInteger::Two);

    //< all sorts of non-leaving code here >

    integer.Close();

    }

</codeblock> </li>

<li id="GUID-0C2577CE-0336-553F-8D7C-9F731BECDDC5"><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> has

a operator <codeph>TCleanupItem()</codeph> cast function that allows you to

call <codeph>CleanupStack::PushL(RInteger&amp;)</codeph>. Use this in preference

to <codeph>CleanupClosePushL(RInteger&amp;)</codeph>, which although it does

the same thing, generates more code. </p> <codeblock id="GUID-EFAD6082-D6BB-56C5-91AA-E94C2EAF419B" xml:space="preserve">

RInteger integer = a.ModularExponentiateL(b, p);

CleanupStack::PushL(integer);

//< all sorts of leaving code here >

CleanupStack::PopAndDestroy(&integer);

</codeblock> </li>

<li id="GUID-6FF78282-6B29-5094-8D6B-C2D0FCDFC9E7"><p>Be careful calling <xref href="GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16.dita#GUID-E3D3C429-EA8C-34C1-9D1D-9062BC3D4F16/GUID-F2E2C416-D2F2-31C1-942B-256F74A4075C"><apiname>TInteger::Set()</apiname></xref>.

After calling this, two <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s have a pointer to the

same heap-based integer. Calling <codeph>Close()</codeph> 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: </p> <codeblock id="GUID-7A7EE1D4-8931-5A43-8470-2C7C3E9E83F2" xml:space="preserve">

RInteger first = RInteger::NewL(298728);

CleanupStack::PushL(first);

//< all sorts of leaving code here >

RInteger second.Set(first);

CleanupStack::Pop(first);

CleanupStack::PushL(second);

</codeblock> </li>

</ul> </section>

</conbody></concept>