/**

@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.

*/