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

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

    14 <section id="GUID-B0B7D886-8759-4806-9BB2-CC378B3A37CC"><title>Introduction</title> <p><b>Note</b>:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    29 </ul> </section>

    30 <section id="GUID-FFA64681-40E3-5DCE-A4EC-3EEC75A35D63"><title>How to create

    31 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" xml:space="preserve">TARGET softwarecrypto.dll

    32 TARGETTYPE dll

    33 

    34 UID        0x1000008d 0x102835C2

    35 VENDORID     0x70000001

    36 

    37 CAPABILITY    All

    38 

    39 DEFFILE        softwarecrypto.def

    40 

    41 USERINCLUDE        .

    42 USERINCLUDE        ..\inc 

    43 USERINCLUDE        ..\inc\spi

    44 SYSTEMINCLUDE    \epoc32\include

    45 SYSTEMINCLUDE    \epoc32\include\cryptospi

    46 

    47 SOURCEPATH    ..\source\softwarecrypto

    48 SOURCE pluginentry.cpp

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

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

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

    52 SOURCE signerimpl.cpp verifierimpl.cpp asymmetriccipherimpl.cpp

    53 

    54 LIBRARY euser.lib cryptospi.lib

    55 

    56 // Depends on bigint and padding code

    57 LIBRARY cryptography.lib

    58 //Depends on random server for random number generation

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

    60 <li id="GUID-0C322CF3-197E-5773-A4BB-CDF4943BE588"><p> <codeph>0x1000008d</codeph> identifies

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

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

    63 <li id="GUID-3D1094C3-A59C-58D0-9873-E5A24935785A"><p>It is recommended that

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

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

    66 <li id="GUID-47338BE3-4A8C-5B17-BF37-184F996B0A2C"><p>The project needs to

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

    68 <li id="GUID-1A985A73-A776-5AE1-A4BD-4CC3227CE223"><p>The plug-in needs to

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

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

    71 <li id="GUID-7DEC5079-A30D-5D16-B2EC-FA03605691ED"><p> <codeph>SYSTEMINCLUDE

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

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

    74 </ul> </section>

    75 <section id="GUID-4B845864-BB8E-5207-8210-A3F608DF6E69"><title>How to define

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

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

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

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

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

    81 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" xml:space="preserve">class TCommonCharacteristics

    82     {

    83     public:

    84       ...

    85       TInt32 iInterfaceUID;

    86       TInt32 iAlgorithmUID;

    87       TInt32 iImplementationUID;

    88       const TRomLitC16* iCreatorName;

    89       TBool iIsFIPSApproved;

    90       TBool iIsHardwareSupported;

    91       TUint iMaxConcurrencySupported;

    92       const TRomLitC16* iAlgorithmName;

    93       TInt iLatency;

    94       TInt iThroughput;

    95       };

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

    97 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

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

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

   100 and indicates whether the hash algorithm is an HMAC or not.) </p> <codeblock id="GUID-628BA925-B38B-54F1-B69A-E630E50BB6BF" xml:space="preserve">class THashCharacteristics

   101     {

   102     public:

   103       IMPORT_C TBool IsOperationModeSupported(TUid aOperationMode) const;        

   104         

   105     public:

   106       TCommonCharacteristics cmn;

   107       TUint iBlockSize;

   108       TUint iOutputSize;

   109       const TInt32* iSupportedOperationModes;

   110       TUint iOperationModeNum;

   111       };

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

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

   114 <section id="GUID-CA441465-BDAB-5B7A-B75D-3B877EBE346F"><title>How to implement

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   131     {

   132     const TCharacteristics** ptr(0);

   133     switch (aInterface.iUid)

   134         {

   135     case KHashInterface:

   136         {

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

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

   139         }

   140         break;

   141 

   142     case KRandomInterface:

   143         {

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

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

   146         }

   147         break;

   148   ...

   149   }

   150  return ptr;

   151  }

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

   153 <li id="GUID-CBAC6B6F-30CC-5B57-BF58-A4B14C94A04A"><p>Every plug-in must implement

   154 this function. </p> </li>

   155 <li id="GUID-E263363A-4137-5D7E-8988-4B25E492D39F"><p> <codeph>TUid aInterface</codeph> is

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

   157 <li id="GUID-C7A913A0-DD63-599F-8A34-EA2D7466B050"><p> <codeph>TInt&amp; aNumPlugins</codeph> should

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

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

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

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

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

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

   164 <li id="GUID-DFCA6450-2121-5257-9F26-A11FD8995E5D"><p> <codeph>TInt iAvailableConcurrency;</codeph>  </p> <p>The

   165 number of available resources for processing the operation for the requested

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

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

   168 <li id="GUID-FEA9BD5F-B264-5316-9B15-FD5E0E51CAC2"><p> <codeph>TBool iExclusiveUse;</codeph>  </p> <p>Whether

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

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

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

   172 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

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

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

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

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

   177 no corresponding declarations). </p> <codeblock id="GUID-A6330276-FB1A-5C14-A2BF-5BBCD452614B" xml:space="preserve">typedef void (*CreateRandomFuncL)(MRandom*&amp;, TUid, const CCryptoParams*);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   194 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

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

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

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

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

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

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

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

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

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

   204 <section id="GUID-6ECA8DAB-37C4-5D83-9DBC-10641AA7B636"><title>How to implement

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

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

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

   208 <li id="GUID-83E757D2-E70D-51D3-BF46-53A2F8A8A3E9"><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>

   209 <li id="GUID-ABDD0216-BA34-5DD1-8D07-064B3F1EAB02"><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>

   210 <li id="GUID-5611F951-0471-5A54-BCFE-4DBDB9FF7B1A"><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>

   211 <li id="GUID-C87B0A48-C66F-5E5E-BEA4-BB3F187AA59D"><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>

   212 <li id="GUID-EE95A2C8-4F9C-5052-8709-AD7C1D2A5E6F"><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>

   213 <li id="GUID-717313C9-B2A3-5E78-8A61-A4C3093627BF"><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>

   214 <li id="GUID-8EA174F1-16A5-5364-9672-5AF6644EC19A"><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>

   215 <li id="GUID-3988580D-047C-5492-9493-0A5365FEFB84"><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>

   216 <li id="GUID-05483361-4043-5FC4-A134-AAEA2E31E872"><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>

   217 </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>)

   218 declares the following pure virtual functions: </p> <codeblock id="GUID-6CDA7919-C31E-50EB-8D67-7A142297DBAF" xml:space="preserve">virtual void Close() = 0;

   219 virtual void Reset() = 0;

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

   221 virtual const CExtendedCharacteristics& GetExtendedCharacteristicsL() = 0;

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

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

   224 these functions as follows: </p> <codeblock id="GUID-A18C6FDA-4E3C-570E-B700-7680F91D397D" xml:space="preserve">void CRandomImpl::Close()

   225     {

   226     delete this;

   227     }

   228 

   229 void CRandomImpl::Reset()

   230     { //Not required

   231     }

   232 

   233 const CExtendedCharacteristics* CRandomImpl::GetExtendedCharacteristicsL()

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

   235     // for exclusive use 

   236     {

   237     return CExtendedCharacteristics::NewL(KMaxTInt, EFalse);

   238     }

   239 

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

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

   242     {

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

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

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

   246         {

   247   //Compare implementation UIDs

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

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

   250             {

   251             aPluginCharacteristics = KRandomCharacteristics[i];

   252             break;

   253             }

   254         }

   255     }

   256 

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

   258     {

   259     return NULL;

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

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

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

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

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

   265 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>,

   266 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>,

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

   268 <section id="GUID-661CE3E1-2FAE-58E1-BBB7-2F72AA8714A2"><title>The configuration

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

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

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

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

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

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

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

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

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

   278 </conbody></concept>