<?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-712DF59D-FAE1-592E-82A6-4E323676F5B8" xml:lang="en"><title>Symmetric

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

<ul>

<li id="GUID-A66ADA26-979E-5B4A-824F-29C182AFCB24"><p> <xref href="GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita#GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8/GUID-6F996812-1D73-509B-9CED-DD672728D597">What are symmetric ciphers?</xref>  </p> </li>

<li id="GUID-46055BED-B538-5B49-BD43-A2E3AA3368E8"><p> <xref href="GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita#GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8/GUID-BDF6E245-AE19-55D6-89ED-BCBE0FCF006B">Block and stream ciphers</xref>  </p> </li>

<li id="GUID-5B9FF3E3-3732-5A75-B429-23B318C0CCBF"><p> <xref href="GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita#GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8/GUID-A4E43A90-A66F-5868-BD94-DA709B75431B">Types of symmetric algorithms supported</xref>  </p> </li>

<li id="GUID-26930CA6-C2AF-58DB-87AB-803481AA3DED"><p> <xref href="GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita#GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8/GUID-66E8AD5D-A9FF-51E3-897D-D5EC3D66903A">Base classes and their derived classes</xref>  </p> </li>

</ul>

<section id="GUID-6F996812-1D73-509B-9CED-DD672728D597"><title>What are symmetric

ciphers? </title> <p>Symmetric algorithms are much faster than asymmetric

algorithms so are used to encrypt and decrypt large amounts of data. In an

informal setting, symmetric ciphers can be thought of as a mapping of some

plaintext to ciphertext, via some well-known transformation function, dependent

on a single secret key. Symmetric algorithms have the property that if a message

is encrypted under a given key, it can only be decrypted using the same key: </p> <fig id="GUID-FDB090BE-13DA-5941-8403-F42C3DF880BF">

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

a symmetric algorithm; a plaintext message, M; a symmetric key, K; and the

ciphertext, K(M).</title>

<image href="GUID-669190F8-3BE9-58FC-B689-00F06FDAD74D_d0e363158_href.png" placement="inline"/>

</fig> <p>So it provides secrecy and also some kind of authentication. If

Alice encrypts a secret using a key known only to her, then only she can access

the secrets. </p><p>It can also be used for communication: if Alice shares

a key with Bob (and only Bob), then she can encrypt her messages with that

key and send it to Bob, and only Bob can decrypt them. In this case the key

is a 'shared secret' enabling private communications. </p><p>There are two

basic types of symmetric ciphers: <xref href="GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita#GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8/GUID-BDF6E245-AE19-55D6-89ED-BCBE0FCF006B">block

ciphers and stream ciphers</xref>. </p> </section>

<section id="GUID-BDF6E245-AE19-55D6-89ED-BCBE0FCF006B"><title>Block and stream

ciphers</title> <ul>

<li id="GUID-D0F3A85C-2DB3-57BE-A12B-102943DB68C9"><p> <b> Stream ciphers</b> are

essentially functions that are initialized with a key, and output a stream

of pseudorandom bits, this 'keystream' is typically XOR-ed with the plaintext

to generate the ciphertext. So they encrypt a bit of plaintext at a time.

They map an <i>n</i> -bit stream of plaintext to a <i>n</i> -bit stream of

ciphertext. </p> </li>

<li id="GUID-25F8F07B-C60E-5B6D-9224-B7E4E89D15A3"><p> <b>Block ciphers</b> encrypt

several bits at once in a fixed-size block. That is, they map <i>m</i>  <i>n</i> -bit

blocks of plaintext to <i>m</i>  <i>n</i> -bit blocks of ciphertext. The cipher

and its mode of operation define the block size: the plaintext is split up

into appropriately-sized blocks and each block is fed into the cipher. </p> <p>There

are two issues here that don't occur with stream ciphers: </p> <ul>

<li id="GUID-2C88F6DF-B8F8-5DF3-8955-03DA02371DEC"><p> <b> padding</b>: the

total size of the input has to be a multiple of the block size, so the plaintext

usually has to be padded to fit (see the class <xref href="GUID-FFD4A90B-CCF7-33D2-802A-A44E2434FAE9.dita"><apiname>CPadding</apiname></xref>).

Optionally, instead of padding out a plaintext message to fit in a block,

block ciphers allow buffering of partial input blocks until the remainder

