How to create a CryptoSPI plug-in

Introduction

Note: this document is intended for device manufacturers.

The purpose of a CryptoSPI plug-in is to implement one or more cryptographic algorithms.

Symbian provides a plug-in called softwarecrypto.dll 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 softwarecrypto.dll is located under src/common/generic/security/cryptospi/source/softwarecrypto/.

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.

• Create the MMP file.

• Define the characteristics of the algorithms.

• Implement all or a subset of the functions defined in pluginentrydef.h.

• Implement the MPlugin-derived objects.

• Update the ROM configuration file.

How to create the MMP file

See for instance src/common/generic/security/cryptospi/group/softwarecrypto.mmp.

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

Key points:

• 0x1000008d identifies the DLL as static (not polymorphic or an ECOM plug-in) and 0x102835C2 is unique to this plug-in, allocated by Symbian Signed.

• It is recommended that plug-ins have ALL capabilities because this ensures that they can be loaded by client applications with any capabilities.

• The project needs to link against cryptospi.lib, the CryptoSPI library.

• The plug-in needs to link against cryptography.lib because big integers (RInteger) are implemented in cryptography.dll.

• SYSTEMINCLUDE \epoc32\include\cryptospi allows code to #include the CryptoSPI header files, which are all exported to epoc32\include\cryptospi\.

How to define the algorithm's characteristics

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 CryptoSpi::TCommonCharacteristics:

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;
      };

Other characteristics are specific to a particular interface. For each interface type, a T class is defined as an aggregation of a TCommonCharacteristics object and some additional characteristics particular to that interface. For instance, THashCharacteristics includes a block size, output size and operation mode. (The operation mode can be either KHashMode or KHmacMode, and indicates whether the hash algorithm is an HMAC or not.)

class THashCharacteristics
    {
    public:
      IMPORT_C TBool IsOperationModeSupported(TUid aOperationMode) const;        
        
    public:
      TCommonCharacteristics cmn;
      TUint iBlockSize;
      TUint iOutputSize;
      const TInt32* iSupportedOperationModes;
      TUint iOperationModeNum;
      };

All the data types relating to characteristics are defined in plugincharacteristics.h.

For an example, see src/common/generic/security/cryptospi/source/softwarecrypto/pluginconfig.h.

How to implement the framework code

Plug-in modules must implement a defined set of functions exported at defined ordinals. The function prototypes and the ordinals (see TPluginEntryOrdinal) are defined in pluginentrydef.h. 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 softwarecryptoU.def exports file, which can be found in the EABI and BWINS directories in the CryptoSPI source code.

Minimally, the plug-in DLL must implement the function exported at ordinal 1, whose prototype is:

typedef const TCharacteristics** (*EnumerateCharacteristicsFunc)(TUid, TInt&);

and at least one of the algorithm factory functions. See for example class CCryptoPluginEntry (pluginentry.h / pluginentry.cpp).

If the plug-in DLL does not support a particular algorithm, the ABSENT keyword should be used in its .def file to ensure any subsequent exports are at the correct ordinals.

Querying the characteristics of plug-ins

CryptoSPI builds up a list of the characteristics of all the plug-in DLLs by calling the function exported at ordinal 1 (EEnumerateCharacteristicsOrdinal) for each DLL and for each interface type. Here is an example implementation:

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;
 }

Key points:

• Every plug-in must implement this function.

• TUid aInterface is the interface UID, as defined in CryptoSpi::KInterfacesUids.

• TInt& aNumPlugins should be set to the number of algorithms of that interface type implemented by the plug-in.

Extended characteristics

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 CryptoSpi::CCryptoBase::GetExtendedCharacteristicsL().

The function exported at ordinal 2 has this prototype:

typedef void (*GetExtendedCharacteristicsFuncL)(TUid, CExtendedCharacteristics*&);

Symbian defines 2 extended characteristics:

• TInt iAvailableConcurrency;

  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.

• TBool iExclusiveUse;

  Whether it is possible for the application to reserve exclusive use of hardware resources used by the plug-in.

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 CryptoSpi::CExtendedCharacteristics::AddCharacteristicL().

Algorithm instantiation

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 ECreateSymmetricKeyGeneratorOrdinal and ECreateAsyncSymmetricKeyGeneratorOrdinal have no corresponding declarations).

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*);

Clients instantiate algorithms by calling one of the CryptoSPI factory methods, for instance CHashFactory::CreateHashL(). All CryptoSPI factory methods take a CCryptoParams 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.

The data type of each parameter can be integer (TInt), big integer (RInteger), or 8/16 bit descriptor. Additional data types could be added in future, by extending the TParamType enum in CCryptoParam and deriving a class from CCryptoParam, but this is unlikely to be necessary.

How to implement the MPlugin-derived class

All concrete algorithm classes are derived from one of the abstract base classes listed below, which are in turn all derived from MPlugin.

• Random (MRandom /MAsyncRandom)

• Hash (MHash /MAsyncHash)

• Symmetric cipher (MSymmetricCipher /MAsyncSymmetricCipher)

• Asymmetric cipher (MAsymmetricCipher /MAsyncAsymmetricCipher)

• Signer (MSigner /MAsyncSigner)

• Verifier (MVerifier /MAsyncVerifier)

• Key agreement (MKeyAgreement /MAsyncKeyAgreement)

• Key pair generator (MKeyPairGenerator /MAsyncKeyPairGenerator)

• Key generator (MSymmetricKeyGenerator /MAsyncSymmetricKeyGenerator)

MPlugin (cryptoplugin.h) declares the following pure virtual functions:

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;

For example, the random number generator plug-in implemented in softwarecrypto.dll implements these functions as follows:

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;
    }

The main purpose of MPlugin::Reset() is to reset the hardware, so is usually not relevant to a software-only implementation. GetExtension() is intended for internal use, and may be removed from the API in future.

These functions are called through the client API to CryptoSPI, in other words CCryptoBase and the various classes derived from it, in this case, CRandom. For instance when the client calls CCryptoBase::GetCharacteristicsL(), this calls GetCharacteristicsL() in the plug-in, or calling CRandom::GenerateRandomBytesL(), calls GenerateRandomBytesL() in the plug-in.

The configuration file

The set of available plug-ins is listed in the configuration file z:\resource\cryptospi\plug-ins.txt. 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 z:\sys\bin. The configuration file must be on the Z: 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 (CLegacySelector) loads plug-in DLLs as required.