/*+
−
* Copyright (c) 2005-2009 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:+
−
*+
−
* Description: +
−
* (c) 1999-2003 Symbian Ltd+
−
*+
−
*/+
−
+
−
+
−
+
−
+
−
/**+
−
 @file+
−
 @publishedAll+
−
 @released+
−
*/+
−
+
−
#ifndef __RANDOM_H__+
−
#define __RANDOM_H__+
−
+
−
#include <e32base.h>+
−
+
−
class CRandom : public CBase+
−
/**+
−
 * @publishedAll+
−
 * @released+
−
 */+
−
	{+
−
public:+
−
+
−
	/**+
−
	 * Implementations of this method should fill the passed+
−
	 * buffer with the generated pseudo-random data up to the+
−
	 * current length, discarding any current contents. The +
−
	 * implementations should leave with KErrNotSecure when +
−
	 * the generated random data is not secure enough. +
−
	 *+
−
	 * @param aDest The buffer to fill with random data+
−
	 * @leave KErrNotSecure Random data generated is not +
−
	 *        secure enough for crytographic operations+
−
	 *        otherwise, leaves with any other system wide error code.+
−
	 *+
−
	 */+
−
	virtual void GenerateBytesL(TDes8& aDest) = 0;+
−
protected:+
−
	IMPORT_C CRandom(void);+
−
private:+
−
	CRandom(const CRandom&);+
−
	CRandom& operator=(const CRandom&);+
−
	};+
−
+
−
/**+
−
 *+
−
 * Sets a pseudo-random number generator implementation to use for this thread.+
−
 * +
−
 * @param aRNG The pseudo-random number generator to use.+
−
 *+
−
 */+
−
IMPORT_C void SetThreadRandomL(CRandom* aRNG);+
−
+
−
/**+
−
 *+
−
 * Sets a pseudo-random number generator implementation to use+
−
 * for this thread, placing it on the cleanup stack.+
−
 * +
−
 * @param aRNG The pseudo-random number generator to use.+
−
 *+
−
 */+
−
IMPORT_C void SetThreadRandomLC(CRandom* aRNG);+
−
+
−
/** @internalAll */+
−
void DeleteThreadRandom(TAny* aPtr);+
−
+
−
/**+
−
 *+
−
 * Destroys the currently installed random number generator+
−
 * that is in use for this thread.+
−
 *+
−
 */+
−
IMPORT_C void DestroyThreadRandom(void);+
−
+
−
/**+
−
 *+
−
 * Generates pseudo-random data.+
−
 * Fills the provided buffer up to its current length,+
−
 * discarding any data that it may currently contain.+
−
 *+
−
 * @param aDest The buffer to fill with random data+
−
 * @leave KErrNotSecure The random data generated is  +
−
 *        not secure enough for cryptographic operations+
−
 *        otherwise, leaves with any other system wide error codes. +
−
 *+
−
 */+
−
IMPORT_C void GenerateRandomBytesL(TDes8& aDest);+
−
+
−
class CRandomShim;+
−
class CSystemRandom : public CRandom+
−
/**+
−
 *+
−
 * This default pseudo-random number generator uses system state +
−
 * to generate entropy for the generation of random numbers.+
−
 *+
−
 * @publishedAll+
−
 * @released+
−
 *+
−
 */+
−
+
−
	{+
−
public:+
−
+
−
	/**+
−
	 *+
−
	 * Constructs a new pseudo-random number generator.+
−
	 *+
−
	 * @return A ready-to-use random number generator.+
−
	 */+
−
	IMPORT_C static CSystemRandom* NewL(void);+
−
	+
−
	/**+
−
	 *+
−
	 * Constructs a new pseudo-random number generator,+
−
	 * and places it on the cleanup stack.+
−
	 *+
−
	 * @return A ready-to-use random number generator.+
−
	 *+
−
	 */+
−
	IMPORT_C static CSystemRandom* NewLC(void);+
−
	+
−
	/**+
−
	 *+
−
	 * Implements the contract as specified in the base class,  CRandom, filling the buffer+
−
	 * supplied with random data  up to its current length, discarding its current content.+
−
	 * It will leave with KErrNotSecure when the generated random data is not secure enough.+
−
	 *+
−
	 * @param aDest The buffer to which to write random data+
−
	 * @leave KErrNotSecure The generated random data is not secure enough for cryptographic operations +
−
	 *        otherwise, leaves with any other system wide error codes.+
−
	 *        +
−
	 */+
−
	virtual void GenerateBytesL(TDes8& aDest);+
−
	+
−
	~CSystemRandom();+
−
private:+
−
	CSystemRandom(void);+
−
	CSystemRandom(const CSystemRandom&);+
−
	CSystemRandom& operator=(const CSystemRandom&);+
−
	+
−
	void ConstructL();+
−
	+
−
	CRandomShim *iShim;+
−
	};+