of the block is given as input. (see <xref href="GUID-CFF1BCCA-5D07-5B8A-9363-AD11EEEAB485.dita#GUID-CFF1BCCA-5D07-5B8A-9363-AD11EEEAB485/GUID-3393A9D6-CB78-5740-B250-F9C1C26C59BD">How

does buffering work within the symmetric cipher framework?</xref> and <xref href="http://www.rsasecurity.com/rsalabs/node.asp?id=2129" scope="external">PKCS#7</xref>). </p> </li>

<li id="GUID-EE6C6890-8F7E-50AD-AEB9-10C43E931DE9"><p> <b>combining blocks</b>:

if you just encrypt each plaintext block with the cipher and then concatenate

the ciphertext blocks, then an attacker who knows something about the structure

can switch the order of the ciphertext blocks to alter the meaning of the

message. For example, if the plaintext includes instructions like 'pay £XXX

to account holder ABC, reference number YYY', then an attacker could replace

the encryption of XXX with some of the encryption of YYY. This leads to other

techniques for combining blocks, called modes, where, for example, the output

of the last block is fed into the input for the next one. So, the output is

not just a function of that plaintext block and key, but is a function of

that plaintext block, the key, and all preceding ciphertext blocks (see <xref href="GUID-CFF1BCCA-5D07-5B8A-9363-AD11EEEAB485.dita#GUID-CFF1BCCA-5D07-5B8A-9363-AD11EEEAB485/GUID-71CD8B41-219D-5D07-8C99-47D68668A880">Symmetric

Modes</xref>). </p> </li>

</ul> </li>

</ul> <p>Both stream ciphers and block ciphers are provided by the API with

a similar interface. Block ciphers usually need padding for non completed

blocks. The API allows the user to choose the padding to be added at the end

of the last encrypted block or to be checked and removed from the last decrypted

block. </p> </section>

<section id="GUID-A4E43A90-A66F-5868-BD94-DA709B75431B"><title>Types of symmetric

algorithms supported</title> <p>The following symmetric algorithms are supported: </p> <table id="GUID-25F43544-4556-544B-B010-76B0E091B80C">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Symmetric algorithm</entry>

<entry>Type</entry>

<entry>Specified in:</entry>

</row>

</thead>

<tbody>

<row>

<entry><p>AES (Advanced Encryption Standard) </p> </entry>

<entry><p>Block cipher </p> </entry>

<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf" scope="external">FIPS-197</xref> </p> </entry>

</row>

<row>

<entry><p>DES (Data Encryption Standard) </p> </entry>

<entry><p>Block cipher </p> </entry>

<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf" scope="external">FIPS 46-3</xref>  </p> </entry>

</row>

<row>

<entry><p>3DES (Triple Data Encryption Standard) </p> </entry>

<entry><p>Block cipher </p> </entry>

<entry><p> <xref href="http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf" scope="external">FIPS 46-3</xref>  </p> </entry>

</row>

<row>

<entry><p>RC2-128 </p> </entry>

<entry><p>Block cipher </p> </entry>

<entry><p> <xref href="ftp://ftp.rfc-editor.org/in-notes/rfc2268.txt" scope="external">RFC

2268</xref>  </p> </entry>

</row>

<row>

<entry><p>ARC4 ('alleged' RC4) </p> </entry>

<entry><p>Stream cipher </p> </entry>

<entry><p>the internet and a posting to sci.crypt in 1994. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-66E8AD5D-A9FF-51E3-897D-D5EC3D66903A"><title>Base classes

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

(TLS/IPSec). </p> <p> <xref href="GUID-F4E08165-A654-3D32-8FED-7ED54BDAD88B.dita"><apiname>CSymmetricCipher</apiname></xref> is the abstract

base class that allows a client to use the supported symmetric algorithms

listed above. It allows clients to encrypt and decrypt without having to know

anything about which encryption algorithm is currently in use. </p> <p>The

PKCS5 API (the <codeph>TPKCS5KDF</codeph> class, also see <xref href="GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E.dita">Password

Based Encryption</xref>) offers Key Derivation Support that allows the derivation

of deterministic arbitrary length byte streams from an input string. The output

byte stream is generated using multiple iterations of a SHA-1 message digest

(<codeph>CSHA1</codeph>) and is suitable for use as a cryptographic symmetric

key. </p> <p>The diagrams below show the main classes used in symmetric 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 colour 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><xref href="GUID-F4E08165-A654-3D32-8FED-7ED54BDAD88B.dita"><apiname>CSymmetricCipher</apiname></xref> and derived classes</b> </p> <fig id="GUID-B11D8EE9-F078-57B2-9453-3ABF1FC0AAA1">

<title>The inheritance diagram shows the <codeph>CSymmetricCipher</codeph> abstract

base class and its derived abstract classes <codeph>CBufferedTransformation</codeph> and <codeph>CStreamCipher</codeph> used

for block and stream ciphers respectively. Also shown are the following derived

classes: <codeph>CBufferedDecryptor</codeph>, <codeph>CBufferedEncryptor</codeph>, <codeph>CARC4</codeph>,

and <codeph>CNullCipher</codeph>.</title>

<image href="GUID-5F72210C-1636-584D-9D89-987D25136975_d0e363464_href.png" placement="inline"/>

</fig> <p><b><xref href="GUID-CFDA5321-EE13-3203-8DED-71E69D4469BD.dita"><apiname>CBlockTransformation</apiname></xref> and derived classes</b> </p> <fig id="GUID-EB7BFBBF-D41C-5A3A-AA53-3F5BDA019C2A">

<title>The inheritance diagram above shows the <xref href="GUID-CFDA5321-EE13-3203-8DED-71E69D4469BD.dita"><apiname>CBlockTransformation</apiname></xref> abstract

base class used for block ciphers. Also shown are the following derived classes: <xref href="GUID-436C3EBE-FC60-3760-A3BA-D8DF8FA5B8AF.dita"><apiname>CBlockChainingMode</apiname></xref>, <xref href="GUID-C65A1F55-A8D2-3393-8DC1-35656017E2B8.dita"><apiname>CModeCBCEncryptor</apiname></xref>, <xref href="GUID-7D5FBD2C-83A0-351A-96B3-C5C54FE525E6.dita"><apiname>CModeCBCDecryptor</apiname></xref>, <xref href="GUID-1C18ED2F-085F-3C3E-A93E-5FD37461E440.dita"><apiname>CDES</apiname></xref>, <xref href="GUID-E7401D77-AD0E-3B8F-A7CC-23ADA5151DB6.dita"><apiname>CDESEncryptor</apiname></xref>, <xref href="GUID-249270AC-907B-3E46-AFDB-131FDC6F612A.dita"><apiname>CDESDecryptor</apiname></xref>, <xref href="GUID-90A671B0-756E-3773-8429-6441D1594F4B.dita"><apiname>C3DES</apiname></xref>, <xref href="GUID-B931DBB9-4484-33FD-9E94-6F256ABD5C68.dita"><apiname>C3DESEncryptor</apiname></xref>, <xref href="GUID-C693C22D-04C5-3C9E-8605-0EA90F723AF3.dita"><apiname>C3DESDecryptor</apiname></xref>, <xref href="GUID-BEE18CDE-CFB6-3116-9FAE-046780D4D006.dita"><apiname>CRC2</apiname></xref>, <xref href="GUID-19F20C86-5722-3A35-B17D-3830D18CC7FC.dita"><apiname>CRC2Encryptor</apiname></xref>, <xref href="GUID-E6FD8DF9-258B-39BC-8C39-ABF7434A29B5.dita"><apiname>CRC2Decryptor</apiname></xref>, <xref href="GUID-B0AEE24A-91A6-335E-AD64-C9DDCC1F81A9.dita"><apiname>CRijndael</apiname></xref>, <xref href="GUID-AE1A9AC0-DB79-3C62-AA23-896812F25F14.dita"><apiname>CAESEncryptor</apiname></xref>, and <xref href="GUID-51666543-0256-3E0D-BF5F-8716753C5921.dita"><apiname>CAESDecryptor</apiname></xref>.</title>

<image href="GUID-7461BD6A-F50B-5E14-8995-CF3F2D8F5F14_d0e363544_href.png" placement="inline"/>

</fig> <p id="GUID-A8F9A25F-B83E-5FE7-840F-4DCF246D3D96"><b>CPadding and derived

classes</b> </p> <fig id="GUID-648F7604-A3C6-57EB-9B34-7F8079549D9C">

<title>Above is an inheritance diagram showing the CPadding abstract base

class used with block ciphers. Also shown are the following derived classes: <xref href="GUID-B7090C61-ECC7-3E8A-8D19-75C9170B0135.dita"><apiname>CPaddingPKCS7</apiname></xref>, <xref href="GUID-3150ECC9-CF8E-3890-91CD-87F5EBCE550E.dita"><apiname>CPaddingPKCS1Encryption</apiname></xref>, <xref href="GUID-F845CB30-7ABE-3EB6-B1B9-C72581897D0C.dita"><apiname>CRSAPKCS1v15Encryptor</apiname></xref>, <xref href="GUID-57C40DCA-8340-38B5-9777-2863C8F88B59.dita"><apiname>CPaddingNone</apiname></xref>, <xref href="GUID-723F64D1-01C5-3A03-B987-0FB862EE8EDE.dita"><apiname>CPaddingPKCS1Signature</apiname></xref>,

and <xref href="GUID-CC2347BE-3272-3DDF-8BDD-B44F5C0026B3.dita"><apiname>CPaddingSSLv3</apiname></xref></title>

<image href="GUID-0FD02CAD-B687-50C0-8E44-74ED9B4A936E_d0e363580_href.png" placement="inline"/>

</fig> </section>

</conbody></concept>