CryptoSPI Overview

Introduction

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.

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	FIPS-197
  DES (Data Encryption Standard)	Block cipher	FIPS 46-3
  3DES (Triple Data Encryption Standard)	Block cipher	FIPS 46-3
  RC2-128	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
  DSA	Signing data Key pair generation	FIPS 186-2 CR1
  Diffie Hellman	Key agreement Key pair generation	PKCS#3

• Hash algorithms - The following hash algorithms are supported:

  Hash algorithms	Specified in
  MD2	RFC 1319
  MD4	RFC 1320
  MD5	RFC 1321
  SHA1	FIPS 180-1 and RFC 3174
  SHA-224	FIPS 180-2
  SHA-256	FIPS 180-2
  SHA-384	FIPS 180-2
  SHA-512	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().

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.

Plug-ins

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.