CryptoSPI Overview (weak build)

Purpose

This is an overview of the weak CryptoSPI APIs. An overview and other documents for the strong CryptoSPI APIs are available in the Security Supplement, which is delivered to device creators with the CBR.

Introduction

CryptoSPI (cryptospi.dll) is a framework for implementing cryptographic algorithms, hash algorithms and random number generation. It allows alternative implementations to be added by Symbian platform device creators as plug-in DLLs.

Weak and strong builds

The cryptography APIs are subject to export control regulations. The export of cryptography refers to the transfer from one country to another of technology related to cryptography. Export control regulations are for national security considerations.

Export control applies to key sizes that are greater than a size specified by the UK Government. Currently, symmetric algorithms with keys greater than 56 bits and asymmetric algorithms with keys greater than 512 bits are export controlled. To comply with government export control rules, the Cryptography library is delivered in two builds:

• A weak build

  The weak build (weak_cryptography.dll) includes cryptography algorithms that are not export controlled. The weak build rejects requests to apply an encryption scheme with key sizes greater than 56 bits for symmetric algorithms and 512 bits for asymmetric algorithms.

• A strong build

  The strong build (strong_cryptography.dll) includes cryptography algorithms that are export controlled.

Note: The API guide and other documentation for cryptography is broken up in the same way as the cryptography library. This document provides information on the weak build. It also gives a brief summary of the algorithms provided in the strong build. The strong cryptography API guide and other documentation is not available from the Symbian Developer Library. It is delivered to device creators with the CBR.

Architectural relationships

Before the introduction of CryptoSPI, features such as cryptographic algorithms, hash algorithms and random number generation were provided by the Symbian platform in cryptography.dll, hash.dll and random.dll.

softwarecrypto.dll is a plug-in module (implemented in the Symbian platform) 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 plug-in module provided by device creators. 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 in softwarecrypto.dll:

This section includes summary details of the following (For more information on the strong APIs, see the Security Supplement, which is delivered to device creators with the CBR):

• cryptographic algorithms

• hash algorithms

• random number generator

Cryptographic algorithms

Cryptographic algorithms allow data to be encrypted and decrypted. They include:

• Symmetric ciphers — algorithms that require communicating parties to hold a shared secret. They are fast and are used for the transmission of bulk data.

• Asymmetric ciphers — algorithms which have two keys, one private to the keys' owner and one which can be published. They are slow compared to symmetric ciphers and are used to exchange a symmetric key before transmission of data encrypted using that key.

The Cryptography algorithms are part of the strong build. To access details of how to implement them you need to access the Security Supplement, which is delivered to device creators with the CBR.

Hash algorithms

Hash algorithms compact a message down to a short series of bytes from which it is impossible to regenerate the message. They are used with an asymmetric cipher to generate signatures.

The following hash algorithms are supported:

Hashes in HMAC mode

• MD2

• MD4

• MD5

• SHA1

• SHA-224

• SHA-256

• SHA-384

• SHA-512

HMAC mode is specified in RFC 2104.

Random Number Generator (RNG)

RNG is the basis for the cryptographic key generation. It uses the RANROT algorithm seeded by random data available on the target hardware (for example free running counters available on ARM processers).

Supporting APIs

• Password Based Encryption (PBE) — provides an API to encrypt and decrypt data with a user-supplied password

• Padding — is extra bits concatenated with a key, password, or plaintext to make their length equal to the block size. It defines the way blocks are filled with data when the data to be encrypted is smaller than the block size. Padding is added at encryption and checked on decryption.

• Big integers — arbitrarily large integers.

  Note that although some functions are exported, the intent is that big integers are only for use by the Cryptography library and not by application code. Big integers are implemented in cryptography.dll.

Implementing CryptoSPI algorithms

The guide to CryptoSPI is not publicly available, but the following documents show how to use CryptoSPI to generate random numbers and create a hash:

• Generating random bytes