1 /** |
|
2 |
|
3 @page cryptotokens_TSecdlg tsecdlg - The dummy security dialog notifier |
|
4 |
|
5 @section tsecdlg_intro Introduction |
|
6 |
|
7 This document describes tsecdlg, the dummy security dialog notifier. |
|
8 |
|
9 The security dialog API provides a way for components to ask the user various |
|
10 standard security-related questions. For example, it contains methods to prompt |
|
11 the user to enter a passphrase, among others. The API is defined in the file |
|
12 secdlg.h. |
|
13 |
|
14 It is necessary to write test harnesses for clients of this API which can be run |
|
15 unattended, without user intervention. To achieve this, tsecdlg was developed. |
|
16 It allows user responses to security dialogs to be pre-defined, and enables a |
|
17 test harness to check that the expected dialogs would have been displayed to the |
|
18 user. |
|
19 |
|
20 @section tsecdlg_secdlg_implementation Security dialog implementation |
|
21 |
|
22 The dialogs that the user sees cannot be implemented as part of the security |
|
23 subsystem because they form part of the user interface layer. So the security |
|
24 dialog API passes client requests to the security dialog notifier. This is a |
|
25 type of plugin, and is typically supplied by the UI implementation - for example |
|
26 by techview. The protocol used to pass messages to and from the plugin is |
|
27 defined in the file secDlgImplDefs.h. |
|
28 |
|
29 tsecdlg is just an implementation of the security dialog notifier that doesn't |
|
30 ask the user for information. Instead it either gives default responses or |
|
31 reads them from a file. |
|
32 |
|
33 @section tsecdlg_when_to_use_tsecdlg When it's necessary to use tsecdlg |
|
34 |
|
35 Any test that directly or indirectly uses the security dialog API will require |
|
36 the use of tsecdlg if the tests are to be run unattended. At the moment, the |
|
37 keystore is the main client of this API. The keystore tests rely heavily on |
|
38 tsecdlg, and anything that uses keystore will probably need to use it as well - |
|
39 for example TLS. |
|
40 |
|
41 <hr> |
|
42 |
|
43 @section tsecdlg_preparation Preparation for running tests that use tsecdlg |
|
44 |
|
45 @section tsecdlg_building_tsecdlg Building tsecdlg |
|
46 |
|
47 Two versions of tsecdlg are built on all platforms - one for the extended |
|
48 notifier framework (ie graphical notifiers, or techview) and one for textshell. |
|
49 This means that tests will work in both environments. |
|
50 |
|
51 To build tsecdlg just requires building the test code supplied in the |
|
52 security cryptotokens component, eg: |
|
53 |
|
54 \code |
|
55 cd common\generic\security\cryptotokens\group |
|
56 bldmake bldfiles |
|
57 abld test build wins udeb |
|
58 \endcode |
|
59 |
|
60 There are two tsecdlg components: |
|
61 |
|
62 <table> |
|
63 <tr><th>Name</th><th>Location</th><th>Description</th></tr> |
|
64 <tr><td>t_secdlg</td><td>z:\\system\\notifiers\\tsecdlg.dll</td><td>Extended notifier</td></tr> |
|
65 <tr><td>t_secdlg_text</td><td>z:\\system\\tnotifiers\\tsecdlg_text.dll</td><td>Textshell notifier</td></tr> |
|
66 </table> |
|
67 |
|
68 @section tsecdlg_emulator_testing Testing on the emulator |
|
69 |
|
70 If you are running in techview mode, you must ensure that the techview |
|
71 implementation of the security dialog notifier (secdlg.dll) is not present (if |
|
72 both secldg.dll and tsecdlg.dll are present, epoc will crash). This can be |
|
73 found in in z:\\system\\notifiers, for example |
|
74 \\epoc32\\release\\wins\\udeb\\z\\system\\notifiers for wins udeb. The easiest |
|
75 way to ensure secdlg.dll is removed is to use the following command: |
|
76 |
|
77 \code |
|
78 del /s /f /q \epoc32\secdlg.dll |
|
79 \endcode |
|
80 |
|
81 This does not matter for textshell mode, because there is no default textshell |
|
82 security dialog plugin. |
|
83 |
|
84 @section tsecdlg_hardware_testing Testing on hardware |
|
85 |
|
86 To test on hardware, the appropriate dll (either techview or textshell) must be |
|
87 included in the ROM in the same location as it is in the emulator (ie |
|
88 z:\\system\\notifiers for techview mode). This can be done adding the following |
|
89 line to an iby file: |
|
90 |
|
91 \code |
|
92 file=ABI_DIR\BUILD_DIR\tsecdlg.dll System\Notifiers\tsecdlg.dll |
|
93 \endcode |
|
94 |
|
95 This is done for security tests in the file filetokenstests.iby. |
|
96 |
|
97 Note that if you are using techview mode, you must ensure that secdlg.dll is not |
|
98 included - you must edit \\epoc32\\rom\\include\\secui.iby and comment out the |
|
99 following line: |
|
100 |
|
101 \code |
|
102 file=ABI_DIR\BUILD_DIR\secdlg.dll System\Notifiers\Secdlg.dll |
|
103 \endcode |
|
104 |
|
105 <hr> |
|
106 |
|
107 @section tsecdlg_cryptotokens_operation tsecdlg operation |
|
108 |
|
109 tsecdlg has two modes of operation: |
|
110 |
|
111 @li Default mode |
|
112 @li Scripted mode |
|
113 |
|
114 @section tsecdlg_default_mode Default mode |
|
115 |
|
116 This is the simpler mode. Whenever the dialog for a passphrase is triggered, |
|
117 tsecdlg replies with a default passphrase ('pinkcloud'). |
|
118 |
|
119 This is intended to used by test code that is not directly testing a client of |
|
120 the security dialog API, for example by TLS. |
|
121 |
|
122 tsecdlg runs in this mode when the files c:\\t_secdlg_in.dat and |
|
123 c:\\t_secdlg_out.dat are not present. |
|
124 |
|
125 @section tsecdlg_scripted_mode Scripted mode |
|
126 |
|
127 This mode is more complex, and is intended to be used by for testing direct |
|
128 clients of the security dialog API - for example the keystore. |
|
129 |
|
130 Before a test is run, a file of expected dialogs and the required responses is |
|
131 prepared. Every time the security dialog API is called and tsecdlg invoked, it |
|
132 checks that the requested dialog is the one expected, and answers with the |
|
133 pre-determined response. An unexpected dialog request produces an error. A |
|
134 file containing the number of correctly answered dialog requests is maintained |
|
135 and this allows the test harness to determine whether all expected dialogs were |
|
136 triggered correctly. |
|
137 |
|
138 The list of expected dialogs is read from c:\\t_secdlg_in.dat. This has the |
|
139 following format: |
|
140 |
|
141 <table> |
|
142 <tr><th>Type</th><th>Description</th></th> |
|
143 <tr><td>TInt32</td><td>Number of dialogs expected</td></tr> |
|
144 </table> |
|
145 |
|
146 Then, for every expected dialog, the following data is present. Strings are |
|
147 represented with their size (TInt32) followed by that many bytes of data. |
|
148 |
|
149 <table> |
|
150 <tr><th>Type</th><th>Description</th></tr> |
|
151 <tr><td>TInt32</td><td>Expected operation</td></tr> |
|
152 <tr><td>String</td><td>Expected label</td></tr> |
|
153 <tr><td>String</td><td>Response 1</td></tr> |
|
154 <tr><td>String</td><td>Response 2 (not always used)</td></tr> |
|
155 </table> |
|
156 |
|
157 The expected operation should be a member of the TSecurityDialogOperation |
|
158 enumeration - this specifies the expected type of dialog that is requested (for |
|
159 example, the enter passphrase dialog). If the requested operation is not the |
|
160 same as this, the operation is completed with KErrOperationMismatch. If the |
|
161 operation is one that is not supported by tsecdlg (only the ones necessary for |
|
162 testing keystore are currently implemented), the operation is completed with |
|
163 KErrOperationNotSupported. |
|
164 |
|
165 The expected label allows the test code to specify the label passed to the API. |
|
166 It is matched if the actual label contains the expected label - this means that |
|
167 passing an empty string will always ensure a match. If the expected label is |
|
168 not matched, the operation is completed with KErrLabelMismatch. |
|
169 |
|
170 The responses are the information tsecdlg passes back as if from the user. Some |
|
171 operations (eg change PIN) return two pieces of information, but for the most |
|
172 part only the first one is used. |
|
173 |
|
174 The error codes are summarised below. Note that as this is test code, these are |
|
175 not officially allocated! |
|
176 |
|
177 <table> |
|
178 <tr><th>Name</th><th>Code</th><th>Description</th></tr> |
|
179 <tr><td>KErrTooManyDialogs</td><td>-12000</td><td>More dialogs have been requested than are described in the input file</td></tr> |
|
180 <tr><td>KErrLabelMismatch</td><td>-12001</td><td>The label requested did not match the expected value</td></tr> |
|
181 <tr><td>KErrOperationMismatch</td><td>-12002</td><td>The operation requested did not match the expected value</td></tr> |
|
182 <tr><td>KErrOperationNotSupported</td><td>-12003</td><td>The operation requested is not implemented by tsecdlg</td></tr> |
|
183 </table> |
|
184 |
|
185 Every time a request is succesfully answered, the file c:\\t_secdlg_out.dat is |
|
186 updated - it contains a single TInt32 that indicates the index of the current |
|
187 dialog in the list of expected dialogs described by c:\\t_secdlg_in.dat. If it |
|
188 is not present, its value is assumed to be zero. |
|
189 |
|
190 */ |
|