<?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-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1" xml:lang="en"><title>Asymmetric

ciphers -- guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-7D18EC96-7474-5AA8-873A-475B07CCB9C4-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-1-1"><p><xref href="GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1.dita#GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1/GUID-0A5993D6-54CC-53AB-ACB5-EB0BA535B83B-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-2">What is asymmetric cryptography?</xref> </p> </li>

<li id="GUID-3F8B68B8-63A3-5D8E-9376-05105EE27E26-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-1-2"><p><xref href="GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1.dita#GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1/GUID-D495DA72-27D6-53B1-846E-B8CE4736433C-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3">Types of asymmetric algorithms supported</xref> </p> </li>

<li id="GUID-CCC7DAF4-1A46-59FB-82EE-B4F2BF19AACE-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-1-3"><p><xref href="GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1.dita#GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1/GUID-3BBF7DAE-BBF0-52B7-83D0-9D85D2296D40-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-4">Base classes and their derived classes</xref> </p> </li>

</ul>

<section id="GUID-0A5993D6-54CC-53AB-ACB5-EB0BA535B83B-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-2"><title>What is asymmetric

cryptography?</title> <p>Asymmetric ciphers, unlike symmetric ciphers, are

algorithms that involve the use of two keys: a private key and a public key.

The private key is kept secret, while the public key is made publicly available.

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

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

public key, is computationally infeasible. </p><p>This type of algorithm generates

the keys as key pairs. This means that if one key in the pair is used to encrypt

some data, only the other key can decrypt it, and vice versa. </p> <fig id="GUID-B943398C-3D1A-5400-8D6B-0B5CFAA91426-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-2-4">

<title>The diagram above shows the encryption and decryption process using:

an asymmetric algorithm; a plaintext message, M; a private key, K1, and a

public key, K2 (or vice versa); and the ciphertext, K1(M).            </title>

<image href="GUID-B172B71E-10DE-5AC6-9F10-A7EC74CE0B7F_d0e615026_href.png" placement="inline"/>

</fig> <p>Although it varies depending on the specific algorithm, the generation

of asymmetric keys is much slower than symmetric key generation. </p> <p>There

are four basic primitives in asymmetric cryptography: encryption and decryption,

and signing and verification. </p> <p id="GUID-7120B4FA-46C6-5856-AF46-942D959AD34B-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-2-7"><b>Encryption

schemes</b> </p> <p>In order to encrypt a message with an asymmetric scheme,

one performs a well-known transformation on the message using the public key

of the intended recipient. Upon receipt, the receiver can decrypt this message

using the inverse transformation and the associated private key. Provided

that only the intended recipient knows the associated private key, it is believed

that message secrecy between the sender and receiver is achieved. </p> <p id="GUID-3C282457-ED91-5B01-AF81-731D6AEABBF8-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-2-9"><b>Signature schemes</b> </p> <p>Conversely,

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

another well-known transformation on the message using one's own private key.

Both the original message and the resulting transformation are sent to the

intended recipient. Upon receipt, the receiver can verify that the message

was signed by the associated private key by performing the inverse operation

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

the message obtained from the transformation of the signature. </p> </section>

<section id="GUID-D495DA72-27D6-53B1-846E-B8CE4736433C-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3"><title>Types of asymmetric

algorithms supported</title> <p>The following asymmetric algorithms are supported: </p> <table id="GUID-8C498BD0-8D70-5024-9329-61AD4927E37C-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3-3">

<tgroup cols="3"><colspec colname="col0" colwidth="0.65*"/><colspec colname="col1" colwidth="0.79*"/><colspec colname="col2" colwidth="1.56*"/>

<thead>

<row>

<entry><p>Asymmetric algorithm</p></entry>

<entry><p>What it's used for</p></entry>

<entry><p>Specified in:</p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p>RSA </p> </entry>

<entry><p>both encryption and digital signatures </p> </entry>

<entry><p> <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2125" scope="external">PKCS#1</xref> v1.5 </p> </entry>

</row>

<row>

<entry><p>DSA (Digital Signature Algorithm) </p> </entry>

<entry><p>signing data </p> </entry>

<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips186-2/fips186-2-change1.pdf" scope="external">FIPS 186-2</xref> CR1 </p> </entry>

</row>

<row>

<entry><p>DH (Diffie-Hellman) </p> </entry>

<entry><p>secure exchange of keys between two parties </p> </entry>

<entry><p> <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2126" scope="external">PKCS#3</xref>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p id="GUID-12ED48AC-AB99-5C0D-B035-9F86AA99055A-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3-4"><b>RSA</b> </p> <p>The

Cryptography library allows support for RSA as specified in <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2125" scope="external">PKCS#1</xref> v1.5. The library does not, in and of itself,

fulfil all the requirements of PKCS#1 v1.5. This is because the Cryptography

