|
1 /** |
|
2 |
|
3 @page SWICertStore The SWI Cert Store |
|
4 |
|
5 @section sec1 Introduction |
|
6 |
|
7 This document descibes the software install certificate store, or SWI cert |
|
8 store. |
|
9 |
|
10 Software install requires access to root certificates in order to validate |
|
11 signed install packages (SIS files). However for security reasons the softare |
|
12 install server is not allowed to dynamically load plugins (it is part of the |
|
13 trusted computing base). This means that it cannot use the unified cert store, |
|
14 as would be the case for normal applications. Instead it uses a dedicated |
|
15 certificate store which it links to directly - the SWI cert store. |
|
16 |
|
17 The SWI cert store is a read-only cert store, implemented using a data file that |
|
18 is built into the ROM on a device. This data file must be created before ROM |
|
19 build time, and it must contain the root certificates necessary to valdiate all |
|
20 SIS files that will be installed on the device. |
|
21 |
|
22 In addtion to the usual cert store operations, the SWI certstore contains |
|
23 additional meta-data that is relevant only to software install. For each |
|
24 certificate it contains a set of capabilities which that certificate is |
|
25 authorised to sign for, and a mandatory flag. If the mandatory flag is set for |
|
26 a certificate, it indicates that every SIS file installed must be signed by a |
|
27 cerificate issued under that certificate. |
|
28 |
|
29 @section sec2 Creating the SWI cert store data file |
|
30 |
|
31 The data file for the SWI cert store is built using the "swicertstoretool" |
|
32 program. This is an epoc binary that runs in the emulator, built as part of the |
|
33 security tests. |
|
34 |
|
35 The format of the command is: |
|
36 |
|
37 @code |
|
38 swicertstoretool INPUT_FILE OUTPUT_FILE LOG_FILE |
|
39 @endcode |
|
40 |
|
41 The paramters have the following meanings: |
|
42 |
|
43 - @c INPUT_FILE - An "ini" format file describing the certificates and |
|
44 meta-data that will be used to populate the store |
|
45 - @c OUTPUT_FILE - The path the data file will be written to |
|
46 - @c LOG_FILE - The path the results of the process will be written to |
|
47 |
|
48 @subsection sec21 Input file format |
|
49 |
|
50 The input file is a text file in "ini" format, made up of one or more sections, |
|
51 each of which contains attributes related to that section. A section is |
|
52 introduced with a line containing the section name in square brackets. |
|
53 Attributes are specified by @c name=value pairs. |
|
54 |
|
55 Each section describes a certificate to be put in the store, with the section |
|
56 name used as the certificate label. |
|
57 |
|
58 The following attributes can be specified for each certificate: |
|
59 |
|
60 <table> |
|
61 |
|
62 <tr> |
|
63 <th>Attribute:</th> |
|
64 <th>Desciption:</th> |
|
65 </tr> |
|
66 |
|
67 <tr> |
|
68 <td>file</td> |
|
69 <td> |
|
70 The name of the file containing the DER encoded certificate. This attribute |
|
71 must be present. |
|
72 </td> |
|
73 </tr> |
|
74 |
|
75 <tr> |
|
76 <td>mandatory</td> |
|
77 <td> |
|
78 Whether the certificate is marked as mandatory for software install. The |
|
79 value must be either "1" (mandatory) or "0" (not mandatory). The attribute is |
|
80 optional - if it is not present the default is "0". |
|
81 </td> |
|
82 </tr> |
|
83 |
|
84 <tr> |
|
85 <td>capability</td> |
|
86 <td> |
|
87 The name of a capability that the certificate can sign for. This attribute can be |
|
88 repeated to allow multiple capabilities to be specified. Allowed capabilities |
|
89 are: |
|
90 |
|
91 - TCB |
|
92 - CommDD |
|
93 - PowerMgmt |
|
94 - MultimediaDD |
|
95 - ReadDeviceData |
|
96 - WriteDeviceData |
|
97 - DRM |
|
98 - TrustedUI |
|
99 - ProtServ |
|
100 - DiskAdmin |
|
101 - NetworkControl |
|
102 - AllFiles |
|
103 - SwEvent |
|
104 - NetworkServices |
|
105 - LocalServices |
|
106 - ReadUserData |
|
107 - WriteUserData |
|
108 - Location |
|
109 </td> |
|
110 </tr> |
|
111 |
|
112 <tr> |
|
113 <td>application</td> |
|
114 <td> |
|
115 The name of an application that the certificate can be used for. This can be |
|
116 repeated, but it must appear at least once. Allowed applications are: |
|
117 |
|
118 - SWInstall (Software install) |
|
119 - SWInstallOCSP (Software install OCSP signing) |
|
120 </td> |
|
121 </tr> |
|
122 |
|
123 </table> |
|
124 |
|
125 Unrecognised attributes are ingnored. |
|
126 |
|
127 @subsubsection sec211 Example input file |
|
128 |
|
129 Below is an example of an input file used for testing software install: |
|
130 |
|
131 @code |
|
132 # exmplateInputFile.txt |
|
133 # |
|
134 # An example input file for the swi cert store tool |
|
135 |
|
136 [Root5CA] |
|
137 file = c:\system\TOCSP\Certs\newopenssl\Root5-RSA.der |
|
138 mandatory = 1 |
|
139 capability = ReadDeviceData |
|
140 capability = WriteDeviceData |
|
141 capability = DRM |
|
142 capability = AllFiles |
|
143 application = SWInstall |
|
144 |
|
145 [SymbianTestDSACA] |
|
146 file = c:\tappinst\certs\Symbian-Test-DSA.der |
|
147 capability = NetworkServices |
|
148 capability = LocalServices |
|
149 capability = Location |
|
150 application = SWInstall |
|
151 application = SWInstallOCSP |
|
152 |
|
153 [SymbianTestRSACA] |
|
154 file = c:\tappinst\certs\Symbian-Test-RSA.der |
|
155 capability = ReadUserData |
|
156 capability = WriteUserData |
|
157 application = SWInstall |
|
158 application = SWInstallOCSP |
|
159 @endcode |
|
160 |
|
161 @subsubsection sec212 Log file |
|
162 |
|
163 The log file should be examined each time the tool is run, as this is the only |
|
164 way in which errors are reported. The log file describes the stages of |
|
165 processing and will end either with an error message or the line "Done" if the |
|
166 data file has been created successfully. |
|
167 |
|
168 @section sec213 Installing the data file |
|
169 |
|
170 The SWI cert store looks for the data file produced by the tool at @c |
|
171 z:\\resource\\swicertstore.dat. So for the emulator, this should be copied to |
|
172 @c \\epoc32\\RELEASE\\winscw\\UDEB\\Z\\Resource\\swicertstore.dat, and for |
|
173 hardware it should be build into the ROM as @c z:\\resource\\swicertstore.dat. |
|
174 |
|
175 @section sec3 Access to the SWI cert store from the unified cert store |
|
176 |
|
177 Although software install cannot access the unified cert store, it is still |
|
178 possible for the SWI cert store to be accessible via the unified cert store. |
|
179 This is accomplished by the cert store plugin @c swicertstoreplugin.dll. This |
|
180 idea is to make it easier to see which certificates are present on a device, and |
|
181 also so that certificates which are used for multiple applications including |
|
182 software install do not need to be duplicated in more than one store. |
|
183 |
|
184 */ |