<?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->MaxOutputLength());

encryptor->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->MaxOutputLength());

encryptor->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->SignL(sha1->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->VerifyL(sha1->Final(messageToBeVerified), *signature);

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

</codeblock> </section>

</conbody></concept>