<?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-BCDCB147-865F-58B0-816F-5FBF0E7CCDD7" xml:lang="en"><title>CryptoSPI
Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-3DAB2F6F-85F6-4AD9-97D9-90B380F8077D"><title>Introduction</title> <p>CryptoSPI
(<filepath>cryptospi.dll</filepath>) is a library introduced in Symbian^3
that manages the selection and loading of cryptographic algorithms. Cryptographic
algorithms enable data to be encrypted and decrypted. The services provided
by CryptoSPI are used by the following components: Certman (Certificate Management),
Software Installation, Secure Communication Protocols (for example, SSL, TLS,
IPSEC), and WTLS. </p> <p>CryptoSPI also provides a framework that allows
licensees and partners to implement additional cryptographic algorithms as
plug-ins to CryptoSPI. </p> <p>The benefits of CryptoSPI are: </p> <ul>
<li id="GUID-32F02DC3-54AD-5520-AD1B-E85317BB4AFE"><p>Plug-ins can use cryptographic
acceleration hardware, which can improve performance and reduce power consumption.
Client applications do not need to know whether an operation is implemented
in software or hardware. </p> </li>
<li id="GUID-B2880123-00C8-58E7-8475-9B3D68059BF4"><p>Its architecture allows
new algorithms or modes of operation to be added by licensees without impacting
the existing APIs or client code. </p> </li>
<li id="GUID-AC37BE3F-52BE-56E9-9E34-F25277F51434"><p>The legacy cryptography
libraries (<filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>)
have been preserved. Legacy client code can continue to use them without needing
modification or re-compilation. This is achieved via an internal BC layer
that routes legacy function calls to use the new SPI. </p> </li>
<li id="GUID-2085DF2B-E97F-5B4F-B01D-84B76ED5FDE7"><p>CryptoSPI adds support
for non-extractable keys, which may be used to protect sensitive or high-value
content. </p> </li>
<li id="GUID-F27670BD-8CAA-5EEA-9A82-6AB2C8741145"><p>CryptoSPI is more secure
against malicious code than the legacy API, because it does not store any
data, it has no server component and plugins must be located in ROM, so cannot
be replaced or eclipsed. </p> </li>
</ul> </section>
<section id="GUID-5038F0E4-7FA2-4D9B-8EC0-D6670B4CCFA2"><title>Architectural
relationships</title> <p>CryptoSPI was introduced in Symbian^3. Before Symbian^3,
cryptographic algorithms, hash algorithms and random number generation were
implemented by Symbian in <filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>.
As shown in the CryptoSPI dependencies diagram, Symbian's legacy implementations
and APIs were retained in Symbian^3, so that existing code does not need to
be modified or recompiled. </p> <p> <filepath>softwarecrypto.dll</filepath> is
a plug-in module implemented by Symbian 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 licensee-provided plug-in module.
The plug-ins and <filepath>cryptospi.dll</filepath> have a dependency on <filepath>cryptography.dll</filepath> because
it implements <xref href="GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita">big integers</xref>. </p> <fig id="GUID-81B9B94D-07B8-512F-8553-0C98F557A21A">
<title>              CryptoSPI dependencies</title>
<image href="GUID-7501D3AC-16FB-58E9-B55C-2598ECCD2FFA_d0e381250_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-BA9876DF-7166-4336-8BAC-D0B9AB051B47"><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 by Symbian in <filepath>softwarecrypto.dll</filepath>  </p> <p>This
section includes summary details of the following: </p> <ul>
<li id="GUID-B57702C1-A525-5F77-9BB5-D6CCB4E45929"><p>cryptographic algorithms </p> </li>
<li id="GUID-4148CBE5-77D8-5455-9A84-E6B978EF1017"><p>hash algorithms. </p> </li>
<li><p>random number generator</p></li>
</ul> <p><b>Cryptographic algorithms</b> </p><ul>
<li><p><b>Symmetric ciphers</b> - The following symmetric algorithms are supported: </p><table id="GUID-EE0B2BF7-BD22-5A03-B4DB-A82D713BB52F">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Symmetric algorithm</entry>
<entry>Type</entry>
<entry>Specified in:</entry>
</row>
</thead>
<tbody>
<row>
<entry><p>AES (Advanced Encryption Standard) </p> </entry>
<entry><p>Block cipher </p> </entry>
<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf" scope="external">FIPS-197</xref> </p> </entry>
</row>
<row>
<entry><p>DES (Data Encryption Standard) </p> </entry>
<entry><p>Block cipher </p> </entry>
<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf" scope="external">FIPS 46-3</xref>  </p> </entry>
</row>
<row>
<entry><p>3DES (Triple Data Encryption Standard) </p> </entry>
<entry><p>Block cipher </p> </entry>
<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf" scope="external">FIPS 46-3</xref>  </p> </entry>
</row>
<row>
<entry><p>RC2-128 </p> </entry>
<entry><p>Block cipher </p> </entry>
<entry><p> <xref href="ftp://ftp.rfc-editor.org/in-notes/rfc2268.txt" scope="external">RFC
2268</xref>  </p> </entry>
</row>
<row>
<entry><p>ARC4 ('alleged' RC4) </p> </entry>
<entry><p>Stream cipher </p> </entry>
<entry><p>The internet and a posting to sci.crypt in 1994. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p> <b> Note:</b> Algorithm identifiers for MISTY1, MISTY2 and Kasumi
(A5/3) block ciphers are in the cryptography library. These identifiers allow
clients of the cryptography library to request implementations of these algorithms
from the symmetric cipher factory. Symbian does not provide implementations
of these algorithms, so the default behavior is for the factory function to
return an error indicating that there is no implementation available. </p> <p><b>Note</b>:
Until Symbian^3, the classes implementing the symmetric and asymmetric ciphers
were provided in <filepath>cryptography.dll</filepath>. </p></li>
<li><p><b>Asymmetric ciphers </b> - The following asymmetric algorithms are
supported: </p><table id="GUID-EF226280-A0A6-5CDC-A561-E2CA11D551B0">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry>Asymmetric algorithm</entry>
<entry>What is's used for</entry>
<entry>Specified in:</entry>
</row>
</thead>
<tbody>
<row>
<entry><p>RSA PKCS#1 v1.5 </p> </entry>
<entry><p>Signing data </p> <p>Key pair generation </p> </entry>
<entry><p> <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2125" scope="external">PKCS#1</xref> v1.5 </p> </entry>
</row>
<row>
<entry><p>DSA </p> </entry>
<entry><p>Signing data </p> <p>Key pair generation </p> </entry>
<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips186-2/fips186-2-change1.pdf" scope="external">FIPS 186-2</xref> CR1 </p> </entry>
</row>
<row>
<entry><p>Diffie Hellman </p> </entry>
<entry><p>Key agreement </p> <p>Key pair generation </p> </entry>
<entry><p> <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2126" scope="external">PKCS#3</xref>  </p> </entry>
</row>
</tbody>
</tgroup>
</table></li>
<li><p><b>Hash algorithms</b> - The following hash algorithms are supported:</p><p><table id="GUID-ABBDB728-AC1E-4C93-949C-401938589A22">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top"><p>Hash algorithms</p></entry>
<entry valign="top"><p>Specified in</p></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>
<row>
<entry><p>SHA-224</p></entry>
<entry><p><xref href="http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf " scope="external">FIPS 180-2</xref></p></entry>
</row>
<row>
<entry><p>SHA-256</p></entry>
<entry><p><xref href="http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf " scope="external">FIPS 180-2</xref></p></entry>
</row>
<row>
<entry><p>SHA-384</p></entry>
<entry><p><xref href="http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf " scope="external">FIPS 180-2</xref></p></entry>
</row>
<row>
<entry><p>SHA-512</p></entry>
<entry><p><xref href="http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf " scope="external">FIPS 180-2</xref></p></entry>
</row>
</tbody>
</tgroup>
</table></p></li>
<li><p><b>Hashes in HMAC mode</b></p><ul>
<li><p>MD2</p></li>
<li><p>MD4</p></li>
<li><p>MD5</p></li>
<li><p>SHA1</p></li>
<li><p>SHA-224</p></li>
<li><p>SHA-256</p></li>
<li><p>SHA-384</p></li>
<li><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></li>
</ul> <p><b>Instantiating algorithms</b> </p> <p>Clients request cryptographic
algorithms using static factory functions. </p> <p>For instance, to create
a hash algorithm, use the generic hash factory function <xref href="GUID-D2231146-4F0D-3F70-8249-C166375D78DC.dita#GUID-D2231146-4F0D-3F70-8249-C166375D78DC/GUID-2C0F6052-76A8-3E45-AF72-F567E1161212"><apiname>CryptoSpi::CHashFactory::CreateHashL()</apiname></xref>,
specifying the UID of the required algorithm. UIDs are defined in <filepath>cryptospidef.h</filepath>,
for instance <codeph>KMd2Uid</codeph>, <codeph>KMd5Uid</codeph>, <codeph>KSha1Uid</codeph>.
CryptoSPI uses a <xref href="GUID-BCDCB147-865F-58B0-816F-5FBF0E7CCDD7.dita#GUID-BCDCB147-865F-58B0-816F-5FBF0E7CCDD7/GUID-15969DD8-8F8A-534D-8445-A5CC95112B63">plug-in
selector</xref> to search for a plug-in that implements the requested algorithm.
When a plug-in is found, CryptoSPI loads it if required, and calls the function
defined at the relevant ordinal in the plug-in DLL, in this case <codeph>ECreateHashOrdinal</codeph>,
to instantiate a hash object, which is returned to the caller. </p> <p><b>Operation
and padding modes</b> </p> <p>CryptoSPI has been designed to be simpler and
more compact than the API that it replaces. Rather than defining separate
classes to do encryption and decryption, for instance, <codeph>C3DESEncryptor</codeph> and <codeph>C3DESDecryptor</codeph>,
CryptoSPI implements a single, generic symmetric cipher class, <codeph>CryptoSpi::CSymmetricCipher</codeph>.
The characteristics of the algorithm, for instance whether it does encryption
or decryption, the operation mode for block ciphers (<codeph>KOperationModeECB</codeph>, <codeph>KOperationModeCBC</codeph> etc.),
and the padding mode (<codeph>KPaddingModeSSLv3</codeph>, <codeph>KPaddingModePKCS7</codeph> etc.)
are all passed by the client to the factory function as UIDs — see <xref href="GUID-5463D9D7-2DE0-3DC1-A415-910636125935.dita#GUID-5463D9D7-2DE0-3DC1-A415-910636125935/GUID-43F80501-62A9-3987-B057-852A1E80E483"><apiname>CryptoSpi::CSymmetricCipherFactory::CreateSymmetricCipherL()</apiname></xref>. </p> <p>The client can switch the algorithm between modes by setting a
flag, see for example <xref href="GUID-699F30D8-BC52-3F83-9188-8CF86B2B0800.dita#GUID-699F30D8-BC52-3F83-9188-8CF86B2B0800/GUID-121C4AC5-0D1C-33E7-A534-A4A6AA4DF6FD"><apiname>CSymmetricCipherBase::SetCryptoModeL()</apiname></xref>, <xref href="GUID-699F30D8-BC52-3F83-9188-8CF86B2B0800.dita#GUID-699F30D8-BC52-3F83-9188-8CF86B2B0800/GUID-22633D2E-2D3A-3B30-91D2-A5A97C5274BC"><apiname>CSymmetricCipherBase::SetPaddingModeL()</apiname></xref> and <xref href="GUID-699F30D8-BC52-3F83-9188-8CF86B2B0800.dita#GUID-699F30D8-BC52-3F83-9188-8CF86B2B0800/GUID-8D992640-AFCE-3839-AD50-0543AFBE564D"><apiname>CSymmetricCipherBase::SetOperationModeL()</apiname></xref>. </p> <p><ul>
<li><p><b>Operation modes </b></p><p>Symbian platform provides default software
implementations of the following operation modes: </p><ul>
<li id="GUID-A7FBAF70-5202-5958-866F-9BACB7D3E0B3"><p>ECB </p> </li>
<li id="GUID-3C51459C-C660-5F38-AD61-3F954DFF3ECF"><p>CBC </p> </li>
<li id="GUID-A718E6C7-59D2-5324-8EE3-764E627D7AF4"><p>CTR (counter) </p> </li>
</ul><p>They are specified in <xref href="http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf" scope="external">NIST Special Publication 800-38A</xref>. </p></li>
<li><p><b>Padding modes </b></p><p>Symbian platform supports the following
padding modes: </p><ul>
<li id="GUID-8BC577C7-6A7E-5A0F-B8C9-1D7E93CE2E80"><p>SSLv3-style padding </p> </li>
<li id="GUID-FA955DDF-CC6C-5CB3-878F-EE319C82EC3F"><p>PKCS#7-style padding </p> </li>
<li id="GUID-93D60F44-17F9-54DD-B947-41D63C943B3F"><p>PKCS#1 v1.5 Encryption-style
padding </p> </li>
<li id="GUID-EF45D638-105A-5DDB-AC22-B37CA5868D97"><p>PKCS#1 v1.5 Signature-style
padding </p> </li>
</ul></li>
</ul> </p> <p><b>Asynchronous operation and cancellation</b> </p> <p>The legacy
cryptography library only supports synchronous operations. By enabling cryptographic
acceleration hardware, CryptoSPI supports more advanced use cases. In order
for users to be able to cancel potentially long-running operations such as
the decryption of high-quality audio/visual content, CryptoSPI supports both
synchronous and asynchronous interfaces for each cryptographic operation,
the latter providing a <codeph>Cancel()</codeph> function. </p> <p><b>Note</b>:
Symbian's software plug-in module (<filepath>softwarecrypto.dll</filepath>)
only implements the synchronous interfaces. </p> <p><b>Plug-ins</b> </p> <p>A
CryptoSPI plugin DLL can implement zero, one or more algorithms, and may provide
alternative implementations of the same algorithm. The set of plugin DLLs
is defined in a configuration file in ROM (<filepath>Z:\resource\cryptospi\plug-ins.txt</filepath>).
CryptoSPI will only load plugins stored in ROM (<filepath>Z:\sys\bin\</filepath>),
so plug-in modules cannot be added by third parties after-market. </p> <p> <filepath>cryptospi.dll</filepath> and
all plug-ins have <codeph>ALL</codeph> capabilities, which ensures that they
can be loaded by client applications with any capabilities. </p> <p>The abstract
base class for all cryptographic plug-ins is <xref href="GUID-48BB2346-6840-3A26-B43C-4DF70A322B17.dita#GUID-48BB2346-6840-3A26-B43C-4DF70A322B17/GUID-8390A214-1E1B-3E8F-A6C9-6030D99F532C"><apiname>CryptoSpi::MPlugin()</apiname></xref>. </p> <p>See
also: <xref href="GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7.dita">How to create
a CryptoSPI plugin</xref>. </p> <p><b>UIDs and plug-in characteristics</b> </p> <p>Plug-ins
are identified by three UIDs: </p> <ul>
<li id="GUID-3A357C90-9E3B-5620-93E0-CF45ABD57993"><p>the interface supported,
for instance hash (<codeph>KHashInterfaceUid</codeph>), </p> </li>
<li id="GUID-E2FAF159-EE47-5DE6-AB03-D133D815C690"><p>the algorithm implemented,
for instance MD2 (<codeph>KMd2Uid</codeph>), and </p> </li>
<li id="GUID-4EB6A03E-F3C5-5577-8C68-4761C25361E8"><p>the unique implementation
ID. </p> </li>
</ul> <p>These three UIDs are part of the plug-in's <i>characteristics</i>.
Plug-in characteristics are defined at compile time as constant data. They
describe the type and capabilities of a plug-in implementation. Some characteristics
are relevant to all plug-in types, for instance the name and UID of the algorithm
implemented, the name of the plug-in vendor and whether the plug-in uses hardware
acceleration. These are termed <i>common characteristics</i> and are defined
in <xref href="GUID-48BB2346-6840-3A26-B43C-4DF70A322B17.dita#GUID-48BB2346-6840-3A26-B43C-4DF70A322B17/GUID-704C9275-4009-3E20-82F1-FBED2B29976E"><apiname>CryptoSpi::TCommonCharacteristics()</apiname></xref>. Other characteristics
are specific to a particular interface type, for instance the modes of operation
for a symmetric cipher. These are defined in an interface-specific characteristics
class, for instance <xref href="GUID-48BB2346-6840-3A26-B43C-4DF70A322B17.dita#GUID-48BB2346-6840-3A26-B43C-4DF70A322B17/GUID-CC81BF89-1AA4-3779-B7DB-A01C89041965"><apiname>CryptoSpi::TSymmetricCipherCharacteristics()</apiname></xref>,
that have a <codeph>TCommonCharacteristics</codeph> data member. Plug-in characteristics
can be retrieved using <xref href="GUID-ED01CE2C-30E8-344F-B3C9-895FA576D33F.dita#GUID-ED01CE2C-30E8-344F-B3C9-895FA576D33F/GUID-8D93089E-1F97-376B-8CC0-08E0E34158F4"><apiname>CCryptoBase::GetCharacteristicsL()</apiname></xref>. </p> <p>Plug-ins
may optionally also have 'extended' characteristics. These are set at runtime,
for instance the number of concurrent operations supported by the plug-in,
and can be retrieved using <xref href="GUID-87D367F5-0FD8-3BEE-AFB0-B48706902C99.dita#GUID-87D367F5-0FD8-3BEE-AFB0-B48706902C99/GUID-720996CA-353D-37A2-A40E-3A18EC8EF4EB"><apiname>CryptoSpi::MPlugin::GetExtendedCharacteristicsL()</apiname></xref>. </p> <p id="GUID-15969DD8-8F8A-534D-8445-A5CC95112B63"><b>Selection rules</b> </p><p>Symbian
has implemented a plug-in selector, <xref href="GUID-48BB2346-6840-3A26-B43C-4DF70A322B17.dita#GUID-48BB2346-6840-3A26-B43C-4DF70A322B17/GUID-2E6D755A-2170-3A7A-8F89-1748CE1FEBDE"><apiname>CryptoSpi::CLegacySelector()</apiname></xref>,
which is used both by the legacy API and by default by CryptoSPI to select
algorithms implemented in <filepath>softwarecrypto.dll</filepath>. In other
words, by default, CryptoSPI and the legacy API use the same algorithm implementations.
The legacy selector works by loading DLLs one by one according to their order
in the ROM configuration file until a suitable implementation is found. </p> <p>As
an alternative to using the default selector, clients can specify a rule-based
selector (<xref href="GUID-48BB2346-6840-3A26-B43C-4DF70A322B17.dita#GUID-48BB2346-6840-3A26-B43C-4DF70A322B17/GUID-DAA57D69-9E75-3333-9227-76D7B0719B7E"><apiname>CryptoSpi::CRuleSelector()</apiname></xref>). This causes CryptoSPI
to re-generate the list of plug-ins, according to a set of selection rules.
The API is described in <xref href="GUID-5857377F-B90D-5149-9485-5919C12B8F13.dita">How
to use a rule-based selector</xref>. </p> <p>In general, it is recommended
that applications should not specify selection rules unless it is critical
to the operation of the application. The preferred approach is to use the
plugin chosen by the default selector, which can be assumed to provide good
performance for the most common use cases. </p> </section>
</conbody><related-links>
<link href="GUID-679390E8-1DE6-55F0-9A0C-60D58956A1E3.dita"><linktext>Hash (message
digest) algorithms</linktext></link>
<link href="GUID-0CD273A2-434C-52E0-B840-CCF24B2853B8.dita"><linktext>Generating
random bytes</linktext></link>
<link href="GUID-D2D17EF9-FFC6-5FBD-A992-55746A12B625.dita"><linktext>Basic encryption
and decryption using a symmetric cipher</linktext></link>
<link href="GUID-38C8F8B0-C259-5B03-A13E-10DBED4071F2.dita"><linktext>Signing and
verification</linktext></link>
<link href="GUID-5857377F-B90D-5149-9485-5919C12B8F13.dita"><linktext>How to use
a rule-based selector</linktext></link>
</related-links></concept>