<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-8290AAF0-577C-51D2-8AC1-0D37A10F45CB" xml:lang="en"><title>CSPRNG

Implementation in Kernel</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-6125753A-78E8-4C9F-B25C-B1285A50AE9A"><title>Purpose</title> <p>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).</p><p>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 <xref href="GUID-BAA558C1-8613-43A0-899E-F53DCAA68F4B.dita">APIs for Accessing Random

Number Generator</xref>.</p> </section>

<section id="GUID-B5BD3E1A-AFBB-5526-B5EA-8FA51A17E596-GENID-1-12-1-17-1-1-11-1-5-1-19-1-2-2"><title>Description</title> <p>The

CSPRNG uses Hash_DRBG algorithm to generate pseudo-random number. Hash_DRBG

algorithm is a standard recommended by National Institute of Secure Technology

(<xref href="http://csrc.nist.gov/publications/nistpubs/800-90/SP800-90revised_March2007.pdf" scope="external">NIST SP800-90</xref>), 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. </p><p>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 <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-85F0FCA1-1998-3863-94E7-1E9D4496E682"><apiname>Kern::RandomSalt</apiname></xref>. </p> </section>

<section id="GUID-4E6F8E44-43E9-473B-8733-029FD3036224"><title>Generating

Random Data</title> <ul>

<li><p><b>To generate random numbers on the user side</b>: Applications can

call <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-9D7451C0-A293-3DCB-AF73-69CEB41AF13D"><apiname>Math::Random</apiname></xref> and its overloaded functions, which call <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-FA565586-92EB-3727-9824-FCD5ED341E58"><apiname>Kern::Random</apiname></xref> to

generate a random number. The overloaded functions of <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita"><apiname>Math</apiname></xref> class

are listed below: </p> <ul>

<li id="GUID-49840D10-1AA9-5B1E-89F2-EE76AA6EE168"><p> <codeph>TUint32 Math::Random()</codeph>  </p> </li>

<li id="GUID-44B4E31A-F2CD-57B1-841C-5D49FB31F761"><p> <codeph>void Math::Random(TDes8&amp;

aRandomValue)</codeph>  </p> </li>

<li id="GUID-A44D2225-FD37-58F0-8371-93BE55FE0B14"><p> <codeph>TUint32 Math::RandomL()</codeph>  </p> </li>

<li id="GUID-CDA30955-23FE-574B-9C9D-EF60905AE143"><p> <codeph>void Math::RandomL(TDes8&amp;

aRandomValue)</codeph>  </p> </li>

</ul></li>

<li><p><b>To generate random numbers on the kernel side</b>: Random numbers

can be accessed using the following methods: </p> <ul>

<li id="GUID-7B3E4D44-394F-5D51-8DA1-DC7515C6BD14"><p> <codeph>EXPORT_C TInt

Kern::SecureRandom(TDes8&amp; aRandomValue)</codeph>  </p> </li>

<li id="GUID-8DD4B45E-4659-5F72-92CB-6774C8CCE12F"><p> <codeph>EXPORT_C TUint32

Kern::Random()</codeph>  </p> </li>

</ul></li>

</ul><note><p>If the generated random number is not secure, the <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita"><apiname>Kern</apiname></xref> and <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita"><apiname>Math</apiname></xref> random

functions return appropriate error codes or leave. </p><p>The <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-FA565586-92EB-3727-9824-FCD5ED341E58"><apiname>Kern::Random</apiname></xref> and <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-9D7451C0-A293-3DCB-AF73-69CEB41AF13D"><apiname>Math::Random</apiname></xref> are

the only functions that do not return any error codes.</p></note> </section>

<example><p>The following examples show the use of the various user-side APIs

to generate a random number:</p><ul>

<li><p> Example of <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-F37E64ED-4DE4-3F0D-9BE2-756CF9D00B13"><apiname>Math::RandomL(TDes8&amp;)</apiname></xref> </p><codeblock xml:space="preserve">const TInt KRandomBufferSize = 1024;

TBuf8 <KRandomBufferSize> buffer(KRandomBufferSize);

Math::RandomL(buffer); // The function will leave if the number is not secure</codeblock></li>

<li><p>Example of <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-4B6E5650-682D-32FA-87E8-B64DBCB74BC5"><apiname>Math::RandomL(</apiname></xref>)</p><codeblock xml:space="preserve">TUint randomValue = Math::RandomL();// The function will leave if the number is not secure</codeblock></li>

<li><p>Example of <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-0B4A64E4-7EC3-300F-ACA0-7F53AAEF7066"><apiname>Math::Random()</apiname></xref></p><codeblock xml:space="preserve">TUint randomValue = Math::Random();</codeblock></li>

</ul><p>The following examples show the use of the kernel side APIs to generate

a random number:</p><ul>

<li><p> Example of <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-EA575BCE-D227-3D4A-8581-542DFAFB4E6C"><apiname>Kern::SecureRandom(TDes8&amp;)</apiname></xref> </p><codeblock xml:space="preserve">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</codeblock></li>

<li><p>Example of <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-13B7C085-495E-36BB-97CE-141A8E5776B6"><apiname>Kern::Random()</apiname></xref></p><codeblock xml:space="preserve">TUint randomValue = Kern::Random();</codeblock></li>

</ul></example>

<section id="GUID-157FE439-6C53-407A-8909-2CB88E89857C"><title>Providing Entropy</title><p>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:</p><ul>

<li><p>Independent of user input. For example, hardware RNG oscillator and

specific interrupts. </p></li>

<li><p>Influenced by user input. For example, audio (microphone input), video

(camera input), keypad input, touch screen input and accelerometer.</p></li>

</ul><p>The kernel provides various functions to allow entropy data to be

contributed to the CSPRNG. The functions are as follows:</p><ul>

<li><p><xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-5AFC49C0-CDAB-317E-B88A-BD1A4C9307CB"><apiname>Kern::RandomSalt(TUint32 aEntropyData, TUint aBitsOfEntropy)</apiname></xref>:

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).</p></li>

<li><p><xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-35F5D818-0C74-3C6E-8EF1-7EF49BB43705"><apiname>Kern::RandomSalt(TUint64 aEntropyData, TUint aBitsOfEntropy)</apiname></xref>:

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.</p></li>

<li><p><xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-1E340F3C-DCE5-3599-A0B9-29E9419807E9"><apiname>Kern::RandomSalt(const TUint8* aEntropyData, TUint aEntropyDataLength,

TUint aBitsOfEntropy)</apiname></xref>: Allows entropy data larger than 64 bits to

be contributed to the CSPRNG. This function cannot be called from an ISR.</p></li>

<li><p><xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-C46E48EE-6F4A-3A61-A3C9-84B145119541"><apiname>Interrupt::AddTimingEntropy()</apiname></xref>: 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 <b>Interrupt

Service Routine (ISR) implementation</b> in <xref href="GUID-2E42E7EA-FED8-522C-8A5F-F65D799476C9.dita">Keyboard

Driver Implementation Tutorial</xref>.</p></li>

</ul><note>In all these cases, <codeph>aBitsOfEntropy</codeph> 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.</note></section>