os/security/crypto/weakcryptospi/inc/random.h
author sl
Tue, 10 Jun 2014 14:32:02 +0200 (2014-06-10)
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
     1 /*
     2 * Copyright (c) 2005-2010 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 the generated pseudo-random data up to the
    44 	 * current length, discarding any current contents. The 
    45 	 * implementations should leave with KErrNotSecure when 
    46 	 * the generated random data is not secure enough. 
    47 	 *
    48 	 * @param aDest The buffer to fill with random data
    49 	 * @leave KErrNotSecure Random data generated is not 
    50 	 *        secure enough for crytographic operations
    51 	 *        otherwise, leaves with any other system wide error code.
    52 	 *
    53 	 */
    54 	virtual void GenerateBytesL(TDes8& aDest) = 0;
    55 protected:
    56 	IMPORT_C CRandom(void);
    57 private:
    58 	CRandom(const CRandom&);
    59 	CRandom& operator=(const CRandom&);
    60 	};
    61 
    62 /**
    63  *
    64  * Sets a pseudo-random number generator implementation to use for this thread.
    65  * 
    66  * @param aRNG The pseudo-random number generator to use.
    67  *
    68  */
    69 IMPORT_C void SetThreadRandomL(CRandom* aRNG);
    70 
    71 /**
    72  *
    73  * Sets a pseudo-random number generator implementation to use
    74  * for this thread, placing it on the cleanup stack.
    75  * 
    76  * @param aRNG The pseudo-random number generator to use.
    77  *
    78  */
    79 IMPORT_C void SetThreadRandomLC(CRandom* aRNG);
    80 
    81 /** @internalAll */
    82 void DeleteThreadRandom(TAny* aPtr);
    83 
    84 /**
    85  *
    86  * Destroys the currently installed random number generator
    87  * that is in use for this thread.
    88  *
    89  */
    90 IMPORT_C void DestroyThreadRandom(void);
    91 
    92 /**
    93  *
    94  * Generates pseudo-random data.
    95  * Fills the provided buffer up to its current length,
    96  * discarding any data that it may currently contain.
    97  *
    98  * @param aDest The buffer to fill with random data
    99  * @leave KErrNotSecure The random data generated is  
   100  *        not secure enough for cryptographic operations
   101  *        otherwise, leaves with any other system wide error codes. 
   102  *
   103  */
   104 IMPORT_C void GenerateRandomBytesL(TDes8& aDest);
   105 
   106 class CRandomShim;
   107 class CSystemRandom : public CRandom
   108 /**
   109  *
   110  * This default pseudo-random number generator uses system state 
   111  * to generate entropy for the generation of random numbers.
   112  *
   113  * @publishedAll
   114  * @released
   115  *
   116  */
   117 
   118 	{
   119 public:
   120 
   121 	/**
   122 	 *
   123 	 * Constructs a new pseudo-random number generator.
   124 	 *
   125 	 * @return A ready-to-use random number generator.
   126 	 */
   127 	IMPORT_C static CSystemRandom* NewL(void);
   128 	
   129 	/**
   130 	 *
   131 	 * Constructs a new pseudo-random number generator,
   132 	 * and places it on the cleanup stack.
   133 	 *
   134 	 * @return A ready-to-use random number generator.
   135 	 *
   136 	 */
   137 	IMPORT_C static CSystemRandom* NewLC(void);
   138 	
   139 	/**
   140 	 *
   141 	 * Implements the contract as specified in the base class,  CRandom, filling the buffer
   142 	 * supplied with random data  up to its current length, discarding its current content.
   143 	 * It will leave under no memory condition.
   144 	 *
   145 	 * @param aDest The buffer to be filled with random data
   146 	 *        
   147 	 */
   148 	virtual void GenerateBytesL(TDes8& aDest);
   149 	
   150 	~CSystemRandom();
   151 private:
   152 	CSystemRandom(void);
   153 	CSystemRandom(const CSystemRandom&);
   154 	CSystemRandom& operator=(const CSystemRandom&);
   155 	
   156 	void ConstructL();
   157 	
   158 	CRandomShim *iShim;
   159 	};
   160 
   161 class TRandom
   162 /**
   163  *
   164  * The user interface to the random number generator.
   165  *
   166  * @publishedAll
   167  * @released
   168  */
   169 	{
   170 public:
   171 
   172 	/**
   173 	 * 
   174 	 * Fills the provided buffer with pseudo-random data up to its current length, 
   175 	 * discarding any current content.
   176 	 *
   177 	 * This method will not return secure random numbers for some time after the phone boot-up. Because,
   178 	 * pseudo-random number generator will take some time to attain a secure state by collecting enough 
   179 	 * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be
   180 	 * cryptographically secure and there is no way to get to know about it with this API. 
   181 	 * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL.
   182 	 *
   183 	 * @param aDestination The buffer in which to write the random data.
   184 	 * @deprecated Use RandomL() instead
   185 	 * @panic This function can panic under low memory conditions
   186 	 *
   187 	 */
   188 	IMPORT_C static void Random(TDes8& aDestination);
   189 
   190 	/**	
   191 	 * 
   192 	 * Fills the provided buffer with pseudo-random data up to its current length,
   193 	 * discarding any current content.
   194 	 *
   195 	 * This method will not return secure random numbers for some time after the phone boot-up. Because,
   196      * pseudo-random number generator will take some time to attain a secure state by collecting enough 
   197      * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be
   198      * cryptographically secure and there is no way to get to know about it with this API. 
   199      * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL.
   200 	 *
   201 	 * @param aDestination The buffer in which to write the random data.
   202 	 * @leave This function can leave under low memory conditions
   203 	 *
   204 	 */
   205 	IMPORT_C static void RandomL(TDes8& aDestination);
   206 	
   207 	/**
   208 	 * 
   209 	 * Fills the provided buffer with the pseudo-random data up to its current length, discarding any current
   210 	 * content of the descriptor. When this method returns normally (with out leave), the system state is secure
   211 	 * and hence the random numbers generated are cryptographically secure as well. When this method leaves with
   212 	 * the error code KErrNotSecure, the system internal state is not secure and hence the random numbers too.
   213 	 * 
   214 	 * Though this method leaves when the system internal state is not secure, still the descriptor will be filled 
   215 	 * with pseudo-random bytes. This random data may or may not be secure enough. Recommended to treat these numbers 
   216 	 * as not secure.
   217 	 *
   218 	 * @param aDestination The buffer in which to write the random data.
   219 	 * @leave KErrNotSecure The generated random numbers is not secure enough for cryptographic operations.
   220 	 *        Otherwise, leaves with some other system wide error codes.
   221 	 *
   222 	 */
   223 	IMPORT_C static void SecureRandomL(TDes8& aDestination);
   224 	};
   225 
   226 class RRandomSession:public RSessionBase
   227 /**
   228  *
   229  * The client interface to the system random number generator. End
   230  * users should use TRandom instead of this interface.
   231  *
   232  * @publishedAll
   233  * @released
   234  */
   235 	{
   236 public:
   237 
   238 	IMPORT_C RRandomSession(void);
   239 	
   240 	/**
   241 	 * 
   242 	 * Fills the provided buffer with pseudo-random data up to its
   243 	 * current length, discarding any current content.
   244 	 *
   245 	 * @param aDestination The buffer in to which to write the random data 
   246 	 *
   247 	 */
   248 	IMPORT_C TInt GetRandom(TDes8& aDestination);
   249 	
   250 	/**
   251 	 *
   252 	 * Opens a new session with the random number generator.
   253 	 *
   254 	 */
   255 	IMPORT_C void ConnectL(void);
   256 	};
   257 
   258 #endif // __RANDOM_H__