/**
	@page asymmetric_cryptography Asymmetric Cryptography

- @ref asymmetricWhat 
- @ref asymmetricHow 

@section asymmetricWhat What is asymmetric cryptography?

- @ref asymmetricWhatEncryption
- @ref asymmetricWhatSignature

The base concept of asymmetric cryptography revolves around the existence of two
keys (instead of a single secret key as in a symmetric system).  In an
asymmetric cryptosystem, each participant has both a public and a private key.
For schemes which are thought to be secure, it is believed that deriving the
private key from the public key, or any transformation resulting from the public
key, is computationally infeasible.  There are four basic primitives in
asymmetric cryptography: encryption and decryption, and signing and
verification.

@subsection asymmetricWhatEncryption Encryption schemes.

In order to encrypt a message with an asymmetric scheme, one peforms a
well-known transformation on the message using the public key of the intended
recipient.  Upon receipt, the receiver can decrypt this message using the inverse
transformation and the associated private key.  Provided that only the intended
recipient knows the associated private key, it is believed that message secrecy
between the sender and receiver is achieved.

@subsection asymmetricWhatSignature Signature schemes.

Conversely, in order to digitally sign a message with an asymmetric scheme, one
performs another well-known transformation on the message using one's own
private key.  Both the original message and the resulting transformation are
sent to the intended receipient.  Upon receipt, the receiver can verify that the
message was signed by the associated private key by peforming the inverse
operation with the public key as input, and then comparing the received message
with the message obtained from the transformation of the signature.  

@section asymmetricHow How do I use the asymmetric crypto framework?

The asymmetric crypto framework consists of the following logically separate
concepts: 

-# Key storage classes (For instance, CRSAPublicKey, CDSAPrivateKey)
-# Cipher transformation classes (CRSAPKCS1v15Encryptor, CDSASigner)
-# Signature representative classes (CRSASignature, CDSASignature)

The first and third are simply containers for their represpective concepts.
Each implementation of item two is responsible for performing one of the four
primitive operations on some data using a key specified at construction.  If the
operation is signing or verification, then the transformation outputs a
signature representative class.  On the other hand, in the case of encryption or
decryption, input and output consist of binary descriptor data.

Before showing some example code, an important note about object ownership.  In
general, unless otherwise stated, the following three rules apply.
-# All key storage and signature representative constructors <B>take
ownership</B> of objects given to them (typically RIntegers).
-# All cipher transformation classes <B>only use</B> objects given to them
(typically key storage classes, signature representatives, and descriptors).
-# Any functions that return pointers to objects (typically the Signer classes)
<B>transfer ownership</B> of the returned object to the caller.

@subsection asymmetricHowEncryption Sample code for Encryption/Decryption

The following code illustrates how to encrypt data using an RSA PKCS1 v1.5
encryptor.  It assumes you already have access to the CRSAPublicKey, rsaPublicKey,
you wish to encrypt to.

@code
CRSAPKCS1v15Encryptor* encryptor = CRSAPKCS1v15Encryptor::NewLC(rsaPublicKey);
//As per rules described above, encryptor does not own rsaPublicKey
HBufC8* encryptedMessage = HBufC8::NewLC(encryptor->MaxOutputLength());
encryptor->EncryptL(messageToEncrypt, *encryptedMessage);
CleanupStack::Pop(encryptedMessage);
CleanupStack::PopAndDestroy(encryptor); 
@endcode

To subsequently decrypt, again presuming access to a CRSAPrivateKey,
rsaPrivateKey.

@code
CRSAPKCS1v15Decryptor* decryptor = CRSAPKCS1v15Decryptor::NewLC(rsaPrivateKey);
//As per rules described above, decryptor does not own rsaPrivateKey
HBufC8* decryptedMessage = HBufC8::NewLC(decryptor->MaxOutputLength());
encryptor->EncryptL(*decryptedMessage, *encryptedMessage);
CleanupStack::Pop(decryptedMessage);
CleanupStack::PopAndDestroy(decryptor); 
@endcode

@subsection asymmetricHowSigner Sample code for Signing/Verifying

All implemented signature systems (both signing and verifying) do not perform
any manipulation of the input message prior to performing their internal signing
mechanism.  For instance, both CRSAPKCS1v15Signer and CDSASigner do not hash the
data to be signed prior to signing it.  Some people refer to this as a "raw sign
primitive".  The decision to operate this way was taken because large numbers of
higher level standards dictate different ways for the data to be hashed prior to
signing (and similarly for verification) and accomadating all of them
significantly confused the api.  Instead it is suggested a class that handles
specification specific (for example, RSA signatures for TLS or X509),
pre-signing transformation is created.  Upon calling a Final()-like call on such
a class, it shall return a descriptor that can be "raw signed" by the
implemented signing primitives.

The following code illustrates how to DSA sign an unhashed descriptor,
messageToBeSigned given a CDSAPrivateKey, dsaPrivateKey.  In this case, the
pre-signing transformation required by the DSA is simply a SHA1 hash.  As a
result, CSHA1 is used as the specification specific, pre-signing transformation
class.

@code
CDSASigner* signer = CDSASigner::NewLC(dsaPrivateKey);
//As per rules described above, signer does not own dsaPrivateKey
CSHA1* sha1 = CSHA1::NewLC();
CDSASignature* signature = signer->SignL(sha1->Final(messageToBeSigned));
//Caller owns signature as per rules described above.
CleanupStack::PopAndDestroy(2, signer); //sha1, signer
CleanupStack::PushL(signature);
@endcode

To subsequently verify given a CDSAPublicKey, dsaPublicKey, and a CDSASignature,
signature:

@code
CDSAVerifier* verifier = CDSAVerifier::NewLC(dsaPublicKey);
//As per rules described above, verifier does not own dsaPublicKey
CSHA1* sha1 = CSHA1::NewLC();
TBool result = verifier->VerifyL(sha1->Final(messageToBeVerified), *signature);
CleanupStack::PopAndDestroy(2, verifier); //sha1, verifier
@endcode


*/