<?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>