// 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 "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:

// crypto.h - IPSEC API towards cryptographic libraries

//

/**

 @internalComponent

*/

#ifndef __CRYPTO_H__

#define __CRYPTO_H__

/**

// @file crypto.h

//

// The basic API for cryptographic algorithm library.

//

// IPSEC hook itself does not contain any cryptographic algorithms.

// The available algorithms are dynamically imported to the IPSEC

// by binding the IPSEC (pfkey) to one or more cryptographic libraries,

// each of which are implemented as a protocol..

//

// This header describes the basic API and base classes for building

// such cryptographic algorithm libraries as protocol modules for IPSEC.

//

// In the TServerProtocolDesc of such protocol, the following fields

// are significant for the IPSEC:

//

// @li	TServerProtocolDesc::iName (protocol name) is the symbolic

//		name of the library. When multiple libraries are used,

//		they should have different names.

// @li	TServerProtocolDesc::iAddrFamily should be KAfCrypto

// @li	TServerProtocolDesc::iProtocol must be KProtocolCrypto

//

// The remaining fields can be freely initialized to any values

// that satisfy the SocketServer requirements. The chosen values

// will have no effect on the IPSEC functionality.

//

// The cryptographic library protocol can be implemented in any

// protocol module (PRT file) along with other protocols. The

// value KProtocolCrypto alone in iProtocol tells that the protocol

// supports the API defined by this definition.

//

// An example of possible Ipsec configuration (ESK file)

// @verbatim

[sockman]

protocols= secpol,pfkey,lib1,lib2

[pfkey]

filename= ipsec6.prt

index= 2

bindto= lib1,lib2

[secpol]

filename= ipsec6.prt

index= 1

bindto= pfkey,ip6

[lib1]

filename= eaysymb.prt

index= 1

[lib2]

filename= newcrypto.prt

index= 1

@endverbatim

@internalTechnology

@released

*/

#include <e32base.h>

#include <es_prot.h>

#include <cryptospi/cryptospidef.h>

#include "cryptosymmetriccipherapi.h"

#include <cryptospi/cryptomacapi.h>

/**

// The protocol number for a library.

*/

const TUint KProtocolCrypto =	0x104;

/**

// The protocol family for the library.

*/

const TUint KAfCrypto = 0x0803;

typedef TBuf<0x20> TAlgorithmName;

/**

* @name	Well Known Algorithm Names

* The cryptographic libary can choose the names for it's algorithms freely,

* but it will cause less confusion, if the well known standard algoriths

* are named uniformly.

*/

//@{

/**

*	Single DES in CBC-Mode.

*	- key: 8

*	- block: 8

*	- IV: 8

*/

_LIT(KIpsecName_DES_CBC,		"descbc");

/**

*	Triple DES in CBC-Mode.

*	- key: 24

*	- block: 8

*	- IV: 8

*/

_LIT(KIpsecName_3DES_CBC,		"3descbc");

/**

*	Blowfish in CBC-Mode.

*	- key: variable in 8..72

*	- block: 8

*	- IV: 8

*/

_LIT(KIpsecName_BLOWFISH_CBC,	"blowfish");

/**

*	IDEA in CBC-Mode.

*	- key: 16

*	- block: 8

*	- IV: 8

*/

_LIT(KIpsecName_IDEA_CBC,		"idea");

/**

*	AES in CBC-Mode.

*	- key: 16, 24 or 32

*	- block: 16

*	- IV: 16

*/

_LIT(KIpsecName_AES_CBC,		"aescbc");

/**

*	AES in CTR-Mode.

*	- key 16, 24 or 32 (+ append 4 octets for the NONCE)

*	- block: 16

*	- IV: 8

*/

_LIT(KIpsecName_AES_CTR,		"aesctr");

/**

*	RC5 in CBC-Mode.

*	- key: variable 5..255

*	- block: 8

*	- IV: 8

*/

_LIT(KIpsecName_RC5,			"rc5");

/**

*	SHA1 Digest.

*	- digest length: 20

*	- block: 64

*/

_LIT(KIpsecName_SHA1,			"sha1");

/**

*	SHA2-256 Digest.

*	- digest length: 32

*	- block: 64

*/

_LIT(KIpsecName_SHA2_256,		"sha2-256");

/**

*	MD5 Digest.

*	- digest length: 16

*	- block: 64

*/

_LIT(KIpsecName_MD5,			"md5");

/**

*

* 

*/

#ifdef SYMBIAN_IPSEC_VOIP_SUPPORT

_LIT(KIpsecName_AES_XCBC_MAC, "aesxcbcmac") ;

#endif //SYMBIAN_IPSEC_VOIP_SUPPORT

//@}

