<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-5927A119-C520-572D-83AF-7265DEEF4553" xml:lang="en"><title>Using
Pre-Shared Keys with Transport Layer Security : Tutorial</title><shortdesc>This topic describes how to use Pre-Shared Keys (PSKs) with Transport
Layer Security (TLS). This tutorial is useful for licensees and third-party
developers. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<context><p>TLS_PSK is a standard for using PSKs with Transport Layer Security
(TLS). You can use TLS_PSK instead of certificate authentication. The benefits
of using TLS_PSK are as follows: </p> <ul>
<li id="GUID-F752EC0E-19B2-5C8E-9F0F-AC1131CC9437"><p>Easy to manage - For
example, PSK can derive from a "secret key" that vendors deploy in the SIM
card of each phone. </p> </li>
<li id="GUID-9964A601-5724-58D0-856C-B2401AD171D3"><p>It improves the connection
setup performance and battery life, as the key exchange algorithm takes less
time to run. </p> </li>
</ul> <p>Symbian maintains the following TLS_PSK ciphersuites: </p> <ul>
<li id="GUID-AF102861-2863-5189-AEA0-738797280D3A"><p>TLS_PSK_WITH_RC4_128_SHA </p> </li>
<li id="GUID-D305CBF6-87F1-5895-AFE6-F8067340E489"><p>TLS_PSK_WITH_3DES_EDE_CBC_SHA </p> </li>
<li id="GUID-EA4EC83B-5B58-53D6-A1AD-D408CBBC25BA"><p>TLS_PSK_WITH_AES_128_CBC_SHA </p> </li>
<li id="GUID-4B4E0A69-8F73-5D41-AE50-A231F2E73A00"><p>TLS_PSK_WITH_AES_256_CBC_SHA </p> </li>
</ul> <p>The ciphersuite is made up of a key exchange (for example PSK), a
cipher (for example RC4_128) and a hash (for example SHA). </p> <p>Note: TLS_PSK
operation is specified by <xref href="http://www.ietf.org/rfc/rfc4279.txt" scope="external">RFC4279</xref>. </p><p>For a client to make a secure connection
with a TLS_PSK server, it must provide a pre-shared key and an identity. To
provide a pre-shared key and an identity, do the following steps: 
</p> </context>
<steps id="GUID-460D5C5A-7C5D-552F-87B1-5E1ED199EEBD">
<step id="GUID-12A544C1-3A69-5EB5-A546-A03B95B27909"><cmd>Configure a PSK
key handler </cmd>
</step>
<step id="GUID-6D6DADE7-457D-5885-8448-AF515B58C381"><cmd/>
<info>Set available ciphersuites. There are two possibilities for offering
PSK ciphersuites: </info>
<substeps id="GUID-505F5F7A-60D5-55BC-9F46-8A0BDE0A8F2F">
<substep id="GUID-5B057120-5AC9-5EAA-929C-F01C9E5036AA"><cmd>Specify an explicit
ordered list of ciphersuites for the server to select from.</cmd>
<info>To do this call <xref href="GUID-6D5FEC74-C9EB-3A5B-96B0-65E92564F387.dita"><apiname>SetAvailableCipherSuites()</apiname></xref>. You can
do this only after configuring the PSK key handler. </info>
</substep>
<substep id="GUID-72D09EBC-0ACB-533D-B43D-CBDD7A173E95"><cmd>Use the default
list, which is automatically generated.</cmd>
<info>If you do not specify an explicit list, the stack automatically includes
the PSK ciphersuites in addition to any other ciphersuites supported. </info>
</substep>
</substeps>
<info>If you specify an explicit list by calling <xref href="GUID-6D5FEC74-C9EB-3A5B-96B0-65E92564F387.dita"><apiname>SetAvailableCipherSuites()</apiname></xref>,
and you later deconfigure the PSK key handler, you must remove the PSK ciphersuites
from the list by calling <xref href="GUID-6D5FEC74-C9EB-3A5B-96B0-65E92564F387.dita"><apiname>SetAvailableCipherSuites()</apiname></xref> again. </info>
</step>
<step id="GUID-CD1A725D-55EA-5F89-9552-C4DC629E9365"><cmd/>
<info>Start a connection. </info>
<info>The server chooses a ciphersuite from those offered by the client. If
the server chooses a PSK ciphersuite, the following sequence of events occurs: </info>

