<?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-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1" xml:lang="en"><title>How

to create a CryptoSPI plug-in</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-B0B7D886-8759-4806-9BB2-CC378B3A37CC-GENID-1-12-1-26-1-1-9-1-10-1-2-1"><title>Introduction</title> <p><b>Note</b>:

this document is intended for device manufacturers. </p> <p>The purpose of

a CryptoSPI plug-in is to implement one or more cryptographic algorithms. </p> <p>Symbian

provides a plug-in called <filepath>softwarecrypto.dll</filepath> that implements

all algorithms supported by the legacy (pre-Symbian^3) cryptography APIs.

In Symbian^3, the legacy APIs have all been re-implemented to use this plug-in

DLL. The source code for <filepath>softwarecrypto.dll</filepath> is located

under <filepath>src/common/generic/security/cryptospi/source/softwarecrypto/</filepath>. </p> <p>This

is a summary of the steps involved in creating a plug-in, in no particular

order. Details of each step are given in the rest of the document. </p> <ul>

<li id="GUID-9E62C60F-AE68-57D4-939A-43631715D89C-GENID-1-12-1-26-1-1-9-1-10-1-2-1-6-1"><p> <xref href="GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1.dita#GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1/GUID-FFA64681-40E3-5DCE-A4EC-3EEC75A35D63-GENID-1-12-1-26-1-1-9-1-10-1-2-2">Create the MMP file</xref>. </p> </li>

<li id="GUID-3726FB61-4B29-5AAF-AB57-A665DB1F6C0A-GENID-1-12-1-26-1-1-9-1-10-1-2-1-6-2"><p> <xref href="GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1.dita#GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1/GUID-4B845864-BB8E-5207-8210-A3F608DF6E69-GENID-1-12-1-26-1-1-9-1-10-1-2-3">Define the characteristics of the algorithms.</xref>  </p> </li>

<li id="GUID-66A983CE-8D31-5B73-A326-4601B24F4C6B-GENID-1-12-1-26-1-1-9-1-10-1-2-1-6-3"><p> <xref href="GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1.dita#GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1/GUID-CA441465-BDAB-5B7A-B75D-3B877EBE346F-GENID-1-12-1-26-1-1-9-1-10-1-2-4">Implement all or a subset of the functions defined in pluginentrydef.h</xref>. </p> </li>

<li id="GUID-AE856A3F-122C-50AF-BBB4-5A6136CA64B5-GENID-1-12-1-26-1-1-9-1-10-1-2-1-6-4"><p> <xref href="GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1.dita#GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1/GUID-6ECA8DAB-37C4-5D83-9DBC-10641AA7B636-GENID-1-12-1-26-1-1-9-1-10-1-2-5">Implement the MPlugin-derived objects</xref>. </p> </li>

<li id="GUID-FE96900F-EBF2-528A-B0C6-2BA32DB65C77-GENID-1-12-1-26-1-1-9-1-10-1-2-1-6-5"><p> <xref href="GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1.dita#GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7-GENID-1-12-1-26-1-1-9-1-10-1/GUID-661CE3E1-2FAE-58E1-BBB7-2F72AA8714A2-GENID-1-12-1-26-1-1-9-1-10-1-2-6">Update the ROM configuration file</xref>. </p> </li>

</ul> </section>

<section id="GUID-FFA64681-40E3-5DCE-A4EC-3EEC75A35D63-GENID-1-12-1-26-1-1-9-1-10-1-2-2"><title>How to create

the MMP file</title> <p>See for instance <filepath>src/common/generic/security/cryptospi/group/softwarecrypto.mmp</filepath>. </p> <codeblock id="GUID-842C71A7-45F4-5BFA-A088-BC4424741296-GENID-1-12-1-26-1-1-9-1-10-1-2-2-3" xml:space="preserve">TARGET softwarecrypto.dll

TARGETTYPE dll

UID        0x1000008d 0x102835C2

VENDORID     0x70000001

CAPABILITY    All

DEFFILE        softwarecrypto.def

USERINCLUDE        .

USERINCLUDE        ..\inc 

USERINCLUDE        ..\inc\spi

