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-3FB8AC96-209B-5B1E-8139-BA2D858CBF2F" xml:lang="en"><title>CryptoSPI |
|
13 Overview (weak build)</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section><title>Purpose</title> <p>This is an overview of the weak CryptoSPI |
|
15 APIs. An overview and other documents for the strong CryptoSPI APIs are available |
|
16 in the Security Supplement, which is delivered to device creators with the |
|
17 CBR. </p> </section> |
|
18 <section><title>Introduction</title> <p>CryptoSPI (<filepath>cryptospi.dll</filepath>) |
|
19 is a framework for implementing cryptographic algorithms, hash algorithms |
|
20 and random number generation. It allows alternative implementations to be |
|
21 added by Symbian platform device creators as plug-in DLLs. </p> <p><b>Weak |
|
22 and strong builds</b> </p> <p>The cryptography APIs are subject to export |
|
23 control regulations. The export of cryptography refers to the transfer from |
|
24 one country to another of technology related to cryptography. Export control |
|
25 regulations are for national security considerations. </p> <p>Export control |
|
26 applies to key sizes that are greater than a size specified by the UK Government. |
|
27 Currently, symmetric algorithms with keys greater than 56 bits and asymmetric |
|
28 algorithms with keys greater than 512 bits are export controlled. To comply |
|
29 with government export control rules, the Cryptography library is delivered |
|
30 in two builds: </p> <ul> |
|
31 <li id="GUID-B6D2DA99-B26C-563C-AB89-12B55BEA3F86"><p>A weak build </p> <p>The |
|
32 weak build (weak_cryptography.dll) includes cryptography algorithms that are |
|
33 not export controlled. The weak build rejects requests to apply an encryption |
|
34 scheme with key sizes greater than 56 bits for symmetric algorithms and 512 |
|
35 bits for asymmetric algorithms. </p> </li> |
|
36 <li id="GUID-8C455A29-794A-50F4-8503-FCFBF55A731B"><p>A strong build </p> <p>The |
|
37 strong build (strong_cryptography.dll) includes cryptography algorithms that |
|
38 are export controlled. </p> </li> |
|
39 </ul> <p> <b> Note:</b> The API guide and other documentation for cryptography |
|
40 is broken up in the same way as the cryptography library. This document provides |
|
41 information on the weak build. It also gives a brief summary of the algorithms |
|
42 provided in the strong build. The strong cryptography API guide and other |
|
43 documentation is not available from the Symbian Developer Library. It is delivered |
|
44 to device creators with the CBR. </p> </section> |
|
45 <section><title>Architectural relationships</title> <p>Before the introduction |
|
46 of CryptoSPI, features such as cryptographic algorithms, hash algorithms and |
|
47 random number generation were provided by the Symbian platform in <filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>. </p> <p> <filepath>softwarecrypto.dll</filepath> is |
|
48 a plug-in module (implemented in the Symbian platform) that provides software-based |
|
49 implementations of all the cryptographic algorithms that were previously implemented |
|
50 by the legacy components (<filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>). |
|
51 The legacy APIs have been re-implemented internally to use the new framework |
|
52 via shim classes. <filepath>hardwarecrypto.dll</filepath> is an arbitrary |
|
53 name used in the diagram to represent a plug-in module provided by device |
|
54 creators. The plug-ins and <filepath>cryptospi.dll</filepath> have a dependency |
|
55 on <filepath>cryptography.dll</filepath> because it implements big integers. </p> <fig id="GUID-F3B5470E-25D5-5BDD-8F47-480D39C4CDB5"> |
|
56 <title> CryptoSPI dependencies </title> |
|
57 <image href="GUID-708FC2C8-19BB-5EFC-A8CD-B0E9E96A5409_d0e387120_href.png" placement="inline"/> |
|
58 </fig> </section> |
|
59 <section><title>API summary</title> <p>The <codeph>CryptoSpi</codeph> namespace |
|
60 is defined for all CryptoSPI classes to differentiate them from the legacy |
|
61 APIs with the same names. </p> <p><b>CryptoSPI scope</b> </p><p>CryptoSPI |
|
62 provides equivalent implementations of all algorithms supported by the legacy |
|
63 APIs, including hashing and random number generation. The following algorithms |
|
64 are implemented in <filepath>softwarecrypto.dll</filepath>: </p><p>This |
|
65 section includes summary details of the following (For more information on |
|
66 the strong APIs, see the Security Supplement, which is delivered to device |
|
67 creators with the CBR): </p><ul> |
|
68 <li><p>cryptographic algorithms </p></li> |
|
69 <li><p>hash algorithms </p></li> |
|
70 <li><p>random number generator</p></li> |
|
71 </ul> <p id="GUID-19D541E1-1868-527A-A376-3ED1D0F428D8"><b>Cryptographic algorithms</b> </p> <p>Cryptographic |
|
72 algorithms allow data to be encrypted and decrypted. They include: </p> <ul> |
|
73 <li id="GUID-C68FBFD7-EE10-5CDD-835B-62D770D7E9E5"><p> <b>Symmetric ciphers</b> — |
|
74 algorithms that require communicating parties to hold a shared secret. They |
|
75 are fast and are used for the transmission of bulk data. </p> </li> |
|
76 <li id="GUID-D7ADFE85-C48D-5E2B-BAF0-CBF68B676C3E"><p> <b>Asymmetric ciphers</b> — |
|
77 algorithms which have two keys, one private to the keys' owner and one which |
|
78 can be published. They are slow compared to symmetric ciphers and are used |
|
79 to exchange a symmetric key before transmission of data encrypted using that |
|
80 key. </p> </li> |
|
81 </ul> <p>The Cryptography algorithms are part of the strong build. To access |
|
82 details of how to implement them you need to access the Security Supplement, |
|
83 which is delivered to device creators with the CBR. </p> <p id="GUID-1C869199-DF50-5DCA-AD0D-5EA31EADA384"><b>Hash |
|
84 algorithms</b> </p> <p><xref href="GUID-679390E8-1DE6-55F0-9A0C-60D58956A1E3.dita">Hash |
|
85 algorithms</xref> compact a message down to a short series of bytes from which |
|
86 it is impossible to regenerate the message. They are used with an asymmetric |
|
87 cipher to generate signatures. </p> <p>The following hash algorithms are supported: </p> <table id="GUID-2ECEAC82-2DEA-5907-9443-ED023DAD2653"> |
|
88 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
89 <thead> |
|
90 <row> |
|
91 <entry>Hash algorithms</entry> |
|
92 <entry>Specified in</entry> |
|
93 </row> |
|
94 </thead> |
|
95 <tbody> |
|
96 <row> |
|
97 <entry><p>MD2 </p> </entry> |
|
98 <entry><p> <xref href="http://www.ietf.org/rfc/rfc1319.txt" scope="external">RFC |
|
99 1319 </xref> </p> </entry> |
|
100 </row> |
|
101 <row> |
|
102 <entry><p>MD4 </p> </entry> |
|
103 <entry><p> <xref href="http://www.ietf.org/rfc/rfc1320.txt" scope="external">RFC |
|
104 1320</xref> </p> </entry> |
|
105 </row> |
|
106 <row> |
|
107 <entry><p>MD5 </p> </entry> |
|
108 <entry><p> <xref href="http://www.ietf.org/rfc/rfc1321.txt" scope="external">RFC |
|
109 1321</xref> </p> </entry> |
|
110 </row> |
|
111 <row> |
|
112 <entry><p>SHA1 </p> </entry> |
|
113 <entry><p> <xref href="http://www.itl.nist.gov/fipspubs/fip180-1.htm" scope="external">FIPS |
|
114 180-1</xref> and <xref href="http://www.ietf.org/rfc/rfc3174.txt" scope="external">RFC |
|
115 3174</xref> </p> </entry> |
|
116 </row> |
|
117 </tbody> |
|
118 </tgroup> |
|
119 </table> <p><i>Hashes in HMAC mode</i> </p> <ul> |
|
120 <li id="GUID-551F9056-7110-5002-8495-D31BAFDCFEA8"><p>MD2 </p> </li> |
|
121 <li id="GUID-4C0AB778-90A5-5EA8-9C26-29248FA9DF63"><p>MD4 </p> </li> |
|
122 <li id="GUID-CC9931AA-B0F4-5832-8C9E-78FBE95F7AEB"><p>MD5 </p> </li> |
|
123 <li id="GUID-6307D557-0AA8-5CC0-88D4-464C31FF1960"><p>SHA1 </p> </li> |
|
124 <li id="GUID-CD13BA31-4543-5E95-8DB4-F9F790F7816D"><p>SHA-224 </p> </li> |
|
125 <li id="GUID-1A2A7EAA-85F5-5516-9590-A2DBA7BBE7FC"><p>SHA-256 </p> </li> |
|
126 <li id="GUID-AACCA093-2CD3-55ED-9D80-298DAB45BBFC"><p>SHA-384 </p> </li> |
|
127 <li id="GUID-7A6E01DF-635C-5EEA-BD53-3CD47CF50160"><p>SHA-512 </p> </li> |
|
128 </ul> <p>HMAC mode is specified in <xref href="http://www.ietf.org/rfc/rfc2104.txt" scope="external">RFC 2104</xref>. </p> <p id="GUID-58FB3D9C-A557-59C7-9AA8-37C77FE9002E"><b>Random |
|
129 Number Generator (RNG)</b> </p> <p><xref href="GUID-0B2245C5-766B-5CF1-8A0C-DD98CEEEBB05.dita">RNG</xref> is |
|
130 the basis for the cryptographic key generation. It uses the RANROT algorithm |
|
131 seeded by random data available on the target hardware (for example free running |
|
132 counters available on ARM processers). </p> <p id="GUID-CE692E1B-A0FF-5CF1-8D22-50BC0D12B83A"><b>Supporting |
|
133 APIs</b> </p> <ul> |
|
134 <li id="GUID-A314831E-84E2-5F33-AF4F-6187020FEB88"><p> <b>Password Based Encryption |
|
135 (PBE)</b> — provides an API to encrypt and decrypt data with a user-supplied |
|
136 password </p> </li> |
|
137 <li id="GUID-FE498ED5-276A-53D1-9283-A4406001B532"><p> <b>Padding</b> — is |
|
138 extra bits concatenated with a key, password, or plaintext to make their length |
|
139 equal to the block size. It defines the way blocks are filled with data when |
|
140 the data to be encrypted is smaller than the block size. Padding is added |
|
141 at encryption and checked on decryption. </p> </li> |
|
142 <li id="GUID-A8A99555-C8BF-5466-8610-67F55A2B36D5"><p> <b>Big integers</b> — |
|
143 arbitrarily large integers. </p> <p>Note that although some functions are |
|
144 exported, the intent is that big integers are only for use by the Cryptography |
|
145 library and not by application code. Big integers are implemented in <filepath>cryptography.dll</filepath>. </p> </li> |
|
146 </ul> <p><b>Implementing CryptoSPI algorithms</b> </p> <p>The guide to CryptoSPI |
|
147 is not publicly available, but the following documents show how to use CryptoSPI |
|
148 to generate random numbers and create a hash: </p> <ul> |
|
149 <li id="GUID-6C8E6AEC-5E02-5608-A9D5-392138EB2538"><p><xref href="GUID-0CD273A2-434C-52E0-B840-CCF24B2853B8.dita">Generating |
|
150 random bytes</xref> </p> </li> |
|
151 </ul> </section> |
|
152 </conbody></concept> |
|