<?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-GENID-1-12-1-26-1-1-9-1-5-1-11-1" xml:lang="en"><title>Big integers</title><prolog><metadata><keywords/></metadata></prolog><conbody>+
−
<ul>+
−
<li id="GUID-44E43C1D-81C0-566D-AD44-65046947046D-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-1-1"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1/GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-2">What does the big integer library do?</xref>  </p> </li>+
−
<li id="GUID-F28BE30D-0E28-57A0-8302-BBA5BEF9DA2E-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-1-2"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1/GUID-324AFDAC-314C-5CC5-B322-E908AA6F53C3-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3">How do I use the big integer library?</xref>  </p> </li>+
−
<li id="GUID-FEC8841D-52D9-5232-9E56-1E59E2A36DE2-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-1-3"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1/GUID-268F2081-4385-5D43-8ADA-4F17BAA4B0BC-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4">Base classes and their derived classes</xref>  </p> <ul>+
−
<li id="GUID-3EEF522F-49CE-5131-BD57-501582746773-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-1-3-2-1"><p> <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1.dita#GUID-C75726D3-E815-503D-8267-26DA27AD4787-GENID-1-12-1-26-1-1-9-1-5-1-11-1/GUID-FE43C9B9-7F50-5311-A2AF-7BA9785A68BC-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-4">RInteger class</xref>  </p> </li>+
−
</ul> </li>+
−
</ul>+
−
<section id="GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-2"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3-3">+
−
<li id="GUID-3374E318-C0C5-5E7D-92D4-0F541F0F6B61-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3-3-1"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3-3-2"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3-3-3"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3-3-4"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-3-5" 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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-3">+
−
<title>The inheritance diagram above shows the <codeph>TInteger</codeph> and <codeph>RInteger</codeph> classes.</title>+
−
<image href="GUID-598140D3-6C92-5D8E-B204-C7197C6E404D_d0e598544_href.png" placement="inline"/>+
−
</fig> <p id="GUID-FE43C9B9-7F50-5311-A2AF-7BA9785A68BC-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-4"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-1"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-1-2" 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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-2"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-2-2" 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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-3"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-3-2" 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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-4"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-4-2" 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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-5"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-5-2" 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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-6"><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-GENID-1-12-1-26-1-1-9-1-5-1-11-1-2-4-7-6-2" 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>+
−