SYSTEMINCLUDE    \epoc32\include

SYSTEMINCLUDE    \epoc32\include\cryptospi

SOURCEPATH    ..\source\softwarecrypto

SOURCE pluginentry.cpp

SOURCE md2impl.cpp md5impl.cpp sha1impl.cpp hmacimpl.cpp

SOURCE 3desimpl.cpp desimpl.cpp rc2impl.cpp rijndaelimpl.cpp arc4impl.cpp symmetriccipherimpl.cpp

SOURCE randomimpl.cpp dsasignerimpl.cpp dsaverifyimpl.cpp rsaimpl.cpp rsafunction.cpp

SOURCE signerimpl.cpp verifierimpl.cpp asymmetriccipherimpl.cpp

LIBRARY euser.lib cryptospi.lib

// Depends on bigint and padding code

LIBRARY cryptography.lib

//Depends on random server for random number generation

LIBRARY random.lib</codeblock> <p>Key points: </p> <ul>

<li id="GUID-0C322CF3-197E-5773-A4BB-CDF4943BE588-GENID-1-12-1-26-1-1-9-1-10-1-2-2-5-1"><p> <codeph>0x1000008d</codeph> identifies

the DLL as static (not polymorphic or an ECOM plug-in) and <codeph>0x102835C2</codeph> is

unique to this plug-in, allocated by Symbian Signed. </p> </li>

<li id="GUID-3D1094C3-A59C-58D0-9873-E5A24935785A-GENID-1-12-1-26-1-1-9-1-10-1-2-2-5-2"><p>It is recommended that

plug-ins have <codeph>ALL</codeph> capabilities because this ensures that

they can be loaded by client applications with any capabilities. </p> </li>

<li id="GUID-47338BE3-4A8C-5B17-BF37-184F996B0A2C-GENID-1-12-1-26-1-1-9-1-10-1-2-2-5-3"><p>The project needs to

link against <filepath>cryptospi.lib</filepath>, the CryptoSPI library. </p> </li>

<li id="GUID-1A985A73-A776-5AE1-A4BD-4CC3227CE223-GENID-1-12-1-26-1-1-9-1-10-1-2-2-5-4"><p>The plug-in needs to

link against <filepath>cryptography.lib</filepath> because big integers (<codeph>RInteger</codeph>)

are implemented in <filepath>cryptography.dll</filepath>. </p> </li>

<li id="GUID-7DEC5079-A30D-5D16-B2EC-FA03605691ED-GENID-1-12-1-26-1-1-9-1-10-1-2-2-5-5"><p> <codeph>SYSTEMINCLUDE

\epoc32\include\cryptospi</codeph> allows code to <codeph>#include</codeph> the

CryptoSPI header files, which are all exported to <filepath>epoc32\include\cryptospi\</filepath>. </p> </li>

</ul> </section>

<section id="GUID-4B845864-BB8E-5207-8210-A3F608DF6E69-GENID-1-12-1-26-1-1-9-1-10-1-2-3"><title>How to define

the algorithm's characteristics</title> <p>All plug-ins must define the characteristics

of their algorithm implementations that are fixed at compile time, as constant

data. Some characteristics are common to all interface types, for instance

the name and UID of the algorithm implemented, the name of the plug-in vendor,

whether the plug-in uses hardware acceleration, and whether it is FIPS certified.

Common characteristics are defined in <xref href="GUID-48BB2346-6840-3A26-B43C-4DF70A322B17.dita#GUID-48BB2346-6840-3A26-B43C-4DF70A322B17/GUID-38201D43-59F9-34A1-9940-14997613998F"><apiname>CryptoSpi::TCommonCharacteristics</apiname></xref>: </p> <codeblock id="GUID-EAEADE27-C875-5713-92DC-050460D22ED5-GENID-1-12-1-26-1-1-9-1-10-1-2-3-3" xml:space="preserve">class TCommonCharacteristics

    {

    public:

      ...

      TInt32 iInterfaceUID;

      TInt32 iAlgorithmUID;

      TInt32 iImplementationUID;

      const TRomLitC16* iCreatorName;

      TBool iIsFIPSApproved;

      TBool iIsHardwareSupported;

      TUint iMaxConcurrencySupported;

      const TRomLitC16* iAlgorithmName;

      TInt iLatency;

      TInt iThroughput;

      };

