<?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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1" 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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-1-2-1"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-1-2-2"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-1-4-1"><p>TLS_PSK_WITH_RC4_128_SHA </p> </li>

<li id="GUID-D305CBF6-87F1-5895-AFE6-F8067340E489-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-1-4-2"><p>TLS_PSK_WITH_3DES_EDE_CBC_SHA </p> </li>

<li id="GUID-EA4EC83B-5B58-53D6-A1AD-D408CBBC25BA-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-1-4-3"><p>TLS_PSK_WITH_AES_128_CBC_SHA </p> </li>

<li id="GUID-4B4E0A69-8F73-5D41-AE50-A231F2E73A00-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-1-4-4"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2">

<step id="GUID-12A544C1-3A69-5EB5-A546-A03B95B27909-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-1"><cmd>Configure a PSK

key handler </cmd>

</step>

<step id="GUID-6D6DADE7-457D-5885-8448-AF515B58C381-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-2"><cmd/>

<info>Set available ciphersuites. There are two possibilities for offering

PSK ciphersuites: </info>

<substeps id="GUID-505F5F7A-60D5-55BC-9F46-8A0BDE0A8F2F-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-2-3">

<substep id="GUID-5B057120-5AC9-5EAA-929C-F01C9E5036AA-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-2-3-1"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-2-3-2"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-3"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-3-4">

<substep id="GUID-A0F4A26A-FA91-58DC-9EFF-6F131F473E63-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-3-4-1"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-3-4-2"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-2-3-4-3"><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-GENID-1-12-1-24-1-1-9-1-4-1-5-1-4-1-3-3-3" xml:space="preserve">

//Configure a PSK key handler

TPckgBuf<MSoPskKeyHandler *> pskConfigPkg;

pskConfigPkg() = ptrToKeyHandler;

User::LeaveIfError(secureSocket->SetOpt(KSoPskConfig, KSolInetSSL, pskConfigPkg));

//set available ciphersuites 

TBuf8<8> buf;    

for(TInt i=0; i<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->SetAvailableCipherSuites( buf );

//Start a connection

secureSocket->StartClientHandshake( iStatus );

</codeblock> </example>

</taskbody></task>