/*

* Copyright (c) 2002-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: 

* ** IMPORTANT **  API's in this file are published to 3rd party developers via the 

* Symbian website. Changes to these API's should be treated as PublishedAll API changes and the Security TA should be consulted.

* Padding codes

*

*/

/**

 @file 

 @publishedAll

 @released

*/

#ifndef __PADDING_H__

#define __PADDING_H__

#include <random.h>

/** 

* Abstract base class defining the interface to padding schemes.

*

* It is designed to be used by both symmetric and asymmetric ciphers.

*

*/

class CPadding : public CBase

	{

public:

	/** 

	* Pads aInput to be BlockSize() bytes long and places the result in aOutput.  

	*

	* @param aInput		Data to be padded.  The size must be less than or equal to

	* 					BlockSize() minus MinPaddingLength().

	* @param aOutput	On return, the resulting padded, block size aligned data

	*					appended to aOutput.  

	*/

	IMPORT_C void PadL(const TDesC8& aInput,TDes8& aOutput);

	/**

	* Pads aInput to be BlockSize() long and places the result in aOutput.  

	*

	* Deriving implementations of DoPadL() can assume that aInput is less than or

	* equal to BlockSize() minus MinPaddingLength().

	*

	* @param aInput		Data to be padded.  

	* @param aOutput	On return, the resulting padded, aBlockBytes aligned data 

	*					appended to aOutput.  

	*/

	virtual void DoPadL(const TDesC8& aInput,TDes8& aOutput) = 0;

	/**

	* Removes padding from aInput and appends unpadded result to aOutput.

	* 

	* @param aInput		Data to be unpadded.

	* @param aOutput	On return, the unpadded data.

	*/

	virtual void UnPadL(const TDesC8& aInput,TDes8& aOutput) = 0;

	/**

	* Sets the block size for this padding system.

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C void SetBlockSize(TInt aBlockBytes);

	/**

	* Retrieves the block size for this padding system.

	*

	* @return	The block size in bytes.

	*/

	IMPORT_C TInt BlockSize(void) const;

	/**

	* Gets the smallest number of bytes that PadL() will ever add to aInput in

	* order to get a valid block aligned aOutput.  

	*

	* For example, in SSLv3 padding, if the block size is 8 and aInput is 7 bytes,

	* it will append 1 byte of padding. For SSLv3 padding, this is the smallest 

	* amount possible as an 8 byte input will add another block size (8 more bytes)

	* of padded data.

	* 

	* @return	A TInt containing the smallest number of padding bytes possible.

	*/

	virtual TInt MinPaddingLength(void) const = 0;

	/**

	* Gets the size of the aOutput buffer, in a call to PadL(), must be in

	* order to accommodate a block size of BlockSize() and an input size of

	* aInputBytes.

	* 

	* @note	By default, this function returns the output of BlockSize().  If

	*		a derived padding system outputs more than a single block of padding,

	*		one must override this function and return the appropriate value.

	*

	* @param aInputBytes	The amount of data to be padded out in bytes.

	* @return				A TInt representing the maximum amount of padded output data

	*						(in bytes) for a given block and input size.

	*/

	IMPORT_C virtual TInt MaxPaddedLength(TInt aInputBytes) const;

	/**

	* Gets the size of the aOutput buffer, in a call to UnPadL(), must be in

	* order to accommodate an input size of aInputBytes.

	*

	* @note	By default, this function returns the value of aInputBytes minus MinPaddingBytes().

	*		Most padding systems cannot determine anything about the unpadded length

	*		without looking at the data.  If your padding system allows you to give a

	*		better bound, then you should reimplement this function.

	*

	* @param aInputBytes	The amount of data to be unpadded in bytes.

	* @return				A TInt containing the maximum amount of unpadded output data

	*						(in bytes) for a given padded input.

	*/

	IMPORT_C virtual TInt MaxUnPaddedLength(TInt aInputBytes) const;

protected:

	/** 

	* Constructor

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C CPadding(TInt aBlockBytes);

private:

	CPadding(void);

	CPadding(const CPadding&);

	CPadding& operator=(const CPadding&);

private:

	TInt iBlockBytes;

	};

/**

* This concrete subclass of CPadding appends no padding.

*

* aOutput will be a copy of aInput after any call to PadL() or UnPadL().

*

*/

class CPaddingNone:public CPadding

	{

public:

	/**

	* Creates a new CPaddingNone object.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingNone object.

	*/

	IMPORT_C static CPaddingNone* NewL(TInt aBlockBytes=KMaxTInt);

	/**

	* Creates a new CPaddingNone object and leaves a pointer to it on the cleanup stack.

	* 

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingNone object.

	*/

	IMPORT_C static CPaddingNone* NewLC(TInt aBlockBytes=KMaxTInt);

	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

	TInt MinPaddingLength(void) const;

	TInt MaxPaddedLength(TInt aInputBytes) const;

protected:

	/** 

	* Constructor

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C CPaddingNone(TInt aBlockBytes);

private:

	CPaddingNone(void);

	CPaddingNone(const CPaddingNone&);

	CPaddingNone& operator=(const CPaddingNone&);

	};

/**

* This concrete subclass of CPadding implements PKCS#1 v1.5 signature padding.

*

* It is intended for use with RSA signing/verifying.

*

*/

class CPaddingPKCS1Signature : public CPadding

	{

public:

	/**

	* Creates a new CPaddingPKCS1Signature object.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingPKCS1Signature object.

	*/

	IMPORT_C static CPaddingPKCS1Signature* NewL(TInt aBlockBytes);

	/**

	* Creates a new CPaddingPKCS1Signature object and leaves a pointer to it on the

	* cleanup stack.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingPKCS1Signature object.

	*/

	IMPORT_C static CPaddingPKCS1Signature* NewLC(

		TInt aBlockBytes);

	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

	TInt MinPaddingLength(void) const;

protected:

	/** 

	* Constructor

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C CPaddingPKCS1Signature(TInt aBlockBytes);

private:

	CPaddingPKCS1Signature(void);

	CPaddingPKCS1Signature(const CPaddingPKCS1Signature&);

	CPaddingPKCS1Signature& operator=(const CPaddingPKCS1Signature&);

	};

/**

* This concrete subclass of CPadding implements PKCS#1 v1.5 encryption padding.

* It is intended for use with RSA encryption/decryption.

*

*/

class CPaddingPKCS1Encryption : public CPadding

	{

public:

	/**

	* Creates a new CPaddingPKCS1Encryption object.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingPKCS1Encryption object.

	*/

	IMPORT_C static CPaddingPKCS1Encryption* NewL(TInt aBlockBytes);

	/**

	* Creates a new CPaddingPKCS1Encryption object and leaves a pointer to it on the

	* cleanup stack.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingPKCS1Encryption object.

	*/

	IMPORT_C static CPaddingPKCS1Encryption* NewLC(TInt aBlockBytes);

	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

	TInt MinPaddingLength(void) const;

protected:

	/** 

	* Constructor

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C CPaddingPKCS1Encryption(TInt aBlockBytes);

private:

	CPaddingPKCS1Encryption(void);

	CPaddingPKCS1Encryption(const CPaddingPKCS1Encryption&);

	CPaddingPKCS1Encryption& operator=(const CPaddingPKCS1Encryption&);

	};

/**

* This concrete subclass of CPadding implements padding according to 

* the SSLv3/TLS standard.

*

* The SSL 3.0 spec does not specifiy the padding bytes to be used - it is

* assumed to be arbitrary (and the openssl implementation uses non-zero random

* data).  The TLS spec however states that padding bytes should be the length

* of the padding - 1.  This class implements the latter when padding, but does

* not check the padding byes when unpadding, so as to be interoperable with SSL

* 3.0.

* 

*/

class CPaddingSSLv3 : public CPadding

	{

public:

	/**

	* Creates a new CPaddingSSLv3 object.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingSSLv3 object.

	*/

	IMPORT_C static CPaddingSSLv3* NewL(TInt aBlockBytes);

	/**

	* Creates a new CPaddingSSLv3 object and leaves a pointer to it on the cleanup stack.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingSSLv3 object.

	*/

	IMPORT_C static CPaddingSSLv3* NewLC(TInt aBlockBytes);

	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

	TInt MinPaddingLength(void) const;

	TInt MaxPaddedLength(TInt aInputBytes) const;

protected:

	/** 

	* Constructor

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C CPaddingSSLv3(TInt aBlockBytes);

private:

	CPaddingSSLv3(void);

	CPaddingSSLv3(const CPaddingSSLv3&);

	CPaddingSSLv3& operator=(const CPaddingSSLv3&);

	};

/**

* This concrete subclass of CPadding implements padding according to 

* the PKCS#7/TLS standard.

*

*/

class CPaddingPKCS7 : public CPadding

	{

public:

	/**

	* Creates a new CPaddingPKCS7 object.

	* 

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingPKCS7 object.

	*/

	IMPORT_C static CPaddingPKCS7* NewL(TInt aBlockBytes);

	/**

	* Creates a new CPaddingPKCS7 object and leaves a pointer to it on the cleanup stack.

	*

	* @param aBlockBytes	The block size in bytes.

	* @return				A pointer to the new CPaddingPKCS7 object.

	*/

	IMPORT_C static CPaddingPKCS7* NewLC(TInt aBlockBytes);

	void DoPadL(const TDesC8& aInput,TDes8& aOutput);

	void UnPadL(const TDesC8& aInput,TDes8& aOutput);

	TInt MinPaddingLength(void) const;

	TInt MaxPaddedLength(TInt aInputBytes) const;

protected:

	/** 

	* Constructor

	* 

	* @param aBlockBytes	The block size in bytes.

	*/

	IMPORT_C CPaddingPKCS7(TInt aBlockBytes);

private:

	CPaddingPKCS7(void);

	CPaddingPKCS7(const CPaddingPKCS7&);

	CPaddingPKCS7& operator=(const CPaddingPKCS7&);

	};

#endif