--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-BAA558C1-8613-43A0-899E-F53DCAA68F4B.dita	Tue Mar 30 11:56:28 2010 +0100
@@ -0,0 +1,111 @@
+<?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>
\ No newline at end of file