/*
* 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 ** PublishedPartner 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.
*
*/


/**
 @file
 @publishedPartner
 @released
*/

#ifndef __PBEBASE_H__
#define __PBEBASE_H__

#include <e32base.h>

class CPBEncryptParms;
class CPBEncryptionData;
class CPBEncryptSet;
class TPBPassword;

/** 
 * Abstract class defining the interface required to allow the actual
 * transformation of plaintext to ciphertext.
 *
 * Generally this class' descendants are constructed using the
 * functions CPBEncryptElement::NewEncryptLC() or CPBEncryptSet::NewEncryptLC().
 *
 * @see CPBEncryptorElement and CPBEncryptorSet
 */
class CPBEncryptor : public CBase
	{
public:
	/** 
	 * Transforms aInput into its encrypted form, aOutput.
	 *
	 *	See the Cryptography api-guide documentation for an explanation of
	 *	how buffering of data supplied to this function is handled.
	 *
	 * @param aInput	The plaintext.
	 * @param aOutput	On return, the ciphertext.
	 */
	virtual void Process(const TDesC8& aInput, TDes8& aOutput) = 0;

	/** 
	 * Transforms aInput into its encrypted form, aOutput, and applies a
	 * padding scheme to ensure a block aligned result.
	 *
	 *	See the Cryptography api-guide documentation for an explanation of
	 *	how buffering of data supplied to this function is handled.
	 * 
	 * @param aInput	The plaintext.
	 * @param aOutput	On return, the ciphertext.
	 */
	virtual void ProcessFinalL(const TDesC8& aInput, TDes8& aOutput) = 0;

	/** 
	 * Gets the maximum length of the output resulting from calling Process() with a
	 * given input length.
	 *
	 * @param aMaxInputLength	The maximum input length in bytes.
	 * @return					The maximum output length in bytes.
	 */
	virtual TInt MaxOutputLength(TUint aMaxInputLength) const = 0;
	
	/** 
	 * Gets the maximum length of the output resulting from calling ProcessFinalL()
	 * with a given input length.
	 *
	 * @param aMaxInputLength	The maximum input length in bytes.
	 * @return					The maximum output length in bytes.
	 */
	virtual TInt MaxFinalOutputLength(TUint aMaxInputLength) const = 0;
};

/** 
 * Abstract class defining the interface required to allow the actual
 * transformation of ciphertext to plaintext.
 *  
 * Generally this class' descendants are constructed using the
 * functions CPBEncryptElement::NewDecryptLC() or CPBEncryptSet::NewDecryptLC().
 */
class CPBDecryptor : public CBase
	{
public:
	/** 
	 * Transforms aInput into its decrypted form, aOutput, and unpads.
	 *
	 *	See the Cryptography api-guide documentation for an explanation of
	 *	how buffering of data supplied to this function is handled.
	 * 
	 * @param aInput	The ciphertext.
	 * @param aOutput	On return, the plaintext.
	 */
	virtual void Process(const TDesC8& aInput, TDes8& aOutput) = 0;

	/** 
	 * Transforms aInput into its decrypted form, aOutput, and unpads.
	 * 
	 * @param aInput	The ciphertext.
	 * @param aOutput	On return, the plaintext.
	 */
	virtual void ProcessFinalL(const TDesC8& aInput, TDes8& aOutput) = 0;

	/** 
	 * Gets the maximum length of the output given a certain input length.
	 * 
	 * @param aMaxInputLength	The maximum input length in bytes.
	 * @return					The maximum output length in bytes.
	 */
	virtual TInt MaxOutputLength(TUint aMaxInputLength) const = 0;
	
	/** 
	 * Gets the maximum length of the output given a certain input length.
	 * 
	 * @param aMaxInputLength	The maximum input length in bytes.
	 * @return					The maximum output length in bytes.
	 */
	virtual TInt MaxFinalOutputLength(TUint aMaxInputLength) const = 0;
	};

/** 
 * Abstract base class defining the interface required to allow the password
 * based encryption and decryption of single or multiple items or elements.
 * 
 * @see CPBEncryptElement and CPBEncryptSet
 * @since v8.0
 */
class CPBEncryptionBase : public CBase
	{
public:
	/** 
	 * Gets the parameters allowing one to re-create the object with the
	 * same state at another point in the future.  
	 * 
	 * In order to decrypt any information previously encrypted with this object, 
	 * you <B><I>must</I></B> store this encryption data along with it. Failure 
	 * to do this will result in the permanent loss of the encrypted information.
	 * 
	 * @return	The data allowing one to re-create this object at a later time.
	 */
	virtual const CPBEncryptionData& EncryptionData(void) const = 0;

	/** 
	 * Constructs a CPBEncryptor object allowing the encryption of data.
	 *
	 * @return	A pointer to a CPBEncryptor object.
	 *			The caller assumes ownership of the returned object. 
	 */
	virtual CPBEncryptor* NewEncryptL(void) const = 0;

	/** 
	 * Constructs a CPBEncryptor object allowing the encryption of data.
	 * 
	 * @return	A pointer to a CPBEncryptor object.
	 *			The caller assumes ownership of the returned object.
	 *			The returned pointer is left on the cleanup stack.
	 */
	virtual CPBEncryptor* NewEncryptLC(void) const = 0;

	/** 
	 * Constructs a CPBDecryptor object allowing the decryption of data.
	 * 
	 * @return	A pointer to a CPBDecryptor object.
	 *			The caller assumes ownership of the returned object.
	 */
	virtual CPBDecryptor* NewDecryptL(void) const = 0;

	/** 
	 * Constructs a CPBDecryptor object allowing the decryption of data.
	 * 
	 * @return	A pointer to a CPBDecryptor object.
	 *			The caller assumes ownership of the returned object.
	 *			The returned pointer is left on the cleanup stack.
	 */
	virtual CPBDecryptor* NewDecryptLC(void) const = 0;

	/** 
	 * Gets the maximum output ciphertext length given a specified input plaintext length.  
	 * 
	 * @param aPlaintextLength	The plaintext length 
	 * @return					The maximum ciphertext length given a plaintext length.
	 */
	virtual TInt MaxCiphertextLength(TInt aPlaintextLength) const = 0;

	/** 
	 * Gets the maximum output plaintext length given a specified input ciphertext length.
	 *
	 * @param aCiphertextLength	The ciphertext length
	 * @return					The maximum plaintext length given a ciphertext length.
	 */
	virtual TInt MaxPlaintextLength(TInt aCiphertextLength) const = 0;

	};

#endif