</codeblock> <p>Other characteristics are specific to a particular interface.

For each interface type, a T class is defined as an aggregation of a <xref href="GUID-BB5BF1BA-686D-30DC-AB50-9F1F58F78051.dita"><apiname>TCommonCharacteristics</apiname></xref> object

and some additional characteristics particular to that interface. For instance, <xref href="GUID-F8CF1F2E-E6EC-3ABE-B18A-C4821115E0AD.dita"><apiname>THashCharacteristics</apiname></xref> includes

a block size, output size and operation mode. (The operation mode can be either <codeph>KHashMode</codeph> or <codeph>KHmacMode</codeph>,

and indicates whether the hash algorithm is an HMAC or not.) </p> <codeblock id="GUID-628BA925-B38B-54F1-B69A-E630E50BB6BF-GENID-1-12-1-26-1-1-9-1-10-1-2-3-5" xml:space="preserve">class THashCharacteristics

    {

    public:

      IMPORT_C TBool IsOperationModeSupported(TUid aOperationMode) const;        

    public:

      TCommonCharacteristics cmn;

      TUint iBlockSize;

      TUint iOutputSize;

      const TInt32* iSupportedOperationModes;

      TUint iOperationModeNum;

      };

</codeblock> <p>All the data types relating to characteristics are defined

in <filepath>plugincharacteristics.h</filepath>. </p> <p>For an example, see <filepath>src/common/generic/security/cryptospi/source/softwarecrypto/pluginconfig.h</filepath>. </p> </section>

<section id="GUID-CA441465-BDAB-5B7A-B75D-3B877EBE346F-GENID-1-12-1-26-1-1-9-1-10-1-2-4"><title>How to implement

the framework code</title> <p>Plug-in modules must implement a defined set

of functions exported at defined ordinals. The function prototypes and the

ordinals (see <xref href="GUID-8C054BE1-1F0D-362D-A8CD-B868488FAAE2.dita"><apiname>TPluginEntryOrdinal</apiname></xref>) are defined in <filepath>pluginentrydef.h</filepath>.

When a client requests an algorithm, these functions are used by CryptoSPI

to query and instantiate algorithm implementations. The simplest way to ensure

that functions are assigned the correct ordinal is to copy the <filepath>softwarecryptoU.def</filepath> exports

file, which can be found in the <filepath>EABI</filepath> and <filepath>BWINS</filepath> directories

in the CryptoSPI source code. </p> <p>Minimally, the plug-in DLL must implement

the function exported at ordinal 1, whose prototype is: </p> <codeblock id="GUID-A6D535EF-5657-5195-A375-5465B588427E-GENID-1-12-1-26-1-1-9-1-10-1-2-4-4" xml:space="preserve">typedef const TCharacteristics** (*EnumerateCharacteristicsFunc)(TUid, TInt&amp;);</codeblock> <p>and at least one of the algorithm factory functions. See for example

class <codeph>CCryptoPluginEntry</codeph> (<filepath>pluginentry.h</filepath> / <filepath>pluginentry.cpp</filepath>). </p> <p>If

the plug-in DLL does not support a particular algorithm, the <codeph>ABSENT</codeph> keyword

should be used in its <filepath>.def</filepath> file to ensure any subsequent

exports are at the correct ordinals. </p> <p><b>Querying the characteristics

of plug-ins</b> </p> <p>CryptoSPI builds up a list of the characteristics

of all the plug-in DLLs by calling the function exported at ordinal 1 (<codeph>EEnumerateCharacteristicsOrdinal</codeph>)

