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