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  @file

    24  @publishedAll

    25  @released

    26 */

    27 

    28 #ifndef __RANDOM_H__

    29 #define __RANDOM_H__

    30 

    31 #include <e32base.h>

    32 

    33 class CRandom : public CBase

    34 /**

    35  * @publishedAll

    36  * @released

    37  */

    38 	{

    39 public:

    40 

    41 	/**

    42 	 * Implementations of this method should fill the passed

    43 	 * buffer with securely generated random data up to the 

    44 	 * current length, discarding any current contents.

    45 	 *

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

    47 	 *

    48 	 */

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

    50 protected:

    51 	IMPORT_C CRandom(void);

    52 private:

    53 	CRandom(const CRandom&);

    54 	CRandom& operator=(const CRandom&);

    55 	};

    56 

    57 /**

    58  *

    59  * Sets a secure random number generator implementation to use

    60  * for this thread.

    61  * 

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

    63  *

    64  */

    65 IMPORT_C void SetThreadRandomL(CRandom* aRNG);

    66 

    67 /**

    68  *

    69  * Sets a secure random number generator implementation to use

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

    71  * 

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

    73  *

    74  */

    75 IMPORT_C void SetThreadRandomLC(CRandom* aRNG);

    76 

    77 /** @internalAll */

    78 void DeleteThreadRandom(TAny* aPtr);

    79 

    80 /**

    81  *

    82  * Destroys the currently installed random number generator

    83  * that is in use for this thread.

    84  *

    85  */

    86 IMPORT_C void DestroyThreadRandom(void);

    87 

    88 /**

    89  *

    90  * Generates cryptographically secure random data, filling

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

    92  * any data that it may currently contain.

    93  *

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

    95  *

    96  */

    97 IMPORT_C void GenerateRandomBytesL(TDes8& aDest);

    98 

    99 class CRandomShim;

   100 class CSystemRandom : public CRandom

   101 /**

   102  *

   103  * This default secure random number generator uses

   104  * system state to generate entropy for the generation

   105  * of cryptographically secure random numbers.

   106  *

   107  * @publishedAll

   108  * @released

   109  *

   110  */

   111 

   112 	{

   113 public:

   114 

   115 	/**

   116 	 *

   117 	 * Constructs a new system random number generator.

   118 	 *

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

   120 	 */

   121 	IMPORT_C static CSystemRandom* NewL(void);

   122 	

   123 	/**

   124 	 *

   125 	 * Constructs a new system random number generator,

   126 	 * and places it on the cleanup stack.

   127 	 *

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

   129 	 *

   130 	 */

   131 	IMPORT_C static CSystemRandom* NewLC(void);

   132 	

   133 	/**

   134 	 *

   135 	 * Implements the contract as specified in the base

   136 	 * class, CRandom, filling the buffer supplied with

   137 	 * cryptographically secure random data up to its

   138 	 * current length, discarding its current content.

   139 	 *

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

   141 	 *

   142 	 */

   143 	virtual void GenerateBytesL(TDes8& aDest);

   144 	

   145 	~CSystemRandom();

   146 private:

   147 	CSystemRandom(void);

   148 	CSystemRandom(const CSystemRandom&);

   149 	CSystemRandom& operator=(const CSystemRandom&);

   150 	

   151 	void ConstructL();

   152 	

   153 	CRandomShim *iShim;

   154 	};

   155 

   156 class TRandom

   157 /**

   158  *

   159  * The user interface to the system cryptographically 

   160  * secure random number generator.

   161  *

   162  * @publishedAll

   163  * @released

   164  */

   165 	{

   166 public:

   167 

   168 	/**

   169 	 * 

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

   171 	 * current length, discarding any current content.

   172 	 *

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

   174 	 * @deprecated Use RandomL() instead

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

   176 	 *

   177 	 */

   178 	IMPORT_C static void Random(TDes8& aDestination);

   179 

   180 	/**

   181 	 * 

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

   183 	 * current length, discarding any current content.

   184 	 *

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

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

   187 	 *

   188 	 */

   189 	IMPORT_C static void RandomL(TDes8& aDestination);

   190 	};

   191 

   192 class RRandomSession:public RSessionBase

   193 /**

   194  *

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

   196  * users should use TRandom instead of this interface.

   197  *

   198  * @publishedAll

   199  * @released

   200  */

   201 	{

   202 public:

   203 

   204 	IMPORT_C RRandomSession(void);

   205 	

   206 	/**

   207 	 * 

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

   209 	 * current length, discarding any current content.

   210 	 *

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

   212 	 *

   213 	 */

   214 	IMPORT_C TInt GetRandom(TDes8& aDestination);

   215 	

   216 	/**

   217 	 *

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

   219 	 *

   220 	 */

   221 	IMPORT_C void ConnectL(void);

   222 	};

   223 

   224 #endif // __RANDOM_H__