--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7.dita Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,278 @@
+<?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" 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"><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"><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>
+<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>
+<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>
+<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>
+<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>
+</ul> </section>
+<section id="GUID-FFA64681-40E3-5DCE-A4EC-3EEC75A35D63"><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" 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"><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"><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"><p>The project needs to
+link against <filepath>cryptospi.lib</filepath>, the CryptoSPI library. </p> </li>
+<li id="GUID-1A985A73-A776-5AE1-A4BD-4CC3227CE223"><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"><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"><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" 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" 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"><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" xml:space="preserve">typedef const TCharacteristics** (*EnumerateCharacteristicsFunc)(TUid, TInt&);</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" xml:space="preserve">EXPORT_C const TCharacteristics** CCryptoPluginEntry::Enumerate(TUid aInterface, TInt& 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"><p>Every plug-in must implement
+this function. </p> </li>
+<li id="GUID-E263363A-4137-5D7E-8988-4B25E492D39F"><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"><p> <codeph>TInt& 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" xml:space="preserve">typedef void (*GetExtendedCharacteristicsFuncL)(TUid, CExtendedCharacteristics*&);</codeblock> <p>Symbian defines 2 extended characteristics: </p> <ul>
+<li id="GUID-DFCA6450-2121-5257-9F26-A11FD8995E5D"><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"><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" xml:space="preserve">typedef void (*CreateRandomFuncL)(MRandom*&, 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*&, 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"><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"><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"><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"><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"><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"><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"><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"><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"><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"><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" 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" 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"><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>
\ No newline at end of file