<?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>