--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,167 @@
+<?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>
\ No newline at end of file