<substeps id="GUID-8BA50D23-A34D-5E02-BA1C-33B9C503E83C">
<substep id="GUID-A0F4A26A-FA91-58DC-9EFF-6F131F473E63"><cmd>The server can
optionally send a “PSK identity hint” to the client.</cmd>
<info> This PSK identity hint might influence the choice of key and identity
the client makes. If the server sends one, it is passed to the key handler.
If it does not send one, NULL is passed to the key handler. </info>
<info>Note: The PSK identity hint is optional and its meaning is not defined
(format must be UTF8). Applications using TLS-PSK may left out it or use it
for any action (for example SUPL uses it to indicate the SUPL protocol version
and to present a list of allowed PSK generators). </info>
</substep>
<substep id="GUID-30DD1846-5C91-577A-9D1F-EE535A9B4DC2"><cmd>The TLS stack
on the client calls <xref href="GUID-1A7C31AC-B493-394E-BB9C-CB6F0DBAE6CF.dita"><apiname>ptrToKeyHandler-&gt;getPskL()</apiname></xref></cmd>
<info>The TLS stack on the client calls getPskL() for the instance of the
key handler (in this case ptrToKeyHandler). See <xref href="GUID-9580646B-FDFA-3515-B3CF-39B16880CF6F.dita#GUID-9580646B-FDFA-3515-B3CF-39B16880CF6F/GUID-0EC110F3-D2A6-3FD4-8E59-9E6F5741A61C"><apiname>MSoPskKeyHandler::
GetPskL()</apiname></xref> for the prototype. This call returns the PSK identity
and value to be used to secure the connection. </info>
</substep>
<substep id="GUID-F52F987A-E500-5579-A5D4-E26F27F7390A"><cmd>The TLS stack
sends the PSK identity to the server.</cmd>
<info>The TLS stack sends the PSK identity (chosen in Step 2) to the server
so it can retrieve the matching PSK value to secure the connection. </info>
</substep>
</substeps>
<info>After the client has chosen which PSK to use, it sends an identity to
the server and the server can use this to obtain a matching PSK. Again the
meaning of the identity field is not specified, but its format must be UTF8.
An application may choose to use it or leave it empty. </info>
<info>Note: In the example, the server must select a PSK ciphersuite, because
the client provides only PSK ciphersuites. The connection fails, if the server
selects a PSK ciphersuite and fails to get a key that matches with the client.
The TLS assumes that the first common ciphersuite cannot fail and does not
implement connection retry. </info>
</step>
</steps>
<example><title>TLS_PSK example</title> <p>The following example code shows
how to configure TLS_PSK: </p> <codeblock id="GUID-61425E22-BD86-5913-BB16-55D933556969" xml:space="preserve">


//Configure a PSK key handler

TPckgBuf&lt;MSoPskKeyHandler *&gt; pskConfigPkg;
pskConfigPkg() = ptrToKeyHandler;
User::LeaveIfError(secureSocket-&gt;SetOpt(KSoPskConfig, KSolInetSSL, pskConfigPkg));

//set available ciphersuites 

TBuf8&lt;8&gt; buf;    
for(TInt i=0; i&lt;4; ++i)
{
 // The supported PSK ciphersuites are as follows:-
 // TLS_PSK_WITH_RC4_128_SHA          = { 0x00, 0x8A };
 // TLS_PSK_WITH_3DES_EDE_CBC_SHA     = { 0x00, 0x8B };
 // TLS_PSK_WITH_AES_128_CBC_SHA      = { 0x00, 0x8C };
 // TLS_PSK_WITH_AES_256_CBC_SHA      = { 0x00, 0x8D };
 buf[i*2]=0;
 buf[i*2+1]=0x8a+i;
}
secureSocket-&gt;SetAvailableCipherSuites( buf );

//Start a connection

secureSocket-&gt;StartClientHandshake( iStatus );

</codeblock> </example>
</taskbody></task>