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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE reference

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

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

    13 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

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

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

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

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

    18 <thead>

    19 <row>

    20 

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

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

    23 </row>

    24 </thead>

    25 <tbody>

    26 <row>

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

    28 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

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

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

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

    32 </row>

    33 <row>

    34 <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>

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

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

    37 </row>

    38 <row>

    39 <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>

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

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

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

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

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

    45 </row>

    46 <row>

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

    48 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

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

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

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

    52 </row>

    53 <row>

    54 

    55 <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>

    56 <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

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

    58 (<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

    59 secure.</entry>

    60 </row>

    61 <row>

    62 <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>

    63 <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

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

    65 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>

    66 </row>

    67 <row>

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

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

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

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

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

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

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

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

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

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

    78 </row>

    79 <row>

    80 <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>

    81 <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

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

    83 not return any argument indicating whether the data returned is cryptographically

    84 secure.</entry>

    85 </row>

    86 <row>

    87 <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>

    88 <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

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

    90 function returns cryptographically secure random data. If the returned data

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

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

    93 </row>

    94 <row>

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

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

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

    98 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

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

   100 </row>

   101 <row>

   102 <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>

   103 <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

   104 the CSPRNG and generating cryptographically secure random numbers.  f the

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

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

   107 non-cryptographic purposes.</entry>

   108 </row>

   109 </tbody>

   110 </tgroup>

   111 </table></refbody></reference>