CryptoSPI +Overview

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

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.

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.