library’s modular design allows applications utilizing it to provide their

own mechanisms of certain operations. At minimum, signature input data (be

prepared in compliance with PKCS#1 v1.5) must be provided by applications

in order to support PKCS#1 v1.5. </p> <ul>

<li><p><b>Private Key Encryption and Decryption</b> </p><p>RSA private keys

provide functionality for encrypting and decrypting data with the private

key. Encrypting with the private key is typically used in signature generation

while decrypting would be used for key exchange or confidentiality of other

small amounts of data. </p><p>The basic mathematics involved in the encryption

and decryption is identical, the differences lay with the handling of padding;

encryption adds padding while decryption removes and checks it. </p></li>

<li><p><b>Padding </b></p><p>For padding the existing PKCS#1 padding mechanism

is used. However, this interface allows the use of any defined padding mechanism. </p></li>

<li><p><b>Key Generation </b> </p><p>Before any private keys can be used they

need to be generated. They can be generated on the device or generated elsewhere. </p> <p>An

RSA modulus takes the form of the product of a pair of large prime numbers,

which will be generated randomly and considered prime if they pass a probabilistic

primality test (where the chance of claiming a non-prime is prime is less

than 1 in 2<sup>30</sup>). This generation process can be rather long-winded,

even for relatively small keys. </p> <p>While there is no actually limit on

RSA modulus sizes, for most applications they range from 512 bits to 4096

bits. </p></li>

</ul> <p id="GUID-488F5006-B5CE-5D3C-8A6A-20F7BFCA3E92-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3-7"><b>DSA</b> </p> <p>The

Cryptography library allows support for NIST Digital Signature Standard (DSS)

as specified in <xref href="http://csrc.nist.gov/publications/fips/fips186-2/fips186-2-change1.pdf" scope="external">FIPS 186-2</xref> change request 1. The standard specifies

DSA as the algorithm for digital signatures and SHA-1 for hashing. At minimum,

the following items must be provided by applications using the library in

order to be fully compliant: </p> <ul>

<li id="GUID-1ABDBEDC-705D-57AC-85A1-C37E3C34FCC7-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3-9-1"><p>Signature input data

must be hashed with SHA-1 as specified in <xref href="http://www.itl.nist.gov/fipspubs/fip180-1.htm" scope="external">FIPS 180-1</xref>. </p> <p> <i>or should it be</i>  </p> <p>Signature

input data must be hashed with SHA-1 as specified in <xref href="http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf" scope="external">FIPS 180-2</xref>. </p> </li>

<li id="GUID-FEC46D5F-0CC7-53F5-9C56-561424AABE2B-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3-9-2"><p>A FIPS-186-2 CR 1 compliant

random number generator must be supplied. The library provides a mechanism

for using such a random number generator if required. </p> </li>

<li id="GUID-BEB5CC2B-F25D-5959-A0BA-C0A2EF05EB8A-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-3-9-3"><p>For backwards compatibility

reasons, the Cryptography library continues to allow prime moduli of less

than 1024 bits to be used. If an application wanted to be fully compliant

with the FIPS 186-2 CR1, it should refuse to submit requests to the Cryptography

library to sign data with a prime modulus of less than 1024 bits. </p> </li>

</ul> <p>The following are some important features of DSA:</p><ul>

<li><p><b>Key Generation</b></p><p>DSA keys have an associated set of parameters,

these parameters are generally public and used across a community of users.

If some parameters are supplied the key generation will use those parameters

or it will generate a set if there are none supplied. </p></li>

<li><p><b>Parameter Generation</b></p><p>Parameter generation for DSA keys

is implemented as specified in FIPS-186. </p></li>

</ul> <p><b>Diffie-Hellman (DH)</b></p><p>The Cryptography library

supports Diffie-Hellman as specified in <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2126" scope="external">PKCS#3</xref>. Note that due to security concerns and a serious

lack of interoperable implementations, the library does not support DH parameter

generation. It is up to the application using the DH implementation to ensure

that they trust the source of the parameters they intend to use for a DH key

exchange. </p></section>

<section id="GUID-3BBF7DAE-BBF0-52B7-83D0-9D85D2296D40-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-4"><title>Base classes

and their derived classes </title> <p>The asymmetric cipher API is used by

the certman (certitificate management) component for WTLS and X.509 certificate

support and by appinst for SIS file signature verification. It is also used

by Networking (TLS/IPSec). </p> <p> <xref href="GUID-BFC47C18-2046-3B2C-8A22-74E0D4E59BFB.dita"><apiname>CRSAParameters</apiname></xref>, <xref href="GUID-76994822-5482-3055-9AF3-82A67845EB68.dita"><apiname>CDSAParameters</apiname></xref>,

and <xref href="GUID-59DFB240-8360-3C80-959B-CF46F77AC9CC.dita"><apiname>CDHParameters</apiname></xref> are the base classes that allow a client

to use the supported asymmetric algorithms listed above. The classes hold

the domain parameters used by the public key algorithms. They are used by

some of the asymmetric algorithms to define some common mathematical structures

used by the encryption or signature processes. </p> <p>The diagrams below

show the main classes used in asymmetric cipher framework. Blue dotted arrows

indicate that a class is contained or used by another class. The arrows are

labelled with the variable(s) through which the pointed class is accessible.

The color of the boxes indicates the type of Symbian class, i.e., <codeph>M</codeph>, <codeph>C</codeph>, <codeph>R</codeph> or <codeph>T</codeph> class. For detailed information on each component see the Cryptography API

Reference material. </p> <p><b>RSA, padding and associated classes</b> </p> <fig id="GUID-6066E2FF-34DA-57F1-A90A-E126887D34A8-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-4-6">

<title>The inheritance diagram above shows the <codeph>RInteger</codeph> and <codeph>CRSAParameters</codeph> classes,

and also the <codeph>CEncryptor</codeph>, <codeph>CDecryptor</codeph> and <codeph>CPadding</codeph> abstract

classes. Also shown are the following classes from the Cryptography API: <codeph>TInteger</codeph>, <codeph>MCryptoSystem</codeph>, <codeph>CRSAPKCS1v15Decryptor</codeph>, <codeph>CRSAPKCS1v15Encryptor</codeph>, <codeph>CRSAPrivateKey</codeph>, <codeph>CRSAPublicKey</codeph>, <codeph>CRSAPrivateKeyStandard</codeph>, <codeph>CRSAPrivateKeyCRT</codeph>, <codeph>CRSAKeyPair</codeph>, <codeph>CPaddingPKCS7</codeph>, <codeph>CPaddingPKCS1Encryption</codeph>, <codeph>CPaddingNone</codeph>, <codeph>CPaddingPKCS1Signature</codeph>, and <codeph>CPaddingSSLv3</codeph>.

              </title>

<image href="GUID-2972C100-EE68-5182-927C-3C46E8F5C0DD_d0e615377_href.png" placement="inline"/>

</fig> <fig id="GUID-28D2A983-B665-57ED-AB50-C33A9CE12045-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-4-7">

<title>The inheritance diagram above shows the <codeph>CRSASigner</codeph> and <codeph>CRSAVerifier</codeph> classes.

Also shown are the following classes from the Cryptography API: <codeph>MSignatureSystem</codeph>, <codeph>CSigner</codeph>, <codeph>CRSAPKCS1v15Signer</codeph>, <codeph>CRSAParameters</codeph>, <codeph>CRSAPrivateKey</codeph>, <codeph>CRSAPublicKey</codeph>, <codeph>CPadding</codeph>, <codeph>CPaddingPKCS1Signature</codeph>, <codeph>CVerifier</codeph>, and <codeph>CRSAPKCS1v15Verifier</codeph>.

              </title>

<image href="GUID-860DCACE-4C5A-508F-B94C-12336E96D1C7_d0e615421_href.png" placement="inline"/>

</fig> <p><b>DSA and associated classes</b> </p> <fig id="GUID-97AB5216-F33B-52B6-83B5-08B6FB623DE4-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-4-9">

<title>The inheritance diagram above shows the <codeph>CDSAParameters</codeph> class.

Also shown are the following classes from the Cryptography API: <codeph>MSignatureSystem</codeph>, <codeph>TInteger</codeph>, <codeph>RInteger</codeph>, <codeph>CSigner</codeph>, <codeph>CDSASigner</codeph>, <codeph>CDSASignature</codeph>, <codeph>CDSAPrimeCertificate</codeph>, <codeph>CDSAKeyPair</codeph>, <codeph>CDSAPrivateKey</codeph>, <codeph>CDSAPublicKey</codeph>, <codeph>CVerifier</codeph>,

and <codeph>CDSAVerifier</codeph>.               </title>

<image href="GUID-C218732C-E675-5116-96FE-2604495C2C92_d0e615473_href.png" placement="inline"/>

</fig> <p><b>DH and associated classes</b> </p> <fig id="GUID-0F963BD7-810F-5D1F-99BC-284DD38AAB1D-GENID-1-12-1-26-1-1-11-1-1-5-1-5-1-2-4-11">

<title> The inheritance diagram above shows the <codeph>CDHParameters</codeph> class.

Also shown are the following classes from the Cryptography API:  <codeph>TInteger</codeph>, <codeph>RInteger</codeph>, <codeph>CDHPrivateKey</codeph>, <codeph>CDHPublicKey</codeph>, <codeph>CDH</codeph>, and <codeph>CDHKeyPair</codeph>. </title>

<image href="GUID-A3155AA1-8D42-5855-AD49-089DC510BCB0_d0e615507_href.png" placement="inline"/>

</fig> </section>

</conbody></concept>