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.
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 .
The CryptoSpi namespace is defined for all CryptoSPI classes to differentiate them from the legacy APIs with the same names.
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:
Symmetric ciphers - The following symmetric algorithms are supported:
|Symmetric algorithm||Type||Specified in:|
AES (Advanced Encryption Standard)
DES (Data Encryption Standard)
3DES (Triple Data Encryption Standard)
ARC4 ('alleged' RC4)
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:
Hash algorithms - The following hash algorithms are supported:
Hashes in HMAC mode
HMAC mode is specified in RFC 2104
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() .
Symbian platform provides default software implementations of the following operation modes:
They are specified in NIST Special Publication 800-38A .
Symbian platform supports the following padding modes:
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() .
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.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.