CryptoSPI Overview


CryptoSPI ( cryptospi.dll ) 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.

CryptoSPI also provides a framework that allows licensees and partners to implement additional cryptographic algorithms as plug-ins to CryptoSPI.

The benefits of CryptoSPI are:

  • 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.

  • Its architecture allows new algorithms or modes of operation to be added by licensees without impacting the existing APIs or client code.

  • The legacy cryptography libraries ( cryptography.dll , hash.dll and random.dll ) 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.

  • CryptoSPI adds support for non-extractable keys, which may be used to protect sensitive or high-value content.

  • 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.

Architectural relationships

CryptoSPI was introduced in Symbian^3. Before Symbian^3, cryptographic algorithms, hash algorithms and random number generation were implemented by Symbian in cryptography.dll , hash.dll and random.dll . 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.

softwarecrypto.dll 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 ( cryptography.dll , hash.dll and random.dll ). The legacy APIs have been re-implemented internally to use the new framework via shim classes. hardwarecrypto.dll is an arbitrary name used in the diagram to represent a licensee-provided plug-in module. The plug-ins and cryptospi.dll have a dependency on cryptography.dll because it implements big integers .

Figure 1. CryptoSPI dependencies

API summary

The CryptoSpi namespace is defined for all CryptoSPI classes to differentiate them from the legacy APIs with the same names.

CryptoSPI scope

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 softwarecrypto.dll

This section includes summary details of the following:

  • cryptographic algorithms

  • hash algorithms.

  • random number generator

Cryptographic algorithms

  • Symmetric ciphers - The following symmetric algorithms are supported:

    Symmetric algorithm Type Specified in:

    AES (Advanced Encryption Standard)

    Block cipher


    DES (Data Encryption Standard)

    Block cipher

    FIPS 46-3

    3DES (Triple Data Encryption Standard)

    Block cipher

    FIPS 46-3


    Block cipher

    RFC 2268

    ARC4 ('alleged' RC4)

    Stream cipher

    The internet and a posting to sci.crypt in 1994.

    Note: 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.

    Note : Until Symbian^3, the classes implementing the symmetric and asymmetric ciphers were provided in cryptography.dll .

  • Asymmetric ciphers - The following asymmetric algorithms are supported:

    Asymmetric algorithm What is's used for Specified in:

    RSA PKCS#1 v1.5

    Signing data

    Key pair generation

    PKCS#1 v1.5


    Signing data

    Key pair generation

    FIPS 186-2 CR1

    Diffie Hellman

    Key agreement

    Key pair generation


  • Hash algorithms - The following hash algorithms are supported:

    Hash algorithms

    Specified in


    RFC 1319


    RFC 1320


    RFC 1321


    FIPS 180-1 and RFC 3174


    FIPS 180-2


    FIPS 180-2


    FIPS 180-2


    FIPS 180-2

  • Hashes in HMAC mode

    • MD2

    • MD4

    • MD5

    • SHA1

    • SHA-224

    • SHA-256

    • SHA-384

    • SHA-512

    HMAC mode is specified in RFC 2104

Instantiating algorithms

Clients request cryptographic algorithms using static factory functions.

For instance, to create a hash algorithm, use the generic hash factory function CryptoSpi::CHashFactory::CreateHashL() , specifying the UID of the required algorithm. UIDs are defined in cryptospidef.h , for instance KMd2Uid , KMd5Uid , KSha1Uid . CryptoSPI uses a plug-in selector 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 ECreateHashOrdinal , to instantiate a hash object, which is returned to the caller.

Operation and padding modes

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, C3DESEncryptor and C3DESDecryptor , CryptoSPI implements a single, generic symmetric cipher class, CryptoSpi::CSymmetricCipher . The characteristics of the algorithm, for instance whether it does encryption or decryption, the operation mode for block ciphers ( KOperationModeECB , KOperationModeCBC etc.), and the padding mode ( KPaddingModeSSLv3 , KPaddingModePKCS7 etc.) are all passed by the client to the factory function as UIDs — see CryptoSpi::CSymmetricCipherFactory::CreateSymmetricCipherL() .

The client can switch the algorithm between modes by setting a flag, see for example CSymmetricCipherBase::SetCryptoModeL() , CSymmetricCipherBase::SetPaddingModeL() and CSymmetricCipherBase::SetOperationModeL() .

  • Operation modes

    Symbian platform provides default software implementations of the following operation modes:

    • ECB

    • CBC

    • CTR (counter)

    They are specified in NIST Special Publication 800-38A .

  • Padding modes

    Symbian platform supports the following padding modes:

    • SSLv3-style padding

    • PKCS#7-style padding

    • PKCS#1 v1.5 Encryption-style padding

    • PKCS#1 v1.5 Signature-style padding

Asynchronous operation and cancellation

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 Cancel() function.

Note : Symbian's software plug-in module ( softwarecrypto.dll ) only implements the synchronous interfaces.


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 ( Z:\resource\cryptospi\plug-ins.txt ). CryptoSPI will only load plugins stored in ROM ( Z:\sys\bin\ ), so plug-in modules cannot be added by third parties after-market.

cryptospi.dll and all plug-ins have ALL capabilities, which ensures that they can be loaded by client applications with any capabilities.

The abstract base class for all cryptographic plug-ins is CryptoSpi::MPlugin() .

See also: How to create a CryptoSPI plugin .

UIDs and plug-in characteristics

Plug-ins are identified by three UIDs:

  • the interface supported, for instance hash ( KHashInterfaceUid ),

  • the algorithm implemented, for instance MD2 ( KMd2Uid ), and

  • the unique implementation ID.

These three UIDs are part of the plug-in's characteristics . 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 common characteristics and are defined in CryptoSpi::TCommonCharacteristics() . 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 CryptoSpi::TSymmetricCipherCharacteristics() , that have a TCommonCharacteristics data member. Plug-in characteristics can be retrieved using CCryptoBase::GetCharacteristicsL() .

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

Selection rules

Symbian has implemented a plug-in selector, CryptoSpi::CLegacySelector() , which is used both by the legacy API and by default by CryptoSPI to select algorithms implemented in softwarecrypto.dll . 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.

As an alternative to using the default selector, clients can specify a rule-based selector ( CryptoSpi::CRuleSelector() ). This causes CryptoSPI to re-generate the list of plug-ins, according to a set of selection rules. The API is described in How to use a rule-based selector .

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.

Related information
Hash (message digest) algorithms