<?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" xml:lang="en"><title>Asymmetric
ciphers -- guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<ul>
<li id="GUID-7D18EC96-7474-5AA8-873A-475B07CCB9C4"><p><xref href="GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0.dita#GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0/GUID-0A5993D6-54CC-53AB-ACB5-EB0BA535B83B">What is asymmetric cryptography?</xref> </p> </li>
<li id="GUID-3F8B68B8-63A3-5D8E-9376-05105EE27E26"><p><xref href="GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0.dita#GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0/GUID-D495DA72-27D6-53B1-846E-B8CE4736433C">Types of asymmetric algorithms supported</xref> </p> </li>
<li id="GUID-CCC7DAF4-1A46-59FB-82EE-B4F2BF19AACE"><p><xref href="GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0.dita#GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0/GUID-3BBF7DAE-BBF0-52B7-83D0-9D85D2296D40">Base classes and their derived classes</xref> </p> </li>
</ul>
<section id="GUID-0A5993D6-54CC-53AB-ACB5-EB0BA535B83B"><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">
<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_d0e382778_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"><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"><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"><title>Types of asymmetric
algorithms supported</title> <p>The following asymmetric algorithms are supported: </p> <table id="GUID-8C498BD0-8D70-5024-9329-61AD4927E37C">
<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"><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"><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"><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"><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"><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"><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">
<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_d0e383129_href.png" placement="inline"/>
</fig> <fig id="GUID-28D2A983-B665-57ED-AB50-C33A9CE12045">
<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_d0e383173_href.png" placement="inline"/>
</fig> <p><b>DSA and associated classes</b> </p> <fig id="GUID-97AB5216-F33B-52B6-83B5-08B6FB623DE4">
<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_d0e383225_href.png" placement="inline"/>
</fig> <p><b>DH and associated classes</b> </p> <fig id="GUID-0F963BD7-810F-5D1F-99BC-284DD38AAB1D">
<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_d0e383259_href.png" placement="inline"/>
</fig> </section>
</conbody></concept>