|
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 task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-5927A119-C520-572D-83AF-7265DEEF4553" xml:lang="en"><title>Using |
|
13 Pre-Shared Keys with Transport Layer Security : Tutorial</title><shortdesc>This topic describes how to use Pre-Shared Keys (PSKs) with Transport |
|
14 Layer Security (TLS). This tutorial is useful for licensees and third-party |
|
15 developers. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
16 <context><p>TLS_PSK is a standard for using PSKs with Transport Layer Security |
|
17 (TLS). You can use TLS_PSK instead of certificate authentication. The benefits |
|
18 of using TLS_PSK are as follows: </p> <ul> |
|
19 <li id="GUID-F752EC0E-19B2-5C8E-9F0F-AC1131CC9437"><p>Easy to manage - For |
|
20 example, PSK can derive from a "secret key" that vendors deploy in the SIM |
|
21 card of each phone. </p> </li> |
|
22 <li id="GUID-9964A601-5724-58D0-856C-B2401AD171D3"><p>It improves the connection |
|
23 setup performance and battery life, as the key exchange algorithm takes less |
|
24 time to run. </p> </li> |
|
25 </ul> <p>Symbian maintains the following TLS_PSK ciphersuites: </p> <ul> |
|
26 <li id="GUID-AF102861-2863-5189-AEA0-738797280D3A"><p>TLS_PSK_WITH_RC4_128_SHA </p> </li> |
|
27 <li id="GUID-D305CBF6-87F1-5895-AFE6-F8067340E489"><p>TLS_PSK_WITH_3DES_EDE_CBC_SHA </p> </li> |
|
28 <li id="GUID-EA4EC83B-5B58-53D6-A1AD-D408CBBC25BA"><p>TLS_PSK_WITH_AES_128_CBC_SHA </p> </li> |
|
29 <li id="GUID-4B4E0A69-8F73-5D41-AE50-A231F2E73A00"><p>TLS_PSK_WITH_AES_256_CBC_SHA </p> </li> |
|
30 </ul> <p>The ciphersuite is made up of a key exchange (for example PSK), a |
|
31 cipher (for example RC4_128) and a hash (for example SHA). </p> <p>Note: TLS_PSK |
|
32 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 |
|
33 with a TLS_PSK server, it must provide a pre-shared key and an identity. To |
|
34 provide a pre-shared key and an identity, do the following steps: |
|
35 </p> </context> |
|
36 <steps id="GUID-460D5C5A-7C5D-552F-87B1-5E1ED199EEBD"> |
|
37 <step id="GUID-12A544C1-3A69-5EB5-A546-A03B95B27909"><cmd>Configure a PSK |
|
38 key handler </cmd> |
|
39 </step> |
|
40 <step id="GUID-6D6DADE7-457D-5885-8448-AF515B58C381"><cmd/> |
|
41 <info>Set available ciphersuites. There are two possibilities for offering |
|
42 PSK ciphersuites: </info> |
|
43 <substeps id="GUID-505F5F7A-60D5-55BC-9F46-8A0BDE0A8F2F"> |
|
44 <substep id="GUID-5B057120-5AC9-5EAA-929C-F01C9E5036AA"><cmd>Specify an explicit |
|
45 ordered list of ciphersuites for the server to select from.</cmd> |
|
46 <info>To do this call <xref href="GUID-6D5FEC74-C9EB-3A5B-96B0-65E92564F387.dita"><apiname>SetAvailableCipherSuites()</apiname></xref>. You can |
|
47 do this only after configuring the PSK key handler. </info> |
|
48 </substep> |
|
49 <substep id="GUID-72D09EBC-0ACB-533D-B43D-CBDD7A173E95"><cmd>Use the default |
|
50 list, which is automatically generated.</cmd> |
|
51 <info>If you do not specify an explicit list, the stack automatically includes |
|
52 the PSK ciphersuites in addition to any other ciphersuites supported. </info> |
|
53 </substep> |
|
54 </substeps> |
|
55 <info>If you specify an explicit list by calling <xref href="GUID-6D5FEC74-C9EB-3A5B-96B0-65E92564F387.dita"><apiname>SetAvailableCipherSuites()</apiname></xref>, |
|
56 and you later deconfigure the PSK key handler, you must remove the PSK ciphersuites |
|
57 from the list by calling <xref href="GUID-6D5FEC74-C9EB-3A5B-96B0-65E92564F387.dita"><apiname>SetAvailableCipherSuites()</apiname></xref> again. </info> |
|
58 </step> |
|
59 <step id="GUID-CD1A725D-55EA-5F89-9552-C4DC629E9365"><cmd/> |
|
60 <info>Start a connection. </info> |
|
61 <info>The server chooses a ciphersuite from those offered by the client. If |
|
62 the server chooses a PSK ciphersuite, the following sequence of events occurs: </info> |
|
63 |
|
64 <substeps id="GUID-8BA50D23-A34D-5E02-BA1C-33B9C503E83C"> |
|
65 <substep id="GUID-A0F4A26A-FA91-58DC-9EFF-6F131F473E63"><cmd>The server can |
|
66 optionally send a “PSK identity hint” to the client.</cmd> |
|
67 <info> This PSK identity hint might influence the choice of key and identity |
|
68 the client makes. If the server sends one, it is passed to the key handler. |
|
69 If it does not send one, NULL is passed to the key handler. </info> |
|
70 <info>Note: The PSK identity hint is optional and its meaning is not defined |
|
71 (format must be UTF8). Applications using TLS-PSK may left out it or use it |
|
72 for any action (for example SUPL uses it to indicate the SUPL protocol version |
|
73 and to present a list of allowed PSK generators). </info> |
|
74 </substep> |
|
75 <substep id="GUID-30DD1846-5C91-577A-9D1F-EE535A9B4DC2"><cmd>The TLS stack |
|
76 on the client calls <xref href="GUID-1A7C31AC-B493-394E-BB9C-CB6F0DBAE6CF.dita"><apiname>ptrToKeyHandler->getPskL()</apiname></xref></cmd> |
|
77 <info>The TLS stack on the client calls getPskL() for the instance of the |
|
78 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:: |
|
79 GetPskL()</apiname></xref> for the prototype. This call returns the PSK identity |
|
80 and value to be used to secure the connection. </info> |
|
81 </substep> |
|
82 <substep id="GUID-F52F987A-E500-5579-A5D4-E26F27F7390A"><cmd>The TLS stack |
|
83 sends the PSK identity to the server.</cmd> |
|
84 <info>The TLS stack sends the PSK identity (chosen in Step 2) to the server |
|
85 so it can retrieve the matching PSK value to secure the connection. </info> |
|
86 </substep> |
|
87 </substeps> |
|
88 <info>After the client has chosen which PSK to use, it sends an identity to |
|
89 the server and the server can use this to obtain a matching PSK. Again the |
|
90 meaning of the identity field is not specified, but its format must be UTF8. |
|
91 An application may choose to use it or leave it empty. </info> |
|
92 <info>Note: In the example, the server must select a PSK ciphersuite, because |
|
93 the client provides only PSK ciphersuites. The connection fails, if the server |
|
94 selects a PSK ciphersuite and fails to get a key that matches with the client. |
|
95 The TLS assumes that the first common ciphersuite cannot fail and does not |
|
96 implement connection retry. </info> |
|
97 </step> |
|
98 </steps> |
|
99 <example><title>TLS_PSK example</title> <p>The following example code shows |
|
100 how to configure TLS_PSK: </p> <codeblock id="GUID-61425E22-BD86-5913-BB16-55D933556969" xml:space="preserve"> |
|
101 |
|
102 |
|
103 //Configure a PSK key handler |
|
104 |
|
105 TPckgBuf<MSoPskKeyHandler *> pskConfigPkg; |
|
106 pskConfigPkg() = ptrToKeyHandler; |
|
107 User::LeaveIfError(secureSocket->SetOpt(KSoPskConfig, KSolInetSSL, pskConfigPkg)); |
|
108 |
|
109 //set available ciphersuites |
|
110 |
|
111 TBuf8<8> buf; |
|
112 for(TInt i=0; i<4; ++i) |
|
113 { |
|
114 // The supported PSK ciphersuites are as follows:- |
|
115 // TLS_PSK_WITH_RC4_128_SHA = { 0x00, 0x8A }; |
|
116 // TLS_PSK_WITH_3DES_EDE_CBC_SHA = { 0x00, 0x8B }; |
|
117 // TLS_PSK_WITH_AES_128_CBC_SHA = { 0x00, 0x8C }; |
|
118 // TLS_PSK_WITH_AES_256_CBC_SHA = { 0x00, 0x8D }; |
|
119 buf[i*2]=0; |
|
120 buf[i*2+1]=0x8a+i; |
|
121 } |
|
122 secureSocket->SetAvailableCipherSuites( buf ); |
|
123 |
|
124 //Start a connection |
|
125 |
|
126 secureSocket->StartClientHandshake( iStatus ); |
|
127 |
|
128 </codeblock> </example> |
|
129 </taskbody></task> |