<?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);
    //&lt; all sorts of non-leaving code here &gt;
    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);
//&lt; all sorts of leaving code here &gt;
CleanupStack::PopAndDestroy(&amp;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);
//&lt; all sorts of leaving code here &gt;
RInteger second.Set(first);
CleanupStack::Pop(first);
CleanupStack::PushL(second);
</codeblock> </li>
</ul> </section>
</conbody></concept>