--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-5927A119-C520-572D-83AF-7265DEEF4553.dita	Tue Jul 20 12:00:49 2010 +0100
@@ -0,0 +1,129 @@
+<?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>
\ No newline at end of file