for each DLL and for each interface type. Here is an example implementation: </p> <codeblock id="GUID-02B7F687-19A5-527D-922E-09A32FC728C1-GENID-1-12-1-26-1-1-9-1-10-1-2-4-9" xml:space="preserve">EXPORT_C const TCharacteristics** CCryptoPluginEntry::Enumerate(TUid aInterface, TInt&amp; aNumPlugins)

    {

    const TCharacteristics** ptr(0);

    switch (aInterface.iUid)

        {

    case KHashInterface:

        {

        aNumPlugins=sizeof(KHashCharacteristics)/sizeof(THashCharacteristics*);

        ptr = (const TCharacteristics**) &KHashCharacteristics[0];

        }

        break;

    case KRandomInterface:

        {

        aNumPlugins=sizeof(KRandomCharacteristics)/sizeof(TRandomCharacteristics*);

        ptr= (const TCharacteristics**) &KRandomCharacteristics[0];

        }

        break;

  ...

  }

 return ptr;

 }

</codeblock> <p>Key points: </p> <ul>

<li id="GUID-CBAC6B6F-30CC-5B57-BF58-A4B14C94A04A-GENID-1-12-1-26-1-1-9-1-10-1-2-4-11-1"><p>Every plug-in must implement

this function. </p> </li>

<li id="GUID-E263363A-4137-5D7E-8988-4B25E492D39F-GENID-1-12-1-26-1-1-9-1-10-1-2-4-11-2"><p> <codeph>TUid aInterface</codeph> is

the interface UID, as defined in <codeph>CryptoSpi::KInterfacesUids</codeph>. </p> </li>

<li id="GUID-C7A913A0-DD63-599F-8A34-EA2D7466B050-GENID-1-12-1-26-1-1-9-1-10-1-2-4-11-3"><p> <codeph>TInt&amp; aNumPlugins</codeph> should

be set to the number of algorithms of that interface type implemented by the

plug-in. </p> </li>

</ul> <p><b>Extended characteristics</b> </p> <p>Extended characteristics

are those which can only be determined at runtime. They are retrieved on demand

by CryptoSPI or clients can call the plug-in's implementation of <codeph>CryptoSpi::CCryptoBase::GetExtendedCharacteristicsL()</codeph>. </p> <p>The

function exported at ordinal 2 has this prototype: </p> <codeblock id="GUID-5A10F3D2-DAE9-55F6-BF1A-A0E001637ACE-GENID-1-12-1-26-1-1-9-1-10-1-2-4-15" xml:space="preserve">typedef void (*GetExtendedCharacteristicsFuncL)(TUid, CExtendedCharacteristics*&amp;);</codeblock> <p>Symbian defines 2 extended characteristics: </p> <ul>

<li id="GUID-DFCA6450-2121-5257-9F26-A11FD8995E5D-GENID-1-12-1-26-1-1-9-1-10-1-2-4-17-1"><p> <codeph>TInt iAvailableConcurrency;</codeph>  </p> <p>The

number of available resources for processing the operation for the requested

plug-in. This could be zero even if no operations are in progress; for instance

cryptographic acceleration hardware is turned off to save battery power. </p> </li>

<li id="GUID-FEA9BD5F-B264-5316-9B15-FD5E0E51CAC2-GENID-1-12-1-26-1-1-9-1-10-1-2-4-17-2"><p> <codeph>TBool iExclusiveUse;</codeph>  </p> <p>Whether

it is possible for the application to reserve exclusive use of hardware resources

used by the plug-in. </p> </li>

</ul> <p>Additional plug-in specific characteristics may be defined. The plug-in

creator needs to define UIDs for each of these and specify the UID when calling <codeph>CryptoSpi::CExtendedCharacteristics::AddCharacteristicL()</codeph>. </p> <p><b>Algorithm instantiation</b> </p> <p>A plug-in must implement

one or more factory methods for instantiating algorithms. The functions exported

at ordinals 3 to 20 have the following declarations. (Note that symmetric

key generation is not yet implemented by Symbian's software crypto plug-in,

so the ordinals <codeph>ECreateSymmetricKeyGeneratorOrdinal</codeph> and <codeph>ECreateAsyncSymmetricKeyGeneratorOrdinal</codeph> have

no corresponding declarations). </p> <codeblock id="GUID-A6330276-FB1A-5C14-A2BF-5BBCD452614B-GENID-1-12-1-26-1-1-9-1-10-1-2-4-21" xml:space="preserve">typedef void (*CreateRandomFuncL)(MRandom*&amp;, TUid, const CCryptoParams*);

