|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-C75726D3-E815-503D-8267-26DA27AD4787" xml:lang="en"><title>Big integers</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
13 <ul> |
|
14 <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> |
|
15 <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> |
|
16 <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> |
|
17 <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> |
|
18 </ul> </li> |
|
19 </ul> |
|
20 <section id="GUID-E105FD3A-2600-504A-842E-E75ABFB6FD31"><title>What does the |
|
21 big integer library do?</title><p>Some types of cryptography require the handling |
|
22 of finite arbitrary length integers. This big integer library attempts to |
|
23 provide support for that requirement. </p><p>It is capable of representing |
|
24 both negative and positive integers with an absolute value of less than 2^(2<sup>37</sup>). </p> </section> |
|
25 <section id="GUID-324AFDAC-314C-5CC5-B322-E908AA6F53C3"><title>How do I use |
|
26 the big integer library?</title> <p>There are four categories of exposed APIs: </p> <ol id="GUID-93981CBD-4B6D-5E95-BD02-44492535C517"> |
|
27 <li id="GUID-3374E318-C0C5-5E7D-92D4-0F541F0F6B61"><p>Creation of new integers |
|
28 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> |
|
29 <li id="GUID-808268B2-FF70-522B-92BD-5B5EA67DA61B"><p>Creation of new integers |
|
30 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> |
|
31 <li id="GUID-3F7FD594-479E-5631-87DE-95D0AC843A0C"><p>Exporting of previously |
|
32 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> |
|
33 <li id="GUID-7D5C5166-15D1-5219-B085-E5D5513E50CE"><p>Querying attributes |
|
34 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> |
|
35 </ol> <p>The following code demonstrates how to create an <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> from |
|
36 a bit string representation of a big integer. </p> <codeblock id="GUID-A496A62E-0912-5241-871B-073270AA72E0" xml:space="preserve"> |
|
37 //This creates an RInteger from the following binary hexadecimal (base 16) |
|
38 //descriptor. Note that the number is written overall in big endian (most |
|
39 //significant digit is first, least significant digit (ones digit) is last). |
|
40 //P.S. The hexadecimal binary descriptor below is the base 16 representation |
|
41 //of the base 10 number 123456789012345678901234567890. |
|
42 RInteger integer = RInteger::NewL(_L8("18EE90FF6C373E0EE4E3F0AD2")); |
|
43 CleanupStack::PushL(integer); |
|
44 |
|
45 //This next line converts the number stored by an RInteger into a binary, big |
|
46 //endian, hexadecimal descriptor. |
|
47 HBufC8* descriptor = integer.BufferLC(); |
|
48 CleanupStack::Pop(descriptor); |
|
49 CleanupStack::PopAndDestroy(integer); |
|
50 //descriptor is the same as the original _L8 input value now. |
|
51 </codeblock> <p>For more information on integers, including important memory |
|
52 management information and additional creation overloads, see <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> in |
|
53 the Cryptography API Reference material. </p> </section> |
|
54 <section id="GUID-268F2081-4385-5D43-8ADA-4F17BAA4B0BC"><title>Base classes |
|
55 and their derived classes</title> <p>The diagram below shows the main classes |
|
56 used in bigint and which are implemented in <filepath>cryptography.dll</filepath>. |
|
57 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 |
|
58 Reference material. </p> <fig id="GUID-45174FC0-A4B0-572E-801F-EC6CD5A96127"> |
|
59 <title>The inheritance diagram above shows the <codeph>TInteger</codeph> and <codeph>RInteger</codeph> classes.</title> |
|
60 <image href="GUID-598140D3-6C92-5D8E-B204-C7197C6E404D_d0e384680_href.png" placement="inline"/> |
|
61 </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 |
|
62 a <codeph>TInteger</codeph> derived class allowing the construction of variable |
|
63 length big integers. </p><p>This class follows standard <codeph>R</codeph> class |
|
64 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> |
|
65 <li id="GUID-07C1504B-0A75-5FAF-BCFC-11E0C6977DD4"><p>You can construct an |
|
66 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"> |
|
67 RInteger integer; |
|
68 </codeblock> <p>This is a constructed, but uninitialized integer. It does |
|
69 not own memory and no operations can be performed on it. It is useful, mostly, |
|
70 to assign the result of another integer operation to. <codeph>Push</codeph> ing |
|
71 and then <codeph>PopAndDestroy</codeph> ing an empty <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> works, |
|
72 although it's not needed. </p> </li> |
|
73 <li id="GUID-CB62909E-910A-5C29-81E1-6DFD17081B6D"><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s |
|
74 can be bitwised copied (the default assignment operator and copy constructor |
|
75 are valid), but you need to be careful you don't lose your original memory |
|
76 in the process. You should only use the assignment operator on a newly declared |
|
77 integer. To set an <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> to another value without losing |
|
78 memory see <codeph>TInteger::Set()</codeph>. </p> <codeblock id="GUID-ECCE21CF-BCD0-57D3-AF54-766B32939D2C" xml:space="preserve"> |
|
79 RInteger a = anotherInteger; // OK -- you now have two integers that point to the same memory |
|
80 RInteger b = RInteger::NewL(aDesc); // OK |
|
81 b = a; // NOT OK, b's original memory has been lost |
|
82 </codeblock> </li> |
|
83 <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 |
|
84 by value from a <codeph>TInteger</codeph> function. </p> <codeblock id="GUID-D03786AD-EF19-59B6-B8A9-F91020D14754" xml:space="preserve"> |
|
85 RInteger integer = a.MinusL(b); // We now own integer |
|
86 CleanupStack::PushL(integer); |
|
87 </codeblock> </li> |
|
88 <li id="GUID-076C4F7F-8EC7-5E5E-833C-DD3E32996DCE"><p>You must call <codeph>Close()</codeph> on |
|
89 all <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s that own memory before they go out of scope. |
|
90 (The cleanup stack can do this for you as well, see further bullet points |
|
91 below). </p> <codeblock id="GUID-B018E759-4201-53D2-AA08-04B6F6ABAD04" xml:space="preserve"> |
|
92 void foo(void) |
|
93 { |
|
94 RInteger integer = a.TimesL(TInteger::Two); |
|
95 //< all sorts of non-leaving code here > |
|
96 integer.Close(); |
|
97 } |
|
98 </codeblock> </li> |
|
99 <li id="GUID-0C2577CE-0336-553F-8D7C-9F731BECDDC5"><p> <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> has |
|
100 a operator <codeph>TCleanupItem()</codeph> cast function that allows you to |
|
101 call <codeph>CleanupStack::PushL(RInteger&)</codeph>. Use this in preference |
|
102 to <codeph>CleanupClosePushL(RInteger&)</codeph>, which although it does |
|
103 the same thing, generates more code. </p> <codeblock id="GUID-EFAD6082-D6BB-56C5-91AA-E94C2EAF419B" xml:space="preserve"> |
|
104 RInteger integer = a.ModularExponentiateL(b, p); |
|
105 CleanupStack::PushL(integer); |
|
106 //< all sorts of leaving code here > |
|
107 CleanupStack::PopAndDestroy(&integer); |
|
108 </codeblock> </li> |
|
109 <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>. |
|
110 After calling this, two <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s have a pointer to the |
|
111 same heap-based integer. Calling <codeph>Close()</codeph> on one, either explicitly |
|
112 or through the cleanup stack, leaves a dangling pointer to the other. You |
|
113 probably want to use code similar to the following: </p> <codeblock id="GUID-7A7EE1D4-8931-5A43-8470-2C7C3E9E83F2" xml:space="preserve"> |
|
114 RInteger first = RInteger::NewL(298728); |
|
115 CleanupStack::PushL(first); |
|
116 //< all sorts of leaving code here > |
|
117 RInteger second.Set(first); |
|
118 CleanupStack::Pop(first); |
|
119 CleanupStack::PushL(second); |
|
120 </codeblock> </li> |
|
121 </ul> </section> |
|
122 </conbody></concept> |