1 /*

     2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * (c) 1999-2003 Symbian Ltd

    16 *

    17 */

    18 

    19 

    20 

    21 

    22 

    23 

    24 

    25 /**

    26  @file

    27  @publishedAll

    28  @released

    29 */

    30 

    31 #ifndef __RANDOM_H__

    32 #define __RANDOM_H__

    33 

    34 #include <e32base.h>

    35 

    36 class CRandom : public CBase

    37 /**

    38  * @publishedAll

    39  * @released

    40  */

    41 	{

    42 public:

    43 

    44 	/**

    45 	 * Implementations of this method should fill the passed

    46 	 * buffer with securely generated random data up to the 

    47 	 * current length, discarding any current contents.

    48 	 *

    49 	 * @param aDest The buffer in to which to write random data.

    50 	 *

    51 	 */

    52 	virtual void GenerateBytesL(TDes8& aDest) = 0;

    53 protected:

    54 	IMPORT_C CRandom(void);

    55 private:

    56 	CRandom(const CRandom&);

    57 	CRandom& operator=(const CRandom&);

    58 	};

    59 

    60 /**

    61  *

    62  * Sets a secure random number generator implementation to use

    63  * for this thread.

    64  * 

    65  * @param aRNG The secure random number generator to use.

    66  *

    67  */

    68 IMPORT_C void SetThreadRandomL(CRandom* aRNG);

    69 

    70 /**

    71  *

    72  * Sets a secure random number generator implementation to use

    73  * for this thread, placing it on the cleanup stack.

    74  * 

    75  * @param aRNG The secure random number generator to use.

    76  *

    77  */

    78 IMPORT_C void SetThreadRandomLC(CRandom* aRNG);

    79 

    80 /** @internalAll */

    81 void DeleteThreadRandom(TAny* aPtr);

    82 

    83 /**

    84  *

    85  * Destroys the currently installed random number generator

    86  * that is in use for this thread.

    87  *

    88  */

    89 IMPORT_C void DestroyThreadRandom(void);

    90 

    91 /**

    92  *

    93  * Generates cryptographically secure random data, filling

    94  * the provided buffer up to its current length, discarding

    95  * any data that it may currently contain.

    96  *

    97  * @param aDest The buffer to fill with random data

    98  *

    99  */

   100 IMPORT_C void GenerateRandomBytesL(TDes8& aDest);

   101 

   102 class CSystemRandom : public CRandom

   103 /**

   104  *

   105  * This default secure random number generator uses

   106  * system state to generate entropy for the generation

   107  * of cryptographically secure random numbers.

   108  *

   109  * @publishedAll

   110  * @released

   111  *

   112  */

   113 

   114 	{

   115 public:

   116 

   117 	/**

   118 	 *

   119 	 * Constructs a new system random number generator.

   120 	 *

   121 	 * @return A ready-to-use random number generator.

   122 	 */

   123 	IMPORT_C static CSystemRandom* NewL(void);

   124 	

   125 	/**

   126 	 *

   127 	 * Constructs a new system random number generator,

   128 	 * and places it on the cleanup stack.

   129 	 *

   130 	 * @return A ready-to-use random number generator.

   131 	 *

   132 	 */

   133 	IMPORT_C static CSystemRandom* NewLC(void);

   134 	

   135 	/**

   136 	 *

   137 	 * Implements the contract as specified in the base

   138 	 * class, CRandom, filling the buffer supplied with

   139 	 * cryptographically secure random data up to its

   140 	 * current length, discarding its current content.

   141 	 *

   142 	 * @param aDest The buffer to which to write random data

   143 	 *

   144 	 */

   145 	virtual void GenerateBytesL(TDes8& aDest);

   146 private:

   147 	CSystemRandom(void);

   148 	CSystemRandom(const CSystemRandom&);

   149 	CSystemRandom& operator=(const CSystemRandom&);

   150 	};

   151 

   152 class TRandom

   153 /**

   154  *

   155  * The user interface to the system cryptographically 

   156  * secure random number generator.

   157  *

   158  * @publishedAll

   159  * @released

   160  */

   161 	{

   162 public:

   163 

   164 	/**

   165 	 * 

   166 	 * Fills the provided buffer with secure random data up to its

   167 	 * current length, discarding any current content.

   168 	 *

   169 	 * @param aDestination The buffer in which to write the random data.

   170 	 * @deprecated Use RandomL() instead

   171 	 * @panic This function can panic under low memory conditions

   172 	 *

   173 	 */

   174 	IMPORT_C static void Random(TDes8& aDestination);

   175 

   176 	/**

   177 	 * 

   178 	 * Fills the provided buffer with secure random data up to its

   179 	 * current length, discarding any current content.

   180 	 *

   181 	 * @param aDestination The buffer in which to write the random data.

   182 	 * @leave This function can leave under low memory conditions

   183 	 *

   184 	 */

   185 	IMPORT_C static void RandomL(TDes8& aDestination);

   186 	};

   187 

   188 class RRandomSession:public RSessionBase

   189 /**

   190  *

   191  * The client interface to the system random number generator. End

   192  * users should use TRandom instead of this interface.

   193  *

   194  * @publishedAll

   195  * @released

   196  */

   197 	{

   198 public:

   199 

   200 	IMPORT_C RRandomSession(void);

   201 	

   202 	/**

   203 	 * 

   204 	 * Fills the provided buffer with secure random data up to its

   205 	 * current length, discarding any current content.

   206 	 *

   207 	 * @param aDestination The buffer in to which to write the random data 

   208 	 *

   209 	 */

   210 	IMPORT_C TInt GetRandom(TDes8& aDestination);

   211 	

   212 	/**

   213 	 *

   214 	 * Opens a new session with the random number server.

   215 	 *

   216 	 */

   217 	IMPORT_C void ConnectL(void);

   218 	};

   219 

   220 #endif // __RANDOM_H__