typedef enum

	{

	EAlgorithmClass_Digest,	//< Message Digest algorithm

	EAlgorithmClass_Cipher,	//< Symmetric Cipher algorithm

#ifdef SYMBIAN_IPSEC_VOIP_SUPPORT

	EAlgorithmClass_Mac ,

#endif //SYMBIAN_IPSEC_VOIP_SUPPORT

	//

	// New types are possible by adding the symbol here

	// and defining the corresponding abstract class

	// (similar to CMessageDigestCrypto and CSymmetricCipher)

	//

	} TAlgorithmClass;

//	TAlgorithmDesc (and related types)

/**

// A description of available algorithm.

//

// Similar to ProtocolList, a protocol supporting this API must

// return a description of each implemented algorithm as an

// array of TAlgorithmDesc objects as a result of AlgorithmList

// call.

*/

class TAlgorithmDesc

	{

public:

	TAlgorithmName iName;		//< Name of the algorithm

	TAlgorithmClass iAlgType;	//< Class of the algorithm (cipher/digest)

	TUint iMinBits;				//< Min Length of the key in bits (all keys total)

	TUint iMaxBits;				//< Max Length of the key in bits (all keys total)

	TUint iBlock;				//< Length of the block in bytes

	TUint iVector;				//< Initialization Vector length (bytes)

	};

// Each of the following includes virtual destructor

// just in case there is a need for a cleanup code

// when the object is deleted using a pointer to

// the base virtual class.

// CMessageDigestCrypto

// ********************

/**

// Base Message Digest (abstract) class.

//

// All message digest algorithms must be derived from this

// base class, which defines the IPSEC required API for

// message digests (used by AH and ESP with authentication

// implementations). 

//

// Because IPSEC needs to run digest for each packet

// independently, it is important that the implementation

// can reset the computation by Init() without needing

// to do any additional allocations.

*/

class CMessageDigestCrypto : public CBase

	{

	// NOTE: This class was originally designed based on assumption

	// that the derived class implementing the digest includes all

	// state in member variables and does not need to allocate

	// additional space -- thus no ConstructL method.

public:

	/**

	// Set digest into initial state.

	//

	// IPSEC calls this method to start a new digest

	// computation for each IP packet that needs

	// digest computation.

	*/

	virtual void Init()=0;

	/**

	// Add segment of data to the digest.

	//

	// The octets in aMessage must be added to the digest

	// value. The length of the aMessage can be anything

	// from 0 or more octets. If the digest algorithm has

	// any inherent block requirements, then this method

	// must handle it (specifically, the digest must work

	// correctly, even if the data is fed to it one byte

	// at time).

	//

	// @param aMessage

	//	describe the segment of octets to be added into

	//	the digest (length >= 0).

	*/

	virtual void Update(const TDesC8& aMessage)=0;

	/**

	// Wrap up the digest and return the result.

	//

	// @param aDigest

	//	a buffer to return the final computed digest value.

	*/

	virtual void Final(TDes8& aDigest)=0;

	virtual ~CMessageDigestCrypto() {}

	};

#ifdef SYMBIAN_IPSEC_VOIP_SUPPORT

class CMacCrypto : public CBase

	{

	public:

	/**

	// Set digest into initial state.

	//

	// IPSEC calls this method to start a new digest

	// computation for each IP packet that needs

	// digest computation.

	*/

	virtual void Init()=0;

	/**

	// Add segment of data to the digest.

	//

	// The octets in aMessage must be added to the digest

	// value. The length of the aMessage can be anything

	// from 0 or more octets. If the digest algorithm has

	// any inherent block requirements, then this method

	// must handle it (specifically, the digest must work

	// correctly, even if the data is fed to it one byte

	// at time).

	//

	// @param aMessage

	//	describe the segment of octets to be added into

	//	the digest (length >= 0).

	*/

	virtual void Update(const TDesC8& aMessage)=0;

	/**

	// Wrap up the digest and return the result.

	//

	// @param aDigest

	//	a buffer to return the final computed digest value.

	*/

	virtual void Final(TDes8& aDigest)=0;

	virtual ~CMacCrypto() {}	

	};

#endif //SYMBIAN_IPSEC_VOIP_SUPPORT

// CSymmetricCipher

// ****************

/**

// Base Symmetric Cipher (abstract) class.

//

// All cipher algorithms must be derived from this

// base class, which defines the IPSEC required API for

// cipher algorithms (used by ESP implementation). 

//

// Because IPSEC needs to run cipher for each packet

// independently, it is important that the implementation

// can reset the computation by InitL() without needing

// to do any additional allocations [which means that

// it being a leaving function is a bad sign!]

*/

