/**+
−
+
−
@page cryptotokens_TSecdlg tsecdlg - The dummy security dialog notifier+
−
+
−
@section tsecdlg_intro Introduction+
−
+
−
This document describes tsecdlg, the dummy security dialog notifier.+
−
+
−
The security dialog API provides a way for components to ask the user various+
−
standard security-related questions.  For example, it contains methods to prompt+
−
the user to enter a passphrase, among others.  The API is defined in the file+
−
secdlg.h.+
−
+
−
It is necessary to write test harnesses for clients of this API which can be run+
−
unattended, without user intervention.  To achieve this, tsecdlg was developed.+
−
It allows user responses to security dialogs to be pre-defined, and enables a+
−
test harness to check that the expected dialogs would have been displayed to the+
−
user.+
−
+
−
@section tsecdlg_secdlg_implementation Security dialog implementation+
−
+
−
The dialogs that the user sees cannot be implemented as part of the security+
−
subsystem because they form part of the user interface layer.  So the security+
−
dialog API passes client requests to the security dialog notifier.  This is a+
−
type of plugin, and is typically supplied by the UI implementation - for example+
−
by techview.  The protocol used to pass messages to and from the plugin is+
−
defined in the file secDlgImplDefs.h.+
−
+
−
tsecdlg is just an implementation of the security dialog notifier that doesn't+
−
ask the user for information.  Instead it either gives default responses or+
−
reads them from a file.+
−
+
−
@section tsecdlg_when_to_use_tsecdlg When it's necessary to use tsecdlg+
−
+
−
Any test that directly or indirectly uses the security dialog API will require+
−
the use of tsecdlg if the tests are to be run unattended.  At the moment, the+
−
keystore is the main client of this API.  The keystore tests rely heavily on+
−
tsecdlg, and anything that uses keystore will probably need to use it as well -+
−
for example TLS.+
−
+
−
<hr>+
−
+
−
@section tsecdlg_preparation Preparation for running tests that use tsecdlg+
−
+
−
@section tsecdlg_building_tsecdlg Building tsecdlg+
−
+
−
Two versions of tsecdlg are built on all platforms - one for the extended+
−
notifier framework (ie graphical notifiers, or techview) and one for textshell.+
−
This means that tests will work in both environments.+
−
+
−
To build tsecdlg just requires building the test code supplied in the+
−
security cryptotokens component, eg:+
−
+
−
\code+
−
cd common\generic\security\cryptotokens\group+
−
bldmake bldfiles+
−
abld test build wins udeb+
−
\endcode+
−
+
−
There are two tsecdlg components: +
−
+
−
<table>+
−
<tr><th>Name</th><th>Location</th><th>Description</th></tr>+
−
<tr><td>t_secdlg</td><td>z:\\system\\notifiers\\tsecdlg.dll</td><td>Extended notifier</td></tr>+
−
<tr><td>t_secdlg_text</td><td>z:\\system\\tnotifiers\\tsecdlg_text.dll</td><td>Textshell notifier</td></tr>+
−
</table>+
−
+
−
@section tsecdlg_emulator_testing Testing on the emulator +
−
+
−
If you are running in techview mode, you must ensure that the techview+
−
implementation of the security dialog notifier (secdlg.dll) is not present (if+
−
both secldg.dll and tsecdlg.dll are present, epoc will crash).  This can be+
−
found in in z:\\system\\notifiers, for example+
−
\\epoc32\\release\\wins\\udeb\\z\\system\\notifiers for wins udeb.  The easiest+
−
way to ensure secdlg.dll is removed is to use the following command:+
−
+
−
\code+
−
del /s /f /q \epoc32\secdlg.dll+
−
\endcode+
−
+
−
This does not matter for textshell mode, because there is no default textshell+
−
security dialog plugin.+
−
+
−
@section tsecdlg_hardware_testing Testing on hardware+
−
+
−
To test on hardware, the appropriate dll (either techview or textshell) must be+
−
included in the ROM in the same location as it is in the emulator (ie+
−
z:\\system\\notifiers for techview mode).  This can be done adding the following+
−
line to an iby file:+
−
+
−
\code+
−
file=ABI_DIR\BUILD_DIR\tsecdlg.dll		System\Notifiers\tsecdlg.dll+
−
\endcode+
−
+
−
This is done for security tests in the file filetokenstests.iby.+
−
+
−
Note that if you are using techview mode, you must ensure that secdlg.dll is not+
−
included - you must edit \\epoc32\\rom\\include\\secui.iby and comment out the+
−
following line:+
−
+
−
\code+
−
file=ABI_DIR\BUILD_DIR\secdlg.dll		System\Notifiers\Secdlg.dll+
−
\endcode+
−
+
−
<hr>+
−
+
−
@section tsecdlg_cryptotokens_operation tsecdlg operation+
−
+
−
tsecdlg has two modes of operation:+
−
+
−
@li Default mode+
−
@li Scripted mode+
−
+
−
@section tsecdlg_default_mode Default mode+
−
+
−
This is the simpler mode.  Whenever the dialog for a passphrase is triggered,+
−
tsecdlg replies with a default passphrase ('pinkcloud').+
−
+
−
This is intended to used by test code that is not directly testing a client of+
−
the security dialog API, for example by TLS.+
−
+
−
tsecdlg runs in this mode when the files c:\\t_secdlg_in.dat and+
−
c:\\t_secdlg_out.dat are not present.+
−
+
−
@section tsecdlg_scripted_mode Scripted mode+
−
+
−
This mode is more complex, and is intended to be used by for testing direct+
−
clients of the security dialog API - for example the keystore.+
−
+
−
Before a test is run, a file of expected dialogs and the required responses is+
−
prepared.  Every time the security dialog API is called and tsecdlg invoked, it+
−
checks that the requested dialog is the one expected, and answers with the+
−
pre-determined response.  An unexpected dialog request produces an error.  A+
−
file containing the number of correctly answered dialog requests is maintained+
−
and this allows the test harness to determine whether all expected dialogs were+
−
triggered correctly.+
−
+
−
The list of expected dialogs is read from c:\\t_secdlg_in.dat.  This has the+
−
following format:+
−
+
−
<table>+
−
<tr><th>Type</th><th>Description</th></th>+
−
<tr><td>TInt32</td><td>Number of dialogs expected</td></tr>+
−
</table>+
−
+
−
Then, for every expected dialog, the following data is present.  Strings are+
−
represented with their size (TInt32) followed by that many bytes of data.+
−
+
−
<table>+
−
<tr><th>Type</th><th>Description</th></tr>+
−
<tr><td>TInt32</td><td>Expected operation</td></tr>+
−
<tr><td>String</td><td>Expected label</td></tr>+
−
<tr><td>String</td><td>Response 1</td></tr>+
−
<tr><td>String</td><td>Response 2 (not always used)</td></tr>+
−
</table>+
−
+
−
The expected operation should be a member of the TSecurityDialogOperation+
−
enumeration - this specifies the expected type of dialog that is requested (for+
−
example, the enter passphrase dialog).  If the requested operation is not the+
−
same as this, the operation is completed with KErrOperationMismatch.  If the+
−
operation is one that is not supported by tsecdlg (only the ones necessary for+
−
testing keystore are currently implemented), the operation is completed with+
−
KErrOperationNotSupported.+
−
+
−
The expected label allows the test code to specify the label passed to the API.+
−
It is matched if the actual label contains the expected label - this means that+
−
passing an empty string will always ensure a match.  If the expected label is+
−
not matched, the operation is completed with KErrLabelMismatch.+
−
+
−
The responses are the information tsecdlg passes back as if from the user.  Some+
−
operations (eg change PIN) return two pieces of information, but for the most+
−
part only the first one is used.  +
−
+
−
The error codes are summarised below.  Note that as this is test code, these are+
−
not officially allocated!+
−
+
−
<table>+
−
<tr><th>Name</th><th>Code</th><th>Description</th></tr>+
−
<tr><td>KErrTooManyDialogs</td><td>-12000</td><td>More dialogs have been requested than are described in the input file</td></tr>+
−
<tr><td>KErrLabelMismatch</td><td>-12001</td><td>The label requested did not match the expected value</td></tr>+
−
<tr><td>KErrOperationMismatch</td><td>-12002</td><td>The operation requested did not match the expected value</td></tr>+
−
<tr><td>KErrOperationNotSupported</td><td>-12003</td><td>The operation requested is not implemented by tsecdlg</td></tr>+
−
</table>+
−
+
−
Every time a request is succesfully answered, the file c:\\t_secdlg_out.dat is+
−
updated - it contains a single TInt32 that indicates the index of the current+
−
dialog in the list of expected dialogs described by c:\\t_secdlg_in.dat.  If it+
−
is not present, its value is assumed to be zero.+
−
+
−
*/+
−