/**
@page symmetric_ciphers Symmetric Cipher

- @ref symmetricWhat
- @ref symmetricHow
- @ref symmetricModes
- @ref symmetricWhich
- @ref symmetricBuffering

<hr>

@section symmetricWhat What are symmetric ciphers?

In an informal setting, symmetric ciphers can be thought of as a mapping of some
plaintext to ciphertext, via some well-known transformation function, dependent
on a secret key.  There are two basic types of symmetric ciphers:
	- Stream ciphers -- These map an n-bit stream of plaintext to a n-bit stream of 
	  ciphertext.
	- Block ciphers -- These map m n-bit blocks of plaintext to m n-bit blocks
	  of ciphertext.  Because the base unit of transformation is the n-bit
	  block, messages that are not exactly divisible by n must be padded (\c CPadding) 
	  to allow for their encryption.  Optionally, instead of padding out a
	  plaintext message to fit in a block, block ciphers allow buffering of
	  partial input blocks until the remainder of the block is given as input.
	  (@ref symmetricBuffering).  Finally, block ciphers have a concept of modes
	  (@ref symmetricModes) that provide a mechanism for making subsequent
	  blocks dependent on some number of previous blocks.

<hr>
@section symmetricHow How do I use the symmetric cipher framework?

- @ref symmetricHowIntro
- @ref symmetricHowInterface
- @ref symmetricHowFactory

@subsection symmetricHowIntro An introduction to the symmetric cipher framework.
The symmetric cipher framework collates the behaviour of all symmetric ciphers
under one interface: \c CSymmetricCipher.  This interface is intended to represent
one direction of one instance of any symmetric cipher.  One direction means
either encryption or decryption, but not both.
	  
@subsection symmetricHowInterface CSymmetricCipher interface basics.
- Block ciphers -- Here one must create an underlying transformation (\c
  CBlockTransformation) and create a \c CBufferedTransformation (which is an
  \c CSymmetricCipher) from that.  
- Stream ciphers -- These have no concept of buffering and are treated as
  specialisations of \c CSymmetricCipher.  They require no intermediate container
  class.  
	  
The following code illustrates the creation of a buffered AES ECB encryptor and an
ARC4 stream cipher.  

@code
CBlockTransformation* block = 0;
block = CAESEncryptor::NewLC(aKey);
CPadding* padding = CPaddingSSLv3::NewLC(KAESBlockSize); //The blocksize of AES (16 bytes)
CSymmetricCipher* cipher = CBufferedEncryptor::NewL(block, padding);
CleanupStack::Pop(2, block); //padding, block -> both owned by cipher
@endcode

@code
CSymmetricCipher* cipher = new(ELeave)TARC4(aKey);
CleanupStack::PushL(cipher):
@endcode

After creation, both examples are usable through the \c CSymmetricCipher interface.
So, to encrypt with either of the above ciphers one could do:

@code
HBufC8* output = HBufC8::NewLC(cipher->MaxOutputLength(input.Size()));
cipher->Process(input, output);
HBufC8* output2 = HBufC8::NewLC(cipher->MaxFinalOutputLength(input2.Size()));
cipher->ProcessFinalL(input2, output2);
@endcode

In this example, \c input and \c input2 are two arbitrary, finite length descriptors.
The derived implementations of \c CSymmetricCipher (\c CBufferedEncryptor / \c CBufferedDecryptor
and \c CStreamCipher) are responsible for handling what to do in each specific
case.  For example, in the case of an encrypting block cipher, \c ProcessFinalL()
will call the underlying padding system, which will in turn ensure that the
overall length of input plaintext is of a suitable length for encryption. For more
information on how the values returned from \c MaxOutputLength() and
\c MaxFinalOutputLength() are calculated see @ref symmetricBuffering.

@subsection symmetricHowFactory Example code for a symmetric factory class.

To simplify the process of creating symmetric encryptors and decryptors, it is
strongly recommended that applications create a factory that automates the
process for them.  The following code gives a sample factory that applications
might like to use as a reference.  It is not supplied as part of the framework
as every application has different ways of identifying symmetric cipher suites.

@code
CSymmetricCipher* CCipherFactory::BuildEncryptorL(
	TSymmetricCipherType aType,const TDesC8& aKey,const TDesC8& aIV)
	{
	CSymmetricCipher* cipher = NULL;

	if (aType==ERc4)
		{
		cipher = new(ELeave) TARC4(aKey);
		}
	else
		{
		CBlockTransformation* bT = NULL;
		switch (aType)
			{
			case EDes_cbc:
				bT = CDESEncryptor::NewL(aKey);
				break;
			case EDes_ede3_cbc:
				bT = C3DESEncryptor::NewL(aKey);
				break;
			case ERc2_cbc:
				bT = CRC2Encryptor::NewL(aKey);
				break;
			default:
				User::Leave(KErrNotSupported);
			};
		CleanupStack::PushL(bT);
		CBlockTransformation* mode = CModeCBCEncryptor::NewL(bT, aIV);
		CleanupStack::Pop(bT);	//	owned by mode
		CleanupStack::PushL(mode);
	 
		CPadding* padding = CPaddingSSLv3::NewLC(KBlockSize); //All of these ciphers use 8 byte blocks
		cipher = CBufferedEncryptor::NewL(mode, padding);
		CleanupStack::Pop(2, mode);	//padding, mode	now owned by cipher
		}
	return cipher;
	}
@endcode

Applications creating these factories need to supply an equivalent to the
\c TSymmetricCipherType enum which contains the list of identifiers representing
the cipher, padding, and mode requirements of the application.  

Note that a similar \c BuildDecryptorL() will also have to be created.

Good naming conventions dictate that applications should not pollute the
global namespace and either use their own namespace or prefix their factory
classes with identifiers that associated it with that specific application.
	 
<hr>
@section symmetricModes Symmetric Modes

When the amount of plaintext to be encrypted is larger than a single block, some
method must be employed to specify how subsequent blocks are dependent on
previous blocks.  The simplest method, known as ECB (Electronic CodeBook),
specifies that subsequent blocks are completely independent.  Therefore, two
identical blocks of plaintext will encrypt to two identical blocks of
ciphertext.  ECB has significant security drawbacks, thus most applications use
more advanced modes in which subsequent blocks are dependent on the ciphertext
of previous blocks.  The symmetric framework handles these modes through the
\c CBlockChainingMode class, which is a specialisation of \c CBlockTransformation.
The idea is that one gives an implementation of a \c CBlockChainingMode another
\c CBlockTransformation (\c CAESEncryptor, for instance) and then performs all
operations on the \c CBlockChainingMode instance.  When
<code>CBlockTransformation::Transform()</code> is called on the mode it is responsible for
calling \c Transform() on the underlying transformation that it owns and then
applying its own chaining mode transformation.

The following example shows how to create a buffered AES CBC encryptor.

@code
CBlockTransformation* basicAesBlock = 0;
CBlockTransformation* cbcBlock = 0;
basicAesBlock = CAESEncryptor::NewLC(aKey);
cbcBlock = CModeCBCEncryptor::NewL(basicAesBlock, iv);
CleanupStack::Pop(basicAesBlock); //owned by cbcBlock
CleanupStack::PushL(cbcBlock);
CPadding* padding = CPaddingSSLv3::NewLC(KAESBlockSize); //The blocksize of AES (16 bytes)
CSymmetricCipher* cipher = CBufferedEncryptor::NewL(cbcBlock, padding);
CleanupStack::Pop(2, cbcBlock); //padding, cbcBlock -> both owned by cipher
@endcode

<hr>
@section symmetricWhich Which symmetric cipher should I use?  
Generally, when implementing secure comms protocols, the cipher you use will be
dictated by the protocol specification.  However, if you are writing your own
application you should consider the use of AES (CAESEncryptor).  This is the
cipher recommended by <A HREF="http://csrc.nist.gov/cryptval/">NIST</A>.

<hr>
@section symmetricBuffering How does buffering work within the symmetric cipher framework?  

- Stream ciphers consume all content they are given.  That is, the value
  returned from <code>CSymmetricCipher::MaxOutputLength()</code> is always the same as the
  \c aInputLength parameter passed in.
- Block ciphers controlled through a \c CBufferedTransformation operate under the
  following rules:
  	- \c Process()
		-# Any previously buffered data is (logically) prepended to \c aInput.
		-# All whole blocks are transformed and appended to \c aOutput.
		-# Any remaining partial blocks, orphaned by the the above rule, are
		buffered.
	- \c ProcessFinalL()
		- Encryption
			-# Any previously buffered data is (logically) prepended to \c aInput.
			-# All whole block are transformed and appended to \c aOutput.
			-# Any remaining partial blocks are padded with underlying padding
			system to be block aligned <I>to the padding block size</I>. (In the
			vast majority of cases, the padding block size is equal to the
			block cipher block size).
			-# The resulting block(s) are transformed and appended to \c aOutput.
		- Decryption
			-# The input <b>must</b> be a multiple of the block size.
			-# Data is decrypted and unpadded using underlying padding system.
			-# Decrypted, unpadded data is appended to \c aOutput.

In all cases <code>CSymmetricCipher::MaxOutputLength()</code> returns as tight an upper bound
as possible on the number of bytes that will be returned by a call to
<code>CSymmetricCipher::Process()</code> with a specified number of input bytes.
Correspondingly, <code>CSymmetricCipher::MaxFinalOutputLength()</code> returns a similar
bound but for a pending call to <code>CSymmetricCipher::ProcessFinalL()</code>.
*/