class CSymmetricCipher : public CBase

	{

public:

	enum TAction { EEncrypt, EDecrypt };

	/**

	// Define the cipher key.

	//

	// Because setting the key can be time consuming,

	// this is only called once after instantiation of the

	// class. Then, each packet is started with a call

	// to InitL.

	//

	// @param aKey

	//	the cipher key. The length of the key is

	//	defined by the length of this descriptor,

	//	and is always multiple of 8 bits.

	// @return

	// @li	> 0, the key is weak (but set anyway)

	// @li	= 0, all ok

	// @li	< 0, the key not usable (not set)

	*/

	virtual TInt Setkey(const TDesC8& aKey)=0;

	/**

	// Reset the cipher engine to initial state.

	//

	// As this method is called for each packet, it

	// should not do any memory allocation or heavy

	// computations.

	//

	// @param aIV initial vector.

	// @param aMode tells whether initialize is for decrypt or encrypt.

	*/

	virtual void Init(const TDesC8 &aIV, TAction aMode)=0;

	/**

	// Perform encryption or decryption.

	//

	// Because algorithms are expected to work blocks, the

	// caller will guarantee that ALL Outbuf's given to Update

	// will exist up to Finish call (or at least as long as at

	// least blocksize octets have been given to Update after it).

	// The implementation of the algorithm can store pointer(s) to

	// aOutbuf described memory area, and return data to such

	// memory area on some later Update or Finish call.

	//

	// The lengths of buffers are always equal, e.g. aInbuf.Length()

	// octets will always fit into aOutbuf. This length can be anything

	// from zero upwards. The cipher must work even if octets were

	// fed to it one by one.

	//

	// @param aOutbuf	result of the decrypt/encrypt

	// @param aInbuf	input to decrypt/encrypt

	*/

	virtual void Update(TDes8& aOutbuf,const TDesC8& aInbuf)=0;

	/**

	// Finish encryption or decryption.

	//

	// Calling Finish is optional, it is needed if the total

	// bytes is not multiple of the blocksize, or if one wants

	// to get the final IV.

	//

	// IPSEC does use the final IV.

	//

	// @param	aIV	the place to return the final IV.

	*/

	virtual void Finish(TDes8& aIV)=0;

	virtual ~CSymmetricCipher() {}

	};

// CProtocolCrypto

// ***************

/**

// Base class of the protocol implementing an algorithm library as a protocol

//

// All algorithm libraries must be derived from this base class.

*/

class CProtocolCrypto : public CProtocolBase

	{

public:

	/**

	// Return the list of supported algorithms.

	//

	// IPSEC calls this method once during the binding

	// process to find out the algorithms that are supported

	// by this library.

	//

	// @retval	aList

	//	a pointer to a new allocated array of TAlgorithmDesc.

	//	This array contains the descriptions of the supported

	//	algorithms. Can also return NULL, if not algorithms

	//	are supported at this point. The calling IPSEC will

	//	release this array, when it is not needed.

	//

	// @returns

	//	the length of the the array. May also return <= 0,

	//	in which case IPSEC will not be using any algorithms

	//	from this library.

	*/

	virtual TUint AlgorithmList(TAlgorithmDesc *&aList) = 0;

	/**

	// Create an instance of cipher algorithm

	//

	// When IPSEC requires a use of specific algorithm, it

	// asks a new instance of the algorithm by calling this

	// method.

	//

	// @param aAlg

	//	index of the algorithm in the array of descriptions

	//	that was returned by the AlgorithmList().

	//

	// @param aKey - The key value to be used in the encryption/decryption operation    

	// @return

	// @li	NULL, if algorithm could not be instantiated

	// @li	non-NULL (= new algorithm engine instance), if algorithm instantiated

	*/

	virtual CryptoSpi::CSymmetricCipher* SymmetricCipherL(TUint aAlg, const TDesC8 &aKey)=0;

#ifdef SYMBIAN_IPSEC_VOIP_SUPPORT	

	virtual CryptoSpi::CMac*  GetMacImplementationL(const TDesC8& aKey)=0;

#endif	

	/**

	// Create an instance of digest algorithm

	//

	// When IPSEC requires a use of specific algorithm, it

	// asks a new instance of the algorithm by calling this

	// method.

	//

	// @param aAlg

	//	index of the algorithm in the array of descriptions

	//	that was returned by the AlgorithmList().

	//

	// @return

	// @li	NULL, if algorithm could not be instantiated

	// @li	non-NULL (= new algorithm engine instance), if algorithm instantiated

	*/

	virtual CMessageDigestCrypto* MessageDigest(TUint aAlg)=0;

protected:

	virtual ~CProtocolCrypto() {}

	};

#endif