1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-4C9C236D-71A7-5A5D-8C1C-F574DA604AF6" xml:lang="en"><title> Asymmetric

    13 ciphers -- HowTo</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-CBD15CF0-5E62-5446-847E-9E7E0EB1A25E"><title> How do I use

    15 the asymmetric cryptographic framework? </title> <p>The asymmetric cryptographic

    16 framework consists of the following logically separate concepts: </p> <ol id="GUID-DC7D223E-57B3-5F96-8487-99F9A5A6CB68">

    17 <li id="GUID-DD6E517D-6ABE-5BED-A12C-7F4807B493E1"><p>Key storage classes

    18 (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>

    19 <li id="GUID-29151A18-EDC2-546C-A44F-3C746B016EDC"><p>Cipher transformation

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

    21 <li id="GUID-8E9E241C-5464-5AB7-BD51-59C75218C3EF"><p>Signature representative

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

    23 </ol> <p>The first and third are simply containers for their respective concepts.

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

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

    26 the operation is signing or verification, then the transformation outputs

    27 a signature representative class. On the other hand, in the case of encryption

    28 or decryption, input and output consist of binary descriptor data. </p> <p>Before

    29 showing some example code, an important note about object ownership. In general,

    30 unless otherwise stated, the following three rules apply. </p> <ol id="GUID-FFBF1C61-CEB0-573E-9003-86BC4F37319B">

    31 <li id="GUID-60A066D8-C525-510D-8502-D6FF245D2B78"><p>All key storage and

    32 signature representative constructors <b>take ownership</b> of objects given

    33 to them (typically <xref href="GUID-8C8CA735-6B76-3204-AFBF-F95496EDCD91.dita"><apiname>RInteger</apiname></xref> s). </p> </li>

    34 <li id="GUID-E13072F8-7B6A-547F-80A8-AFC1D198C3E8"><p>All cipher transformation

    35 classes <b>only use</b> objects given to them (typically key storage classes,

    36 signature representatives, and descriptors). </p> </li>

    37 <li id="GUID-B4611B8A-F4D5-5209-A9B7-7B9CC237D64E"><p>Any functions that return

    38 pointers to objects (typically the Signer classes) <b>transfer ownership</b> of

    39 the returned object to the caller. </p> </li>

    40 </ol> <p id="GUID-EE3679E5-FE32-5C72-9EDB-B202A1C4E7FB"><b>Sample

    41 code for encryption/decryption</b> </p> <p>The following code illustrates

    42 how to encrypt data using an RSA PKCS#1 v1.5 encryptor. It assumes you already

    43 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">

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

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

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

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

    48 CleanupStack::Pop(encryptedMessage);

    49 CleanupStack::PopAndDestroy(encryptor); 

    50 </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">

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

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

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

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

    55 CleanupStack::Pop(decryptedMessage);

    56 CleanupStack::PopAndDestroy(decryptor); 

    57 </codeblock> <p id="GUID-F6919BBF-8CAD-5CA6-8DA0-5836F6DE63B1"><b>Sample code

    58 for signing/verifying</b> </p> <p>All implemented signature systems (both

    59 signing and verifying) do not perform any manipulation of the input message

    60 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

    61 not hash the data to be signed prior to signing it. Some people refer to this

    62 as a "raw sign primitive". The decision to operate this way was taken because

    63 large numbers of higher level standards dictate different ways for the data

    64 to be hashed prior to signing (and similarly for verification) and accomadating

    65 all of them significantly confused the api. Instead it is suggested a class

    66 that handles specification specific (for example, RSA signatures for TLS or

    67 X.509), pre-signing transformation is created. Upon calling a <codeph>Final()</codeph> -like

    68 call on such a class, it shall return a descriptor that can be "raw signed"

    69 by the implemented signing primitives. </p> <p>The following code illustrates

    70 how to DSA sign an unhashed descriptor, <codeph>messageToBeSigned</codeph> given

    71 a <xref href="GUID-2A19BF6D-D333-349B-9F2F-76E2F28A7044.dita"><apiname>CDSAPrivateKey</apiname></xref>. In this case, the pre-signing transformation

    72 required by the DSA is simply a SHA-1 hash. As a result, <codeph>CSHA1</codeph> is

    73 used as the specification specific, pre-signing transformation class. </p> <codeblock id="GUID-28326A2B-C312-506A-9AC2-C77936EF4A58" xml:space="preserve">

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

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

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

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

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

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

    80 CleanupStack::PushL(signature);

    81 </codeblock> <p>To subsequently verify given a <xref href="GUID-BBB5FEE0-368B-32D8-A30F-CFF4FACBE29A.dita"><apiname>CDSAPublicKey</apiname></xref> and

    82 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">

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

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

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

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

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

    88 </codeblock> </section>

    89 </conbody></concept>