Symbian3/SDK/Source/GUID-3FB8AC96-209B-5B1E-8139-BA2D858CBF2F.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     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-3FB8AC96-209B-5B1E-8139-BA2D858CBF2F" xml:lang="en"><title>CryptoSPI
       
    13 Overview (weak build)</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <section><title>Purpose</title> <p>This is an overview of the weak CryptoSPI
       
    15 APIs. An overview and other documents for the strong CryptoSPI APIs are available
       
    16 in the Security Supplement, which is delivered to device creators with the
       
    17 CBR. </p> </section>
       
    18 <section><title>Introduction</title> <p>CryptoSPI (<filepath>cryptospi.dll</filepath>)
       
    19 is a framework for implementing cryptographic algorithms, hash algorithms
       
    20 and random number generation. It allows alternative implementations to be
       
    21 added by Symbian platform device creators as plug-in DLLs. </p> <p><b>Weak
       
    22 and strong builds</b> </p> <p>The cryptography APIs are subject to export
       
    23 control regulations. The export of cryptography refers to the transfer from
       
    24 one country to another of technology related to cryptography. Export control
       
    25 regulations are for national security considerations. </p> <p>Export control
       
    26 applies to key sizes that are greater than a size specified by the UK Government.
       
    27 Currently, symmetric algorithms with keys greater than 56 bits and asymmetric
       
    28 algorithms with keys greater than 512 bits are export controlled. To comply
       
    29 with government export control rules, the Cryptography library is delivered
       
    30 in two builds: </p> <ul>
       
    31 <li id="GUID-B6D2DA99-B26C-563C-AB89-12B55BEA3F86"><p>A weak build </p> <p>The
       
    32 weak build (weak_cryptography.dll) includes cryptography algorithms that are
       
    33 not export controlled. The weak build rejects requests to apply an encryption
       
    34 scheme with key sizes greater than 56 bits for symmetric algorithms and 512
       
    35 bits for asymmetric algorithms. </p> </li>
       
    36 <li id="GUID-8C455A29-794A-50F4-8503-FCFBF55A731B"><p>A strong build </p> <p>The
       
    37 strong build (strong_cryptography.dll) includes cryptography algorithms that
       
    38 are export controlled. </p> </li>
       
    39 </ul> <p> <b> Note:</b> The API guide and other documentation for cryptography
       
    40 is broken up in the same way as the cryptography library. This document provides
       
    41 information on the weak build. It also gives a brief summary of the algorithms
       
    42 provided in the strong build. The strong cryptography API guide and other
       
    43 documentation is not available from the Symbian Developer Library. It is delivered
       
    44 to device creators with the CBR. </p> </section>
       
    45 <section><title>Architectural relationships</title> <p>Before the introduction
       
    46 of CryptoSPI, features such as cryptographic algorithms, hash algorithms and
       
    47 random number generation were provided by the Symbian platform in <filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>. </p> <p> <filepath>softwarecrypto.dll</filepath> is
       
    48 a plug-in module (implemented in the Symbian platform) that provides software-based
       
    49 implementations of all the cryptographic algorithms that were previously implemented
       
    50 by the legacy components (<filepath>cryptography.dll</filepath>, <filepath>hash.dll</filepath> and <filepath>random.dll</filepath>).
       
    51 The legacy APIs have been re-implemented internally to use the new framework
       
    52 via shim classes. <filepath>hardwarecrypto.dll</filepath> is an arbitrary
       
    53 name used in the diagram to represent a plug-in module provided by device
       
    54 creators. The plug-ins and <filepath>cryptospi.dll</filepath> have a dependency
       
    55 on <filepath>cryptography.dll</filepath> because it implements big integers. </p> <fig id="GUID-F3B5470E-25D5-5BDD-8F47-480D39C4CDB5">
       
    56 <title>              CryptoSPI dependencies            </title>
       
    57 <image href="GUID-708FC2C8-19BB-5EFC-A8CD-B0E9E96A5409_d0e360594_href.png" placement="inline"/>
       
    58 </fig> </section>
       
    59 <section><title>API summary</title> <p>The <codeph>CryptoSpi</codeph> namespace
       
    60 is defined for all CryptoSPI classes to differentiate them from the legacy
       
    61 APIs with the same names. </p> <p><b>CryptoSPI scope</b> </p><p>CryptoSPI
       
    62 provides equivalent implementations of all algorithms supported by the legacy
       
    63 APIs, including hashing and random number generation. The following algorithms
       
    64 are implemented in <filepath>softwarecrypto.dll</filepath>: </p><p>This
       
    65 section includes summary details of the following (For more information on
       
    66 the strong APIs, see the Security Supplement, which is delivered to device
       
    67 creators with the CBR): </p><ul>
       
    68 <li><p>cryptographic algorithms </p></li>
       
    69 <li><p>hash algorithms </p></li>
       
    70 <li><p>random number generator</p></li>
       
    71 </ul> <p id="GUID-19D541E1-1868-527A-A376-3ED1D0F428D8"><b>Cryptographic algorithms</b> </p> <p>Cryptographic
       
    72 algorithms allow data to be encrypted and decrypted. They include: </p> <ul>
       
    73 <li id="GUID-C68FBFD7-EE10-5CDD-835B-62D770D7E9E5"><p> <b>Symmetric ciphers</b> —
       
    74 algorithms that require communicating parties to hold a shared secret. They
       
    75 are fast and are used for the transmission of bulk data. </p> </li>
       
    76 <li id="GUID-D7ADFE85-C48D-5E2B-BAF0-CBF68B676C3E"><p> <b>Asymmetric ciphers</b> —
       
    77 algorithms which have two keys, one private to the keys' owner and one which
       
    78 can be published. They are slow compared to symmetric ciphers and are used
       
    79 to exchange a symmetric key before transmission of data encrypted using that
       
    80 key. </p> </li>
       
    81 </ul> <p>The Cryptography algorithms are part of the strong build. To access
       
    82 details of how to implement them you need to access the Security Supplement,
       
    83 which is delivered to device creators with the CBR. </p> <p id="GUID-1C869199-DF50-5DCA-AD0D-5EA31EADA384"><b>Hash
       
    84 algorithms</b> </p> <p><xref href="GUID-679390E8-1DE6-55F0-9A0C-60D58956A1E3.dita">Hash
       
    85 algorithms</xref> compact a message down to a short series of bytes from which
       
    86 it is impossible to regenerate the message. They are used with an asymmetric
       
    87 cipher to generate signatures. </p> <p>The following hash algorithms are supported: </p> <table id="GUID-2ECEAC82-2DEA-5907-9443-ED023DAD2653">
       
    88 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
       
    89 <thead>
       
    90 <row>
       
    91 <entry>Hash algorithms</entry>
       
    92 <entry>Specified in</entry>
       
    93 </row>
       
    94 </thead>
       
    95 <tbody>
       
    96 <row>
       
    97 <entry><p>MD2 </p> </entry>
       
    98 <entry><p> <xref href="http://www.ietf.org/rfc/rfc1319.txt" scope="external">RFC
       
    99 1319 </xref>  </p> </entry>
       
   100 </row>
       
   101 <row>
       
   102 <entry><p>MD4 </p> </entry>
       
   103 <entry><p> <xref href="http://www.ietf.org/rfc/rfc1320.txt" scope="external">RFC
       
   104 1320</xref>  </p> </entry>
       
   105 </row>
       
   106 <row>
       
   107 <entry><p>MD5 </p> </entry>
       
   108 <entry><p> <xref href="http://www.ietf.org/rfc/rfc1321.txt" scope="external">RFC
       
   109 1321</xref>  </p> </entry>
       
   110 </row>
       
   111 <row>
       
   112 <entry><p>SHA1 </p> </entry>
       
   113 <entry><p> <xref href="http://www.itl.nist.gov/fipspubs/fip180-1.htm" scope="external">FIPS
       
   114 180-1</xref> and <xref href="http://www.ietf.org/rfc/rfc3174.txt" scope="external">RFC
       
   115 3174</xref>  </p> </entry>
       
   116 </row>
       
   117 </tbody>
       
   118 </tgroup>
       
   119 </table> <p><i>Hashes in HMAC mode</i> </p> <ul>
       
   120 <li id="GUID-551F9056-7110-5002-8495-D31BAFDCFEA8"><p>MD2 </p> </li>
       
   121 <li id="GUID-4C0AB778-90A5-5EA8-9C26-29248FA9DF63"><p>MD4 </p> </li>
       
   122 <li id="GUID-CC9931AA-B0F4-5832-8C9E-78FBE95F7AEB"><p>MD5 </p> </li>
       
   123 <li id="GUID-6307D557-0AA8-5CC0-88D4-464C31FF1960"><p>SHA1 </p> </li>
       
   124 <li id="GUID-CD13BA31-4543-5E95-8DB4-F9F790F7816D"><p>SHA-224 </p> </li>
       
   125 <li id="GUID-1A2A7EAA-85F5-5516-9590-A2DBA7BBE7FC"><p>SHA-256 </p> </li>
       
   126 <li id="GUID-AACCA093-2CD3-55ED-9D80-298DAB45BBFC"><p>SHA-384 </p> </li>
       
   127 <li id="GUID-7A6E01DF-635C-5EEA-BD53-3CD47CF50160"><p>SHA-512 </p> </li>
       
   128 </ul> <p>HMAC mode is specified in <xref href="http://www.ietf.org/rfc/rfc2104.txt" scope="external">RFC 2104</xref>. </p> <p id="GUID-58FB3D9C-A557-59C7-9AA8-37C77FE9002E"><b>Random
       
   129 Number Generator (RNG)</b> </p> <p><xref href="GUID-0B2245C5-766B-5CF1-8A0C-DD98CEEEBB05.dita">RNG</xref> is
       
   130 the basis for the cryptographic key generation. It uses the RANROT algorithm
       
   131 seeded by random data available on the target hardware (for example free running
       
   132 counters available on ARM processers). </p> <p id="GUID-CE692E1B-A0FF-5CF1-8D22-50BC0D12B83A"><b>Supporting
       
   133 APIs</b> </p> <ul>
       
   134 <li id="GUID-A314831E-84E2-5F33-AF4F-6187020FEB88"><p> <b>Password Based Encryption
       
   135 (PBE)</b> — provides an API to encrypt and decrypt data with a user-supplied
       
   136 password </p> </li>
       
   137 <li id="GUID-FE498ED5-276A-53D1-9283-A4406001B532"><p> <b>Padding</b> — is
       
   138 extra bits concatenated with a key, password, or plaintext to make their length
       
   139 equal to the block size. It defines the way blocks are filled with data when
       
   140 the data to be encrypted is smaller than the block size. Padding is added
       
   141 at encryption and checked on decryption. </p> </li>
       
   142 <li id="GUID-A8A99555-C8BF-5466-8610-67F55A2B36D5"><p> <b>Big integers</b> —
       
   143 arbitrarily large integers. </p> <p>Note that although some functions are
       
   144 exported, the intent is that big integers are only for use by the Cryptography
       
   145 library and not by application code. Big integers are implemented in <filepath>cryptography.dll</filepath>. </p> </li>
       
   146 </ul> <p><b>Implementing CryptoSPI algorithms</b> </p> <p>The guide to CryptoSPI
       
   147 is not publicly available, but the following documents show how to use CryptoSPI
       
   148 to generate random numbers and create a hash: </p> <ul>
       
   149 <li id="GUID-6C8E6AEC-5E02-5608-A9D5-392138EB2538"><p><xref href="GUID-0CD273A2-434C-52E0-B840-CCF24B2853B8.dita">Generating
       
   150 random bytes</xref>  </p> </li>
       
   151 </ul> </section>
       
   152 </conbody></concept>