/**

@page SWICertStore The SWI Cert Store

@section sec1 Introduction

This document descibes the software install certificate store, or SWI cert
store.

Software install requires access to root certificates in order to validate
signed install packages (SIS files).  However for security reasons the softare
install server is not allowed to dynamically load plugins (it is part of the
trusted computing base).  This means that it cannot use the unified cert store,
as would be the case for normal applications.  Instead it uses a dedicated
certificate store which it links to directly - the SWI cert store.

The SWI cert store is a read-only cert store, implemented using a data file that
is built into the ROM on a device.  This data file must be created before ROM
build time, and it must contain the root certificates necessary to valdiate all
SIS files that will be installed on the device.

In addtion to the usual cert store operations, the SWI certstore contains
additional meta-data that is relevant only to software install.  For each
certificate it contains a set of capabilities which that certificate is
authorised to sign for, and a mandatory flag.  If the mandatory flag is set for
a certificate, it indicates that every SIS file installed must be signed by a
cerificate issued under that certificate.

@section sec2 Creating the SWI cert store data file

The data file for the SWI cert store is built using the "swicertstoretool"
program.  This is an epoc binary that runs in the emulator, built as part of the
security tests.

The format of the command is:

@code
swicertstoretool INPUT_FILE OUTPUT_FILE LOG_FILE
@endcode

The paramters have the following meanings:

 - @c INPUT_FILE - An "ini" format file describing the certificates and
	               meta-data that will be used to populate the store
 - @c OUTPUT_FILE - The path the data file will be written to
 - @c LOG_FILE - The path the results of the process will be written to

@subsection sec21 Input file format

The input file is a text file in "ini" format, made up of one or more sections,
each of which contains attributes related to that section.  A section is
introduced with a line containing the section name in square brackets.
Attributes are specified by @c name=value pairs.

Each section describes a certificate to be put in the store, with the section
name used as the certificate label.

The following attributes can be specified for each certificate:

<table>

<tr>
  <th>Attribute:</th>
  <th>Desciption:</th>
</tr>

<tr>
  <td>file</td>
  <td>
    The name of the file containing the DER encoded certificate. This attribute
    must be present.
  </td>
</tr>

<tr>
  <td>mandatory</td>
  <td>
    Whether the certificate is marked as mandatory for software install. The
	value must be either "1" (mandatory) or "0" (not mandatory).  The attribute is
	optional - if it is not present the default is "0".
  </td>
</tr>

<tr>
  <td>capability</td>
  <td>
	The name of a capability that the certificate can sign for. This attribute can be
	repeated to allow multiple capabilities to be specified.  Allowed capabilities
	are:

	 - TCB
	 - CommDD
	 - PowerMgmt
	 - MultimediaDD
	 - ReadDeviceData
	 - WriteDeviceData
	 - DRM
	 - TrustedUI
	 - ProtServ
	 - DiskAdmin
	 - NetworkControl
	 - AllFiles
	 - SwEvent
	 - NetworkServices
	 - LocalServices
	 - ReadUserData
	 - WriteUserData
	 - Location
  </td>
</tr>

<tr>
  <td>application</td>
  <td>
	The name of an application that the certificate can be used for. This can be
	repeated, but it must appear at least once.  Allowed applications are:

	 - SWInstall		(Software install)
	 - SWInstallOCSP	(Software install OCSP signing)
  </td>
</tr>

</table>

Unrecognised attributes are ingnored.

@subsubsection sec211 Example input file

Below is an example of an input file used for testing software install:

@code
# exmplateInputFile.txt
#
# An example input file for the swi cert store tool

[Root5CA]
file = c:\system\TOCSP\Certs\newopenssl\Root5-RSA.der
mandatory = 1
capability = ReadDeviceData
capability = WriteDeviceData
capability = DRM
capability = AllFiles
application = SWInstall

[SymbianTestDSACA]
file = c:\tappinst\certs\Symbian-Test-DSA.der
capability = NetworkServices
capability = LocalServices
capability = Location
application = SWInstall
application = SWInstallOCSP

[SymbianTestRSACA]
file = c:\tappinst\certs\Symbian-Test-RSA.der
capability = ReadUserData
capability = WriteUserData
application = SWInstall
application = SWInstallOCSP
@endcode

@subsubsection sec212 Log file

The log file should be examined each time the tool is run, as this is the only
way in which errors are reported.  The log file describes the stages of
processing and will end either with an error message or the line "Done" if the
data file has been created successfully.

@section sec213 Installing the data file

The SWI cert store looks for the data file produced by the tool at @c
z:\\resource\\swicertstore.dat.  So for the emulator, this should be copied to
@c \\epoc32\\RELEASE\\winscw\\UDEB\\Z\\Resource\\swicertstore.dat, and for
hardware it should be build into the ROM as @c z:\\resource\\swicertstore.dat.

@section sec3 Access to the SWI cert store from the unified cert store

Although software install cannot access the unified cert store, it is still
possible for the SWI cert store to be accessible via the unified cert store.
This is accomplished by the cert store plugin @c swicertstoreplugin.dll.  This
idea is to make it easier to see which certificates are present on a device, and
also so that certificates which are used for multiple applications including
software install do not need to be duplicated in more than one store.

*/