typedef void (*CreateHashFuncL)(MHash*&, TUid, TUid, const CKey*, const CCryptoParams*);

typedef void (*CreateSymmetricCipherFuncL)(MSymmetricCipher*&, TUid, const CKey&, TUid, TUid, TUid, const CCryptoParams*);

typedef void (*CreateAsymmetricCipherFuncL)(MAsymmetricCipher*&, TUid, const CKey&, TUid, TUid, const CCryptoParams*);

typedef void (*CreateSignerFuncL)(MSigner*&, TUid, const CKey&, TUid, const CCryptoParams*);

typedef void (*CreateVerifierFuncL)(MVerifier*&, TUid, const CKey&, TUid, const CCryptoParams*);

typedef void (*CreateKeyAgreementFuncL)(MKeyAgreement*&, TUid, const CKey&, const CCryptoParams*);

typedef void (*CreateKeyPairGeneratorFuncL)(MKeyPairGenerator*&, TUid, const CCryptoParams*);

typedef void (*CreateAsyncRandomFuncL)(MAsyncRandom*&, TUid, const CCryptoParams*);

typedef void (*CreateAsyncHashFuncL)(MAsyncHash*&, TUid, TUid, const CKey*, const CCryptoParams*);

typedef void (*CreateAsyncSymmetricCipherFuncL)(MAsyncSymmetricCipher*&, TUid, const CKey&, TUid, TUid, TUid, const CCryptoParams*);

typedef void (*CreateAsyncAsymmetricCipherFuncL)(MAsyncAsymmetricCipher*&, TUid, const CKey&, TUid, TUid, const CCryptoParams*);

typedef void (*CreateAsyncSignerFuncL)(MAsyncSigner*&, TUid, const CKey&, TUid, const CCryptoParams*);

typedef void (*CreateAsyncVerifierFuncL)(MAsyncVerifier*&, TUid, const CKey&, TUid, const CCryptoParams*);

typedef void (*CreateAsyncKeyAgreementFuncL)(MAsyncKeyAgreement*&, TUid, const CKey&, const CCryptoParams*);

typedef void (*CreateAsyncKeyPairGeneratorFuncL)(MAsyncKeyPairGenerator*&amp;, TUid, const CCryptoParams*);</codeblock> <p>Clients

instantiate algorithms by calling one of the CryptoSPI factory methods, for

instance <xref href="GUID-FF3CFE33-C90A-328C-BF80-0A03B821AE1C.dita#GUID-FF3CFE33-C90A-328C-BF80-0A03B821AE1C/GUID-D91B2099-C9F4-3B7C-843F-39A654DC0555"><apiname>CHashFactory::CreateHashL()</apiname></xref>. All CryptoSPI factory

methods take a <xref href="GUID-C3704390-D2DD-3DFF-A1E3-433C5030044B.dita"><apiname>CCryptoParams</apiname></xref> parameter. This class allows

clients to supply arbitrary, algorithm-specific data to plug-ins, for instance

the effective key length for RC2, or the number of bytes to discard from the

keystream for ARC4. </p> <p>The data type of each parameter can be integer

(<codeph>TInt</codeph>), big integer (<codeph>RInteger</codeph>), or 8/16

bit descriptor. Additional data types could be added in future, by extending

the <codeph>TParamType</codeph> enum in <codeph>CCryptoParam</codeph> and

deriving a class from <codeph>CCryptoParam</codeph>, but this is unlikely

to be necessary. </p> </section>

<section id="GUID-6ECA8DAB-37C4-5D83-9DBC-10641AA7B636-GENID-1-12-1-26-1-1-9-1-10-1-2-5"><title>How to implement

the MPlugin-derived class</title> <p>All concrete algorithm classes are derived

from one of the abstract base classes listed below, which are in turn all

derived from <codeph>MPlugin</codeph>. </p> <ul>

