|
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-35E9F104-95F7-511F-B0C5-AB64BCA972D0" xml:lang="en"><title>Asymmetric |
|
13 ciphers -- guide</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <ul> |
|
15 <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> |
|
16 <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> |
|
17 <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> |
|
18 </ul> |
|
19 <section id="GUID-0A5993D6-54CC-53AB-ACB5-EB0BA535B83B"><title>What is asymmetric |
|
20 cryptography?</title> <p>Asymmetric ciphers, unlike symmetric ciphers, are |
|
21 algorithms that involve the use of two keys: a private key and a public key. |
|
22 The private key is kept secret, while the public key is made publicly available. |
|
23 For schemes which are thought to be secure, it is believed that deriving the |
|
24 private key from the public key, or any transformation resulting from the |
|
25 public key, is computationally infeasible. </p><p>This type of algorithm generates |
|
26 the keys as key pairs. This means that if one key in the pair is used to encrypt |
|
27 some data, only the other key can decrypt it, and vice versa. </p> <fig id="GUID-B943398C-3D1A-5400-8D6B-0B5CFAA91426"> |
|
28 <title>The diagram above shows the encryption and decryption process using: |
|
29 an asymmetric algorithm; a plaintext message, M; a private key, K1, and a |
|
30 public key, K2 (or vice versa); and the ciphertext, K1(M). </title> |
|
31 <image href="GUID-B172B71E-10DE-5AC6-9F10-A7EC74CE0B7F_d0e382778_href.png" placement="inline"/> |
|
32 </fig> <p>Although it varies depending on the specific algorithm, the generation |
|
33 of asymmetric keys is much slower than symmetric key generation. </p> <p>There |
|
34 are four basic primitives in asymmetric cryptography: encryption and decryption, |
|
35 and signing and verification. </p> <p id="GUID-7120B4FA-46C6-5856-AF46-942D959AD34B"><b>Encryption |
|
36 schemes</b> </p> <p>In order to encrypt a message with an asymmetric scheme, |
|
37 one performs a well-known transformation on the message using the public key |
|
38 of the intended recipient. Upon receipt, the receiver can decrypt this message |
|
39 using the inverse transformation and the associated private key. Provided |
|
40 that only the intended recipient knows the associated private key, it is believed |
|
41 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, |
|
42 in order to digitally sign a message with an asymmetric scheme, one performs |
|
43 another well-known transformation on the message using one's own private key. |
|
44 Both the original message and the resulting transformation are sent to the |
|
45 intended recipient. Upon receipt, the receiver can verify that the message |
|
46 was signed by the associated private key by performing the inverse operation |
|
47 with the public key as input, and then comparing the received message with |
|
48 the message obtained from the transformation of the signature. </p> </section> |
|
49 <section id="GUID-D495DA72-27D6-53B1-846E-B8CE4736433C"><title>Types of asymmetric |
|
50 algorithms supported</title> <p>The following asymmetric algorithms are supported: </p> <table id="GUID-8C498BD0-8D70-5024-9329-61AD4927E37C"> |
|
51 <tgroup cols="3"><colspec colname="col0" colwidth="0.65*"/><colspec colname="col1" colwidth="0.79*"/><colspec colname="col2" colwidth="1.56*"/> |
|
52 <thead> |
|
53 <row> |
|
54 <entry><p>Asymmetric algorithm</p></entry> |
|
55 <entry><p>What it's used for</p></entry> |
|
56 <entry><p>Specified in:</p></entry> |
|
57 </row> |
|
58 </thead> |
|
59 <tbody> |
|
60 <row> |
|
61 <entry><p>RSA </p> </entry> |
|
62 <entry><p>both encryption and digital signatures </p> </entry> |
|
63 <entry><p> <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2125" scope="external">PKCS#1</xref> v1.5 </p> </entry> |
|
64 </row> |
|
65 <row> |
|
66 <entry><p>DSA (Digital Signature Algorithm) </p> </entry> |
|
67 <entry><p>signing data </p> </entry> |
|
68 <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> |
|
69 </row> |
|
70 <row> |
|
71 <entry><p>DH (Diffie-Hellman) </p> </entry> |
|
72 <entry><p>secure exchange of keys between two parties </p> </entry> |
|
73 <entry><p> <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2126" scope="external">PKCS#3</xref> </p> </entry> |
|
74 </row> |
|
75 </tbody> |
|
76 </tgroup> |
|
77 </table> <p id="GUID-12ED48AC-AB99-5C0D-B035-9F86AA99055A"><b>RSA</b> </p> <p>The |
|
78 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, |
|
79 fulfil all the requirements of PKCS#1 v1.5. This is because the Cryptography |
|
80 library’s modular design allows applications utilizing it to provide their |
|
81 own mechanisms of certain operations. At minimum, signature input data (be |
|
82 prepared in compliance with PKCS#1 v1.5) must be provided by applications |
|
83 in order to support PKCS#1 v1.5. </p> <ul> |
|
84 <li><p><b>Private Key Encryption and Decryption</b> </p><p>RSA private keys |
|
85 provide functionality for encrypting and decrypting data with the private |
|
86 key. Encrypting with the private key is typically used in signature generation |
|
87 while decrypting would be used for key exchange or confidentiality of other |
|
88 small amounts of data. </p><p>The basic mathematics involved in the encryption |
|
89 and decryption is identical, the differences lay with the handling of padding; |
|
90 encryption adds padding while decryption removes and checks it. </p></li> |
|
91 <li><p><b>Padding </b></p><p>For padding the existing PKCS#1 padding mechanism |
|
92 is used. However, this interface allows the use of any defined padding mechanism. </p></li> |
|
93 <li><p><b>Key Generation </b> </p><p>Before any private keys can be used they |
|
94 need to be generated. They can be generated on the device or generated elsewhere. </p> <p>An |
|
95 RSA modulus takes the form of the product of a pair of large prime numbers, |
|
96 which will be generated randomly and considered prime if they pass a probabilistic |
|
97 primality test (where the chance of claiming a non-prime is prime is less |
|
98 than 1 in 2<sup>30</sup>). This generation process can be rather long-winded, |
|
99 even for relatively small keys. </p> <p>While there is no actually limit on |
|
100 RSA modulus sizes, for most applications they range from 512 bits to 4096 |
|
101 bits. </p></li> |
|
102 </ul> <p id="GUID-488F5006-B5CE-5D3C-8A6A-20F7BFCA3E92"><b>DSA</b> </p> <p>The |
|
103 Cryptography library allows support for NIST Digital Signature Standard (DSS) |
|
104 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 |
|
105 DSA as the algorithm for digital signatures and SHA-1 for hashing. At minimum, |
|
106 the following items must be provided by applications using the library in |
|
107 order to be fully compliant: </p> <ul> |
|
108 <li id="GUID-1ABDBEDC-705D-57AC-85A1-C37E3C34FCC7"><p>Signature input data |
|
109 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 |
|
110 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> |
|
111 <li id="GUID-FEC46D5F-0CC7-53F5-9C56-561424AABE2B"><p>A FIPS-186-2 CR 1 compliant |
|
112 random number generator must be supplied. The library provides a mechanism |
|
113 for using such a random number generator if required. </p> </li> |
|
114 <li id="GUID-BEB5CC2B-F25D-5959-A0BA-C0A2EF05EB8A"><p>For backwards compatibility |
|
115 reasons, the Cryptography library continues to allow prime moduli of less |
|
116 than 1024 bits to be used. If an application wanted to be fully compliant |
|
117 with the FIPS 186-2 CR1, it should refuse to submit requests to the Cryptography |
|
118 library to sign data with a prime modulus of less than 1024 bits. </p> </li> |
|
119 </ul> <p>The following are some important features of DSA:</p><ul> |
|
120 <li><p><b>Key Generation</b></p><p>DSA keys have an associated set of parameters, |
|
121 these parameters are generally public and used across a community of users. |
|
122 If some parameters are supplied the key generation will use those parameters |
|
123 or it will generate a set if there are none supplied. </p></li> |
|
124 <li><p><b>Parameter Generation</b></p><p>Parameter generation for DSA keys |
|
125 is implemented as specified in FIPS-186. </p></li> |
|
126 </ul> <p><b>Diffie-Hellman (DH)</b></p><p>The Cryptography library |
|
127 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 |
|
128 lack of interoperable implementations, the library does not support DH parameter |
|
129 generation. It is up to the application using the DH implementation to ensure |
|
130 that they trust the source of the parameters they intend to use for a DH key |
|
131 exchange. </p></section> |
|
132 <section id="GUID-3BBF7DAE-BBF0-52B7-83D0-9D85D2296D40"><title>Base classes |
|
133 and their derived classes </title> <p>The asymmetric cipher API is used by |
|
134 the certman (certitificate management) component for WTLS and X.509 certificate |
|
135 support and by appinst for SIS file signature verification. It is also used |
|
136 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>, |
|
137 and <xref href="GUID-59DFB240-8360-3C80-959B-CF46F77AC9CC.dita"><apiname>CDHParameters</apiname></xref> are the base classes that allow a client |
|
138 to use the supported asymmetric algorithms listed above. The classes hold |
|
139 the domain parameters used by the public key algorithms. They are used by |
|
140 some of the asymmetric algorithms to define some common mathematical structures |
|
141 used by the encryption or signature processes. </p> <p>The diagrams below |
|
142 show the main classes used in asymmetric cipher framework. Blue dotted arrows |
|
143 indicate that a class is contained or used by another class. The arrows are |
|
144 labelled with the variable(s) through which the pointed class is accessible. |
|
145 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 |
|
146 Reference material. </p> <p><b>RSA, padding and associated classes</b> </p> <fig id="GUID-6066E2FF-34DA-57F1-A90A-E126887D34A8"> |
|
147 <title>The inheritance diagram above shows the <codeph>RInteger</codeph> and <codeph>CRSAParameters</codeph> classes, |
|
148 and also the <codeph>CEncryptor</codeph>, <codeph>CDecryptor</codeph> and <codeph>CPadding</codeph> abstract |
|
149 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>. |
|
150 </title> |
|
151 <image href="GUID-2972C100-EE68-5182-927C-3C46E8F5C0DD_d0e383129_href.png" placement="inline"/> |
|
152 </fig> <fig id="GUID-28D2A983-B665-57ED-AB50-C33A9CE12045"> |
|
153 <title>The inheritance diagram above shows the <codeph>CRSASigner</codeph> and <codeph>CRSAVerifier</codeph> classes. |
|
154 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>. |
|
155 </title> |
|
156 <image href="GUID-860DCACE-4C5A-508F-B94C-12336E96D1C7_d0e383173_href.png" placement="inline"/> |
|
157 </fig> <p><b>DSA and associated classes</b> </p> <fig id="GUID-97AB5216-F33B-52B6-83B5-08B6FB623DE4"> |
|
158 <title>The inheritance diagram above shows the <codeph>CDSAParameters</codeph> class. |
|
159 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>, |
|
160 and <codeph>CDSAVerifier</codeph>. </title> |
|
161 <image href="GUID-C218732C-E675-5116-96FE-2604495C2C92_d0e383225_href.png" placement="inline"/> |
|
162 </fig> <p><b>DH and associated classes</b> </p> <fig id="GUID-0F963BD7-810F-5D1F-99BC-284DD38AAB1D"> |
|
163 <title> The inheritance diagram above shows the <codeph>CDHParameters</codeph> class. |
|
164 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> |
|
165 <image href="GUID-A3155AA1-8D42-5855-AD49-089DC510BCB0_d0e383259_href.png" placement="inline"/> |
|
166 </fig> </section> |
|
167 </conbody></concept> |