<?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 reference

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference id="GUID-BAA558C1-8613-43A0-899E-F53DCAA68F4B" xml:lang="en"><title>APIs

for Accessing Random Number Generator</title><abstract><p>Symbian platform provides different APIs by means of which the <xref href="GUID-8290AAF0-577C-51D2-8AC1-0D37A10F45CB.dita">Cryptographically Secure

Random Number Generator in Kernel</xref> (CSPRNG) implemented in the kernel

can be accessed.</p><p>The following table lists the various APIs with their

descriptions:</p></abstract><prolog><metadata><keywords/></metadata></prolog><refbody><table id="GUID-48D09C12-1BE8-42BC-8140-18F1332A1254">

<tgroup cols="2"><colspec colname="col1" colwidth="0.88*"/><colspec colname="col2" colwidth="1.12*"/>

<thead>

<row>

<entry valign="top">Random Number Generator APIs</entry>

<entry valign="top">Description</entry>

</row>

</thead>

<tbody>

<row>

<entry nameend="col2" namest="col1"><b>Kernel-side access</b>: Base porters

can use 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-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60EC16BC-1A7E-3EC1-9A2A-3019B894BE6E"><apiname>Kern::SecureRandom()</apiname></xref> functions

to obtain random data from the kernel's CSPRNG. For information the use of

these functions, see <xref href="GUID-8290AAF0-577C-51D2-8AC1-0D37A10F45CB.dita">CSPRNG

Implementation in Kernel</xref>.</entry>

</row>

<row>

<entry><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></entry>

<entry>Returns 32 bits of random data from the CSPRNG. <p>Use this function

to get high-quality random number which may not be cryptographically secure.</p></entry>

</row>

<row>

<entry><xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60EC16BC-1A7E-3EC1-9A2A-3019B894BE6E"><apiname>Kern::SecureRandom()</apiname></xref></entry>

<entry>Returns random data of length specified in the descriptor passed as

parameter to this function. <p>This function is used to get cryptographically

secure random numbers. If the returned data is not guaranteed to be cryptographically

secure, the function returns a KErrNotReady argument along with random data

that can be used for non-cryptographic purposes.</p></entry>

</row>

<row>

<entry nameend="col2" namest="col1"><b>User-side access to the Kernel APIs</b>:

Developers can use <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> and <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-5AE91EA6-A4D7-308C-B5D6-23E2409AF15E"><apiname>Math::RandomL()</apiname></xref> that

call the Kernel's Random APIs to get random data. For information on how these

functions are used, see <xref href="GUID-8290AAF0-577C-51D2-8AC1-0D37A10F45CB.dita">CSPRNG

Implementation in Kernel</xref>.</entry>

</row>

<row>

<entry><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></entry>

<entry>Internally calls <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> and returns random

data of length specified in the descriptor passed as parameter to this function

(<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>). The random data returned may not be cryptographically

secure.</entry>

</row>

<row>

<entry><xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-5AE91EA6-A4D7-308C-B5D6-23E2409AF15E"><apiname>Math::RandomL()</apiname></xref></entry>

<entry>Internally calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60EC16BC-1A7E-3EC1-9A2A-3019B894BE6E"><apiname>Kern::SecureRandom()</apiname></xref> and returns

random data of length specified in the descriptor passed as parameter to this

function (<xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita#GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A/GUID-5AE91EA6-A4D7-308C-B5D6-23E2409AF15E"><apiname>Math::RandomL()</apiname></xref>). </entry>

</row>

<row>

<entry nameend="col2" namest="col1"><b>Access from the OS Security Package

(TRandom)</b>: <p>The <xref href="GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC.dita"><apiname>TRandom</apiname></xref> functions provide means for

the legacy crypto components ( <filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>)

to access the CSPRNG through CryptoSPI and generate random numbers. For information

on the legacy crypto components, see <xref href="GUID-3FB8AC96-209B-5B1E-8139-BA2D858CBF2F.dita">CryptoSPI

Overview (weak build)</xref>. For information on <xref href="GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC.dita"><apiname>TRandom</apiname></xref>,

see <xref href="GUID-66BBA81D-2488-50B8-8822-43AAAA139DDE.dita">Random Number Generation

Overview</xref>.<note>If you do not wish to use <xref href="GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC.dita"><apiname>TRandom</apiname></xref> classes

for random number generation, you can directly use the <xref href="GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4.dita"><apiname>CRandom</apiname></xref> class

for accessing the CSPRNG.</note></p></entry>

</row>

<row>

<entry><xref href="GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC.dita#GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC/GUID-82D3EB95-4DA0-3C99-B03C-49D3A54054A1"><apiname>TRandom::RandomL()</apiname></xref></entry>

<entry>Internally calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60EC16BC-1A7E-3EC1-9A2A-3019B894BE6E"><apiname>Kern::SecureRandom()</apiname></xref> (by means

of CryptoSPI) for accessing the CSPRNG and generating random numbers. It does

not return any argument indicating whether the data returned is cryptographically

secure.</entry>

</row>

<row>

<entry><xref href="GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC.dita#GUID-5B1A7F31-2C04-3E57-BD09-B0EF3AAED1EC/GUID-0C7F0D0C-8F02-3683-A9CE-96C2EA1A3BFB"><apiname>TRandom::SecureRandomL()</apiname></xref></entry>

<entry>Internally calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60EC16BC-1A7E-3EC1-9A2A-3019B894BE6E"><apiname>Kern::SecureRandom()</apiname></xref> (by means

of CryptoSPI) for accessing the CSPRNG and generating random numbers.  <p>This

function returns cryptographically secure random data. If the returned data

is not guaranteed to be cryptographically secure, the function returns a KErrNotSecure

argument along with random data that can be used for non-cryptographic purposes.</p></entry>

</row>

<row>

<entry nameend="col2" namest="col1"><b>Access from the OS Security Package

(CRandom)</b>: <p> <xref href="GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4.dita"><apiname>CRandom</apiname></xref> is a CryptoSPI class that provides

functions to access CSPRNG and generate random data. For information on generating

random data using <xref href="GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4.dita"><apiname>CRandom</apiname></xref>, see <xref href="GUID-0CD273A2-434C-52E0-B840-CCF24B2853B8.dita">Generating

Random Bytes</xref>.</p></entry>

</row>

<row>

<entry><xref href="GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4.dita#GUID-CD88247C-561B-3AB4-BF77-AFD322F860A4/GUID-F251BF16-E212-3595-9FE8-C7BC754972E1"><apiname>CRandom::GenerateRandomBytesL()</apiname></xref></entry>

<entry>Internally calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60EC16BC-1A7E-3EC1-9A2A-3019B894BE6E"><apiname>Kern::SecureRandom()</apiname></xref> for accessing

the CSPRNG and generating cryptographically secure random numbers.  f the

returned data is not guaranteed to be cryptographically secure, the function

returns a KErrNotSecure argument along with random data that can be used for

non-cryptographic purposes.</entry>

</row>

</tbody>

</tgroup>