Collapse all Symbian^3 Product Developer Library

CSPRNG Implementation in Kernel

Purpose

The Cryptographically Secure/Strong Pseudo-Random Number Generator (CSPRNG) generates random numbers that are cryptographically secure. The CSPRNG generates a sequence of numbers that approximates the properties of random numbers. The strength of CSPRNG not only depends on the generation algorithm, but also on the strength of entropy (the degree of uncertainty in the random number or the extent to which the number is random).

In Symbian platform, the CSPRNG is implemented in the kernel. This provides the kernel and user-level threads and processes easy access to secure random numbers. For an overview of the various APIs by means of which the CSPRNG can be accessed, see APIs for Accessing Random Number Generator.

Description

The CSPRNG uses Hash_DRBG algorithm to generate pseudo-random number. Hash_DRBG algorithm is a standard recommended by National Institute of Secure Technology (NIST SP800-90), which uses cryptographic hash functions (SHA-256) to generate random numbers. The strength of CSPRNG not only depends on the generation algorithm, but also on the strength of entropy input.

A key process in the generation of random numbers is entropy accumulation. During initialization of the CSPRNG, it is critical to accumulate entropy from the entropy sources. Entropy accumulation is the process by which a CSPRNG acquires a new unpredictable internal state. The entropies are collected into a hash-based pool using Kern::RandomSalt.

Generating Random Data

To generate random numbers on the user side: Applications can call Math::Random and its overloaded functions, which call Kern::Random to generate a random number. The overloaded functions of Math class are listed below:
- TUint32 Math::Random()
- void Math::Random(TDes8& aRandomValue)
- TUint32 Math::RandomL()
- void Math::RandomL(TDes8& aRandomValue)
To generate random numbers on the kernel side: Random numbers can be accessed using the following methods:
- EXPORT_C TInt Kern::SecureRandom(TDes8& aRandomValue)
- EXPORT_C TUint32 Kern::Random()

Note:

If the generated random number is not secure, the Kern and Math random functions return appropriate error codes or leave.

The Kern::Random and Math::Random are the only functions that do not return any error codes.

The following examples show the use of the various user-side APIs to generate a random number:

Example of Math::RandomL(TDes8&)

const TInt KRandomBufferSize = 1024;
TBuf8 <KRandomBufferSize> buffer(KRandomBufferSize);
Math::RandomL(buffer); // The function will leave if the number is not secure

Example of Math::RandomL()

TUint randomValue = Math::RandomL();// The function will leave if the number is not secure

Example of Math::Random()
```
TUint randomValue = Math::Random();
```

The following examples show the use of the kernel side APIs to generate a random number:

Example of Kern::SecureRandom(TDes8&)

const TInt KRandomBufferSize = 1024;
TBuf8 <KRandomBufferSize> buffer(KRandomBufferSize);
Tint err = Kern::SecureRandom(buffer); // Number is secure if err is KErrNone else the number is not secure

Example of Kern::Random()
```
TUint randomValue = Kern::Random();
```

Providing Entropy

The quality of the output of the CSPRNG can be improved by providing it with data known to be random. Such data is referred to as entropy data. Entropy data sources can either be:

Independent of user input. For example, hardware RNG oscillator and specific interrupts.
Influenced by user input. For example, audio (microphone input), video (camera input), keypad input, touch screen input and accelerometer.

The kernel provides various functions to allow entropy data to be contributed to the CSPRNG. The functions are as follows:

Kern::RandomSalt(TUint32 aEntropyData, TUint aBitsOfEntropy): Allows entropy data up to 32 bits in length to be contributed to the CSPRNG. This function is low-latency and safe to be called from an Interrupt Service Routine (ISR).
Kern::RandomSalt(TUint64 aEntropyData, TUint aBitsOfEntropy): Allows entropy data up to 64 bits in length to be contributed to the CSPRNG. This function is low-latency and safe to be called from an ISR.
Kern::RandomSalt(const TUint8* aEntropyData, TUint aEntropyDataLength, TUint aBitsOfEntropy): Allows entropy data larger than 64 bits to be contributed to the CSPRNG. This function cannot be called from an ISR.
Interrupt::AddTimingEntropy(): This function allows the timing of an interrupt to be contributed as entropy data, the highest resolution timer available is automatically used for the timestamp. This function can only be called from an ISR. For an example of its usage, see the section Interrupt Service Routine (ISR) implementation in Keyboard Driver Implementation Tutorial.

Note: In all these cases, aBitsOfEntropy is an estimate of the number of bits of entropy contained in the sample and not necessarily the length of the sample. Failure to provide accurate entropy estimations may affect the quality of the CSPRNG’s output.

Parent topic: Concepts