<li id="GUID-83E757D2-E70D-51D3-BF46-53A2F8A8A3E9-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-1"><p>Random (<xref href="GUID-53D7EA29-2736-3B19-AA69-915FAD2A7130.dita"><apiname>MRandom</apiname></xref> /<xref href="GUID-A19A4B6F-CCF2-3167-B757-F8308B7B7C26.dita"><apiname>MAsyncRandom</apiname></xref>) </p> </li>

<li id="GUID-ABDD0216-BA34-5DD1-8D07-064B3F1EAB02-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-2"><p>Hash (<xref href="GUID-6896A7F0-AE37-369E-AB54-F069A7DE3FDB.dita"><apiname>MHash</apiname></xref> /<xref href="GUID-A4B3807A-82D1-39D3-8D00-D2A1D41EFEA5.dita"><apiname>MAsyncHash</apiname></xref>) </p> </li>

<li id="GUID-5611F951-0471-5A54-BCFE-4DBDB9FF7B1A-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-3"><p>Symmetric cipher (<xref href="GUID-733DAE85-68B3-3211-808A-4FBD9C1E1F05.dita"><apiname>MSymmetricCipher</apiname></xref> /<xref href="GUID-545AE46E-8CF1-3470-8F10-5FCB6D79859E.dita"><apiname>MAsyncSymmetricCipher</apiname></xref>) </p> </li>

<li id="GUID-C87B0A48-C66F-5E5E-BEA4-BB3F187AA59D-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-4"><p>Asymmetric cipher (<xref href="GUID-C044BB6D-6E78-3698-8710-89FFB7A6CDFD.dita"><apiname>MAsymmetricCipher</apiname></xref> /<xref href="GUID-EE7FCCA6-D86F-30E2-BB6A-862BAE111344.dita"><apiname>MAsyncAsymmetricCipher</apiname></xref>) </p> </li>

<li id="GUID-EE95A2C8-4F9C-5052-8709-AD7C1D2A5E6F-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-5"><p>Signer (<xref href="GUID-59F2E24A-5F48-383F-95C6-88A5B432E121.dita"><apiname>MSigner</apiname></xref> /<xref href="GUID-B0EC8744-B525-3599-B1B4-00E4A9C62C7A.dita"><apiname>MAsyncSigner</apiname></xref>) </p> </li>

<li id="GUID-717313C9-B2A3-5E78-8A61-A4C3093627BF-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-6"><p>Verifier (<xref href="GUID-98E08EBD-3758-39D6-A2B1-EC42F66D2F84.dita"><apiname>MVerifier</apiname></xref> /<xref href="GUID-BCCA1F97-B568-3B75-9974-5E70F1ADDEFA.dita"><apiname>MAsyncVerifier</apiname></xref>) </p> </li>

<li id="GUID-8EA174F1-16A5-5364-9672-5AF6644EC19A-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-7"><p>Key agreement (<xref href="GUID-A47EF879-B23E-339A-9EBC-3622668B83FB.dita"><apiname>MKeyAgreement</apiname></xref> /<xref href="GUID-E70B8C8A-384F-39F0-8845-4CE53E86B286.dita"><apiname>MAsyncKeyAgreement</apiname></xref>) </p> </li>

<li id="GUID-3988580D-047C-5492-9493-0A5365FEFB84-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-8"><p>Key pair generator (<xref href="GUID-238EBB3C-0ECC-38A5-848E-28716B75931B.dita"><apiname>MKeyPairGenerator</apiname></xref> /<xref href="GUID-5B2CE80F-536F-3B75-9FD9-3C0C98EE3D09.dita"><apiname>MAsyncKeyPairGenerator</apiname></xref>) </p> </li>

<li id="GUID-05483361-4043-5FC4-A134-AAEA2E31E872-GENID-1-12-1-26-1-1-9-1-10-1-2-5-3-9"><p>Key generator (<xref href="GUID-1492AF86-FD98-3219-B46B-543DD7066801.dita"><apiname>MSymmetricKeyGenerator</apiname></xref> /<xref href="GUID-A3F12E4C-51D7-3007-A53E-EC53FAEA3D9C.dita"><apiname>MAsyncSymmetricKeyGenerator</apiname></xref>) </p> </li>