−
+
−
class TRandom+
−
/**+
−
 *+
−
 * The user interface to the random number generator.+
−
 *+
−
 * @publishedAll+
−
 * @released+
−
 */+
−
	{+
−
public:+
−
+
−
	/**+
−
	 * +
−
	 * Fills the provided buffer with pseudo-random data up to its current length, +
−
	 * discarding any current content.+
−
	 *+
−
	 * This method will not return secure random numbers for some time after the phone boot-up. Because,+
−
	 * pseudo-random number generator will take some time to attain a secure state by collecting enough +
−
	 * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be+
−
	 * cryptographically secure and there is no way to get to know about it with this API. +
−
	 * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL.+
−
	 *+
−
	 * @param aDestination The buffer in which to write the random data.+
−
	 * @deprecated Use RandomL() instead+
−
	 * @panic This function can panic under low memory conditions+
−
	 *+
−
	 */+
−
	IMPORT_C static void Random(TDes8& aDestination);+
−
+
−
	/**	+
−
	 * +
−
	 * Fills the provided buffer with pseudo-random data up to its current length,+
−
	 * discarding any current content.+
−
	 *+
−
	 * This method will not return secure random numbers for some time after the phone boot-up. Because,+
−
     * pseudo-random number generator will take some time to attain a secure state by collecting enough +
−
     * entropy samples after the boot-up. Till that time, the pseudo-random numbers generated may not be+
−
     * cryptographically secure and there is no way to get to know about it with this API. +
−
     * So, if explcit notification on the strength of the random numbers is necessary, use TRandom::SecureRandomL.+
−
	 *+
−
	 * @param aDestination The buffer in which to write the random data.+
−
	 * @leave This function can leave under low memory conditions+
−
	 *+
−
	 */+
−
	IMPORT_C static void RandomL(TDes8& aDestination);+
−
	+
−
	/**+
−
	 * +
−
	 * Fills the provided buffer with the pseudo-random data up to its current length, discarding any current+
−
	 * content of the descriptor. When this method returns normally (with out leave), the system state is secure+
−
	 * and hence the random numbers generated are cryptographically secure as well. When this method leaves with+
−
	 * the error code KErrNotSecure, the system internal state is not secure and hence the random numbers too.+
−
	 * +
−
	 * Though this method leaves when the system internal state is not secure, still the descriptor will be filled +
−
	 * with pseudo-random bytes. This random data may or may not be secure enough. Recommended to treat these numbers +
−
	 * as not secure.+
−
	 *+
−
	 * @param aDestination The buffer in which to write the random data.+
−
	 * @leave KErrNotSecure The generated random numbers is not secure enough for cryptographic operations.+
−
	 *        Otherwise, leaves with some other system wide error codes.+
−
	 *+
−
	 */+
−
	IMPORT_C static void SecureRandomL(TDes8& aDestination);+
−
	};+
−
+
−
class RRandomSession:public RSessionBase+
−
/**+
−
 *+
−
 * The client interface to the system random number generator. End+
−
 * users should use TRandom instead of this interface.+
−
 *+
−
 * @publishedAll+
−
 * @released+
−
 */+
−
	{+
−
public:+
−
+
−
	IMPORT_C RRandomSession(void);+
−
	+
−
	/**+
−
	 * +
−
	 * Fills the provided buffer with pseudo-random data up to its+
−
	 * current length, discarding any current content.+
−
	 *+
−
	 * @param aDestination The buffer in to which to write the random data +
−
	 *+
−
	 */+
−
	IMPORT_C TInt GetRandom(TDes8& aDestination);+
−
	+
−
	/**+
−
	 *+
−
	 * Opens a new session with the random number generator.+
−
	 *+
−
	 */+
−
	IMPORT_C void ConnectL(void);+
−
	};+
−
+
−
#endif // __RANDOM_H__+
−