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