</ul> <p> <xref href="GUID-6BD89347-671F-3518-9777-55801A090C79.dita"><apiname/></xref><xref href="GUID-47357E35-5781-3093-80FD-052EC7F0DF3F.dita"><apiname>MPlugin</apiname></xref> (<filepath>cryptoplugin.h</filepath>)

declares the following pure virtual functions: </p> <codeblock id="GUID-6CDA7919-C31E-50EB-8D67-7A142297DBAF-GENID-1-12-1-26-1-1-9-1-10-1-2-5-5" xml:space="preserve">virtual void Close() = 0;

virtual void Reset() = 0;

virtual void GetCharacteristicsL(const TCharacteristics*& aPluginCharacteristics) = 0;

virtual const CExtendedCharacteristics& GetExtendedCharacteristicsL() = 0;

virtual TAny* GetExtension(TUid aExtensionId) = 0;</codeblock> <p>For example,

the random number generator plug-in implemented in <filepath>softwarecrypto.dll</filepath> implements

these functions as follows: </p> <codeblock id="GUID-A18C6FDA-4E3C-570E-B700-7680F91D397D-GENID-1-12-1-26-1-1-9-1-10-1-2-5-7" xml:space="preserve">void CRandomImpl::Close()

    {

    delete this;

    }

void CRandomImpl::Reset()

    { //Not required

    }

const CExtendedCharacteristics* CRandomImpl::GetExtendedCharacteristicsL()

 // All Symbian software plug-ins have unlimited concurrency and cannot be reserved

    // for exclusive use 

    {

    return CExtendedCharacteristics::NewL(KMaxTInt, EFalse);

    }

//Get the plug-in characteristics (defined at compile time)

void CRandomImpl::GetCharacteristicsL(const TCharacteristics*& aPluginCharacteristics)

    {

 //Find out how many algorithms are implemented by the plug-in

    TInt randomNum = sizeof(KRandomCharacteristics)/sizeof(TRandomCharacteristics*);

    for (TInt i = 0; i < randomNum; i++)

        {

  //Compare implementation UIDs

  //ImplementationUid() is a helper function that returns KCryptoPluginRandomUid

        if (KRandomCharacteristics[i]->cmn.iImplementationUID == ImplementationUid().iUid)

            {

            aPluginCharacteristics = KRandomCharacteristics[i];

            break;

            }

        }

    }

TAny* CRandomImpl::GetExtension(TUid /*aExtensionId*/)

    {

    return NULL;

    }</codeblock> <p>The main purpose of <codeph>MPlugin::Reset()</codeph> is

to reset the hardware, so is usually not relevant to a software-only implementation. <codeph>GetExtension()</codeph> is

intended for internal use, and may be removed from the API in future. </p> <p>These

functions are called through the client API to CryptoSPI, in other words <codeph>CCryptoBase</codeph> and

the various classes derived from it, in this case, <codeph>CRandom</codeph>.

For instance when the client calls <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>,

this calls <codeph>GetCharacteristicsL()</codeph> in the plug-in, or calling <xref href="GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4.dita#GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4/GUID-F251BF16-E212-3595-9FE8-C7BC754972E1"><apiname>CRandom::GenerateRandomBytesL()</apiname></xref>,

calls <codeph>GenerateRandomBytesL()</codeph> in the plug-in. </p> </section>

<section id="GUID-661CE3E1-2FAE-58E1-BBB7-2F72AA8714A2-GENID-1-12-1-26-1-1-9-1-10-1-2-6"><title>The configuration

file</title> <p>The set of available plug-ins is listed in the configuration

file <filepath>z:\resource\cryptospi\plug-ins.txt</filepath>. Each line in

the file contains the filename of a single plug-in DLL, without the path.

The path is not required because the DLLs are assumed to be located in <filepath>z:\sys\bin</filepath>.

The configuration file must be on the <filepath>Z:</filepath> drive and therefore

additional plug-ins cannot be installed post-manufacture. Depending on the

plug-in selector in use, plug-ins may be loaded individually, as required,

or all at once when CryptoSPI is initialized. The default selector implemented

by Symbian (<codeph>CLegacySelector</codeph>) loads plug-in DLLs as required. </p> </section>

</conbody></concept>