--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-4C9C236D-71A7-5A5D-8C1C-F574DA604AF6.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 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: 
+-->
+<!DOCTYPE concept
+  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-4C9C236D-71A7-5A5D-8C1C-F574DA604AF6" xml:lang="en"><title> Asymmetric
+ciphers -- HowTo</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-CBD15CF0-5E62-5446-847E-9E7E0EB1A25E"><title> How do I use
+the asymmetric cryptographic framework? </title> <p>The asymmetric cryptographic
+framework consists of the following logically separate concepts: </p> <ol id="GUID-DC7D223E-57B3-5F96-8487-99F9A5A6CB68">
+<li id="GUID-DD6E517D-6ABE-5BED-A12C-7F4807B493E1"><p>Key storage classes
+(For instance, <xref href="GUID-5EF9067A-713F-3934-A29E-62F1414D9EF4.dita"><apiname>CRSAPublicKey</apiname></xref>, <xref href="GUID-2A19BF6D-D333-349B-9F2F-76E2F28A7044.dita"><apiname>CDSAPrivateKey</apiname></xref>) </p> </li>
+<li id="GUID-29151A18-EDC2-546C-A44F-3C746B016EDC"><p>Cipher transformation
+classes (<xref href="GUID-F845CB30-7ABE-3EB6-B1B9-C72581897D0C.dita"><apiname>CRSAPKCS1v15Encryptor</apiname></xref>, <xref href="GUID-13B5CDC3-CB8A-34C7-ADD2-FAE6D6915412.dita"><apiname>CDSASigner</apiname></xref>) </p> </li>
+<li id="GUID-8E9E241C-5464-5AB7-BD51-59C75218C3EF"><p>Signature representative
+classes (<xref href="GUID-27876B1C-C1A7-39C2-9266-0D42A86300B4.dita"><apiname>CRSASignature</apiname></xref>, <xref href="GUID-83C9D319-CC1B-355D-85EF-D58C42ABCCCA.dita"><apiname>CDSASignature</apiname></xref>) </p> </li>
+</ol> <p>The first and third are simply containers for their respective 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. </p> <p>Before
+showing some example code, an important note about object ownership. In general,
+unless otherwise stated, the following three rules apply. </p> <ol id="GUID-FFBF1C61-CEB0-573E-9003-86BC4F37319B">
+<li id="GUID-60A066D8-C525-510D-8502-D6FF245D2B78"><p>All key storage and
+signature representative constructors <b>take ownership</b> of objects given
+to them (typically <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s). </p> </li>
+<li id="GUID-E13072F8-7B6A-547F-80A8-AFC1D198C3E8"><p>All cipher transformation
+classes <b>only use</b> objects given to them (typically key storage classes,
+signature representatives, and descriptors). </p> </li>
+<li id="GUID-B4611B8A-F4D5-5209-A9B7-7B9CC237D64E"><p>Any functions that return
+pointers to objects (typically the Signer classes) <b>transfer ownership</b> of
+the returned object to the caller. </p> </li>
+</ol> <p id="GUID-EE3679E5-FE32-5C72-9EDB-B202A1C4E7FB"><b>Sample
+code for encryption/decryption</b> </p> <p>The following code illustrates
+how to encrypt data using an RSA PKCS#1 v1.5 encryptor. It assumes you already
+have access to the <xref href="GUID-5EF9067A-713F-3934-A29E-62F1414D9EF4.dita"><apiname>CRSAPublicKey</apiname></xref> you wish to encrypt to. </p> <codeblock id="GUID-A2B3F20C-3437-5F04-BC97-A1A53AF2940D" xml:space="preserve">
+CRSAPKCS1v15Encryptor* encryptor = CRSAPKCS1v15Encryptor::NewLC(rsaPublicKey);
+//As per rules described above, encryptor does not own rsaPublicKey
+HBufC8* encryptedMessage = HBufC8::NewLC(encryptor-&gt;MaxOutputLength());
+encryptor-&gt;EncryptL(messageToEncrypt, *encryptedMessage);
+CleanupStack::Pop(encryptedMessage);
+CleanupStack::PopAndDestroy(encryptor); 
+</codeblock> <p>To subsequently decrypt, again presuming access to a <xref href="GUID-53CFA8FB-1C29-3C4F-B72E-15E13B26E00F.dita"><apiname>CRSAPrivateKey</apiname></xref>. </p> <codeblock id="GUID-E822E9A2-B457-5A4E-BF7C-0A19BD0D078A" xml:space="preserve">
+CRSAPKCS1v15Decryptor* decryptor = CRSAPKCS1v15Decryptor::NewLC(rsaPrivateKey);
+//As per rules described above, decryptor does not own rsaPrivateKey
+HBufC8* decryptedMessage = HBufC8::NewLC(decryptor-&gt;MaxOutputLength());
+encryptor-&gt;EncryptL(*decryptedMessage, *encryptedMessage);
+CleanupStack::Pop(decryptedMessage);
+CleanupStack::PopAndDestroy(decryptor); 
+</codeblock> <p id="GUID-F6919BBF-8CAD-5CA6-8DA0-5836F6DE63B1"><b>Sample code
+for signing/verifying</b> </p> <p>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 <xref href="GUID-2EA351B3-155D-3B44-80FC-6F6827A52AEA.dita"><apiname>CRSAPKCS1v15Signer</apiname></xref> and <xref href="GUID-13B5CDC3-CB8A-34C7-ADD2-FAE6D6915412.dita"><apiname>CDSASigner</apiname></xref> 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
+X.509), pre-signing transformation is created. Upon calling a <codeph>Final()</codeph> -like
+call on such a class, it shall return a descriptor that can be "raw signed"
+by the implemented signing primitives. </p> <p>The following code illustrates
+how to DSA sign an unhashed descriptor, <codeph>messageToBeSigned</codeph> given
+a <xref href="GUID-2A19BF6D-D333-349B-9F2F-76E2F28A7044.dita"><apiname>CDSAPrivateKey</apiname></xref>. In this case, the pre-signing transformation
+required by the DSA is simply a SHA-1 hash. As a result, <codeph>CSHA1</codeph> is
+used as the specification specific, pre-signing transformation class. </p> <codeblock id="GUID-28326A2B-C312-506A-9AC2-C77936EF4A58" xml:space="preserve">
+CDSASigner* signer = CDSASigner::NewLC(dsaPrivateKey);
+//As per rules described above, signer does not own dsaPrivateKey
+CSHA1* sha1 = CSHA1::NewLC();
+CDSASignature* signature = signer-&gt;SignL(sha1-&gt;Final(messageToBeSigned));
+//Caller owns signature as per rules described above.
+CleanupStack::PopAndDestroy(2, signer); //sha1, signer
+CleanupStack::PushL(signature);
+</codeblock> <p>To subsequently verify given a <xref href="GUID-BBB5FEE0-368B-32D8-A30F-CFF4FACBE29A.dita"><apiname>CDSAPublicKey</apiname></xref> and
+a <xref href="GUID-83C9D319-CC1B-355D-85EF-D58C42ABCCCA.dita"><apiname>CDSASignature</apiname></xref>: </p> <codeblock id="GUID-59919AAE-C2B0-5207-8FE2-03A9D7F287AD" xml:space="preserve">
+CDSAVerifier* verifier = CDSAVerifier::NewLC(dsaPublicKey);
+//As per rules described above, verifier does not own dsaPublicKey
+CSHA1* sha1 = CSHA1::NewLC();
+TBool result = verifier-&gt;VerifyL(sha1-&gt;Final(messageToBeVerified), *signature);
+CleanupStack::PopAndDestroy(2, verifier); //sha1, verifier
+</codeblock> </section>
+</conbody></concept>
\ No newline at end of file