1 /**

     2 	@page asymmetric_cryptography Asymmetric Cryptography

     3 

     4 - @ref asymmetricWhat 

     5 - @ref asymmetricHow 

     6 

     7 @section asymmetricWhat What is asymmetric cryptography?

     8 

     9 - @ref asymmetricWhatEncryption

    10 - @ref asymmetricWhatSignature

    11 

    12 The base concept of asymmetric cryptography revolves around the existence of two

    13 keys (instead of a single secret key as in a symmetric system).  In an

    14 asymmetric cryptosystem, each participant has both a public and a private key.

    15 For schemes which are thought to be secure, it is believed that deriving the

    16 private key from the public key, or any transformation resulting from the public

    17 key, is computationally infeasible.  There are four basic primitives in

    18 asymmetric cryptography: encryption and decryption, and signing and

    19 verification.

    20 

    21 @subsection asymmetricWhatEncryption Encryption schemes.

    22 

    23 In order to encrypt a message with an asymmetric scheme, one peforms a

    24 well-known transformation on the message using the public key of the intended

    25 recipient.  Upon receipt, the receiver can decrypt this message using the inverse

    26 transformation and the associated private key.  Provided that only the intended

    27 recipient knows the associated private key, it is believed that message secrecy

    28 between the sender and receiver is achieved.

    29 

    30 @subsection asymmetricWhatSignature Signature schemes.

    31 

    32 Conversely, in order to digitally sign a message with an asymmetric scheme, one

    33 performs another well-known transformation on the message using one's own

    34 private key.  Both the original message and the resulting transformation are

    35 sent to the intended receipient.  Upon receipt, the receiver can verify that the

    36 message was signed by the associated private key by peforming the inverse

    37 operation with the public key as input, and then comparing the received message

    38 with the message obtained from the transformation of the signature.  

    39 

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

    41 

    42 The asymmetric crypto framework consists of the following logically separate

    43 concepts: 

    44 

    45 -# Key storage classes (For instance, CRSAPublicKey, CDSAPrivateKey)

    46 -# Cipher transformation classes (CRSAPKCS1v15Encryptor, CDSASigner)

    47 -# Signature representative classes (CRSASignature, CDSASignature)

    48 

    49 The first and third are simply containers for their represpective concepts.

    50 Each implementation of item two is responsible for performing one of the four

    51 primitive operations on some data using a key specified at construction.  If the

    52 operation is signing or verification, then the transformation outputs a

    53 signature representative class.  On the other hand, in the case of encryption or

    54 decryption, input and output consist of binary descriptor data.

    55 

    56 Before showing some example code, an important note about object ownership.  In

    57 general, unless otherwise stated, the following three rules apply.

    58 -# All key storage and signature representative constructors <B>take

    59 ownership</B> of objects given to them (typically RIntegers).

    60 -# All cipher transformation classes <B>only use</B> objects given to them

    61 (typically key storage classes, signature representatives, and descriptors).

    62 -# Any functions that return pointers to objects (typically the Signer classes)

    63 <B>transfer ownership</B> of the returned object to the caller.

    64 

    65 @subsection asymmetricHowEncryption Sample code for Encryption/Decryption

    66 

    67 The following code illustrates how to encrypt data using an RSA PKCS1 v1.5

    68 encryptor.  It assumes you already have access to the CRSAPublicKey, rsaPublicKey,

    69 you wish to encrypt to.

    70 

    71 @code

    72 CRSAPKCS1v15Encryptor* encryptor = CRSAPKCS1v15Encryptor::NewLC(rsaPublicKey);

    73 //As per rules described above, encryptor does not own rsaPublicKey

    74 HBufC8* encryptedMessage = HBufC8::NewLC(encryptor->MaxOutputLength());

    75 encryptor->EncryptL(messageToEncrypt, *encryptedMessage);

    76 CleanupStack::Pop(encryptedMessage);

    77 CleanupStack::PopAndDestroy(encryptor); 

    78 @endcode

    79 

    80 To subsequently decrypt, again presuming access to a CRSAPrivateKey,

    81 rsaPrivateKey.

    82 

    83 @code

    84 CRSAPKCS1v15Decryptor* decryptor = CRSAPKCS1v15Decryptor::NewLC(rsaPrivateKey);

    85 //As per rules described above, decryptor does not own rsaPrivateKey

    86 HBufC8* decryptedMessage = HBufC8::NewLC(decryptor->MaxOutputLength());

    87 encryptor->EncryptL(*decryptedMessage, *encryptedMessage);

    88 CleanupStack::Pop(decryptedMessage);

    89 CleanupStack::PopAndDestroy(decryptor); 

    90 @endcode

    91 

    92 @subsection asymmetricHowSigner Sample code for Signing/Verifying

    93 

    94 All implemented signature systems (both signing and verifying) do not perform

    95 any manipulation of the input message prior to performing their internal signing

    96 mechanism.  For instance, both CRSAPKCS1v15Signer and CDSASigner do not hash the

    97 data to be signed prior to signing it.  Some people refer to this as a "raw sign

    98 primitive".  The decision to operate this way was taken because large numbers of

    99 higher level standards dictate different ways for the data to be hashed prior to

   100 signing (and similarly for verification) and accomadating all of them

   101 significantly confused the api.  Instead it is suggested a class that handles

   102 specification specific (for example, RSA signatures for TLS or X509),

   103 pre-signing transformation is created.  Upon calling a Final()-like call on such

   104 a class, it shall return a descriptor that can be "raw signed" by the

   105 implemented signing primitives.

   106 

   107 The following code illustrates how to DSA sign an unhashed descriptor,

   108 messageToBeSigned given a CDSAPrivateKey, dsaPrivateKey.  In this case, the

   109 pre-signing transformation required by the DSA is simply a SHA1 hash.  As a

   110 result, CSHA1 is used as the specification specific, pre-signing transformation

   111 class.

   112 

   113 @code

   114 CDSASigner* signer = CDSASigner::NewLC(dsaPrivateKey);

   115 //As per rules described above, signer does not own dsaPrivateKey

   116 CSHA1* sha1 = CSHA1::NewLC();

   117 CDSASignature* signature = signer->SignL(sha1->Final(messageToBeSigned));

   118 //Caller owns signature as per rules described above.

   119 CleanupStack::PopAndDestroy(2, signer); //sha1, signer

   120 CleanupStack::PushL(signature);

   121 @endcode

   122 

   123 To subsequently verify given a CDSAPublicKey, dsaPublicKey, and a CDSASignature,

   124 signature:

   125 

   126 @code

   127 CDSAVerifier* verifier = CDSAVerifier::NewLC(dsaPublicKey);

   128 //As per rules described above, verifier does not own dsaPublicKey

   129 CSHA1* sha1 = CSHA1::NewLC();

   130 TBool result = verifier->VerifyL(sha1->Final(messageToBeVerified), *signature);

   131 CleanupStack::PopAndDestroy(2, verifier); //sha1, verifier

   132 @endcode

   133 

   134 

   135 */