<?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>
</table></refbody></reference>