|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-36539894-580E-5774-AA79-7F640E8C59E1" xml:lang="en"><title>Central |
|
13 Repository Initialisation Files Guide</title><shortdesc>This topic describes the concepts of initialisation files used |
|
14 by the Central Repository. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-EAB04F5A-A208-4537-8EEF-6C6BE9F951ED"><title>Initialisation file properties</title> <p>The mechanisms of |
|
16 key spaces, capabilities and SIDs are used to write the content of an initialisation |
|
17 file. </p> <p><b>Owner </b> </p> <p>The owner of a repository (the application responsible |
|
18 for backing it up) is identified by its SID. Example: </p> <codeblock id="GUID-3057056D-64F4-5A3D-9644-9B1417EFDC89" xml:space="preserve"> |
|
19 [owner] |
|
20 0x12345 |
|
21 </codeblock> <p><b>Metadata </b> </p> <p>Settings of a repository are given values and also |
|
22 metadata values. The Default Metadata section of a repository gives the settings |
|
23 global default metadata values which may be overridden by individual metadata |
|
24 values assigned in the Main section. A metadata value is held as a 32 bit |
|
25 integer whose binary digits encode separate items of metadata. The most significant |
|
26 eight bits (most significant byte) of the integer are reserved for internal |
|
27 purposes. The other 24 bits of the integer have no reserved significance. |
|
28 Two of the eight bits are exposed for use by application developers. </p> <ul> |
|
29 <li id="GUID-65872DE7-F12A-5F1E-892C-937C81053E48"><p>The least significant |
|
30 bit of the most significant byte is set to 1 to indicate that a backup operation |
|
31 applies to the setting. </p> </li> |
|
32 <li id="GUID-A13A915F-EDBC-5E69-8557-D4FC6789CE23"><p>The second least significant |
|
33 bit of the most significant byte is set to 1 to indicate that a restore factory |
|
34 settings operation applies to the setting. </p> </li> |
|
35 </ul> <p>What is meant by least and most significant? An example may help. |
|
36 A hexadecimal number such as 03020100 is stored as a single 32 bit integer. |
|
37 The integer can be analysed as a sequence of four bytes: </p> <p>03 02 01 |
|
38 00 </p> <p>The leftmost byte, 03, is the most significant byte because it |
|
39 represents a larger quantity (03000000) than the other three (02000, 0100 |
|
40 and 00). Each byte consists of eight bits. In binary notation they are </p> <p>00000011 |
|
41 00000010 00000001 00000000 </p> <p>The rightmost bit of the leftmost byte |
|
42 is the least significant bit of the most significant byte because it represents |
|
43 a smaller quantity (1) than its neighbour to the left (10) which is the second |
|
44 least significant bit of the most significant byte. These are the two exposed |
|
45 bits of the metadata value and the hexadecimal integer 03020100 has both of |
|
46 them set to 1. The 32 bits are sometimes referred to by number (32 for the |
|
47 leftmost down to 1 for the rightmost): thus the exposed bits are also called |
|
48 bits 26 and 25. </p> <p>Global default metadata values consist simply of a |
|
49 32 bit integer. Default metadata values can also be applied to a range of |
|
50 settings by prefixing either a pair of keys representing a continuous range, |
|
51 or else a partial key and a key mask prefixed by "mask=". Example: </p> <codeblock id="GUID-EC5F473A-86AB-58CF-878B-7AFD7EE69779" xml:space="preserve"> |
|
52 [defaultMeta] |
|
53 0x00000010 |
|
54 0x100 0x400 0x00000020 |
|
55 0x1000 mask = 0x04 0x00000040 |
|
56 </codeblock> </section> |
|
57 <section id="GUID-04903C24-0CEC-4937-BC94-77540BFC3F7D"><title>Access policies </title> <p>An access policy grants read or |
|
58 write permissions on a setting or a group of settings to an application or |
|
59 a group of applications. Applications are identified by their SID and groups |
|
60 of applications by their capability name. </p> <p>Decide which applications |
|
61 you want to grant permissions to, and whether you are going to identify them |
|
62 by capability or SID. SIDs are unsigned integers which identify an application |
|
63 and are assigned by Symbian Signed. Identify the settings and groups of settings |
|
64 which are to be written and read: you will need their keys and partial keys. |
|
65 Determine which applications need read or write permissions on which settings. </p> <p>You |
|
66 create an access policy by combining these elements using the following syntax. </p> <ul> |
|
67 <li id="GUID-A3E78BC6-7436-59E6-8C6F-B546B638BABB"><p>A capname is one of |
|
68 '<codeph>TCB</codeph>' '<codeph>CommDD</codeph>' etc. A caplist is two or |
|
69 three capnames separated by a comma and whitespace. A read caps statement |
|
70 is "cap_rd" followed by a capname or a caplist. </p> </li> |
|
71 <li id="GUID-5A76E256-BF6B-5CAD-A45C-C07140C4EEEE"><p>A read sid statement |
|
72 is "<codeph>sid_rd</codeph> " followed by an SID. </p> </li> |
|
73 <li id="GUID-0EE23D2A-2EED-5CEA-BF6D-7B23D11E9935"><p>A read policy is a read |
|
74 sid statement or a read caps statement or one of each separated by whitespace. |
|
75 A write policy is the same as a read policy with "_wr" instead of "_rd". An |
|
76 access policy is a read policy or a write policy or one of each separated |
|
77 by whitespace. </p> </li> |
|
78 <li id="GUID-EAB2A33E-99C2-5B40-8333-232761A7BC91"><p>Instead of granting |
|
79 or denying permissions to specified applications, you can create global permissions |
|
80 by using the words 'AlwaysPass' or 'AlwaysFail' in place of an SID. For instance, |
|
81 'sid_rd AlwaysPass' grants read permissions to all applications, 'sid_wr AlwaysFail' |
|
82 denies write permissions to all applications and so on. </p> </li> |
|
83 </ul> <p>An access policy constructed on these lines with no further qualification |
|
84 creates permissions on all the settings in a repository (this is called a |
|
85 default policy). To create permissions on individual settings (a single policy) |
|
86 or a group of settings (a range policy or a mask policy depending on implementation) |
|
87 we use the keys of those settings. </p> <ul> |
|
88 <li id="GUID-F86D7F23-EB24-5169-B072-EED5BEC5925D"><p>A single policy is a |
|
89 default policy prefixed with a key referring to a single setting. </p> </li> |
|
90 <li id="GUID-0F83526E-BF07-5914-887B-E128CFC59775"><p>A range policy is a |
|
91 default policy prefixed with two keys, the lowerkey and the upperkey. The |
|
92 policy assigns permissions on all settings with keys between the lowerkey |
|
93 and the upperkey inclusively. </p> </li> |
|
94 <li id="GUID-BA19291D-8F06-5D6D-932C-8F0B8554DF51"><p>A mask policy is an |
|
95 access policy prefixed with a partial key and then "mask=" and a keymask. </p> </li> |
|
96 <li id="GUID-828D372D-0297-5CDF-93E7-10A63516E698"><p>A custom policy is a |
|
97 single policy, a range policy or a mask policy. A policy list is a custom |
|
98 policy or several custom policies separated by whitespace. </p> </li> |
|
99 </ul> <p>We have now defined the structure of the access policy section of |
|
100 an initialisation file. It consists of a line reading "[PlatSec]" followed |
|
101 by a default policy or a policy list or one of each separated by whitespace. |
|
102 Where several policies in a list apply to the same key, the later policy overrides |
|
103 the earlier. The read policies, each on a separate line, must precede the |
|
104 write policies, each on a separate line. </p> </section> |
|
105 <section id="GUID-F2F1838D-D5A7-4720-9D10-3BEFFF64732E"><title> Initial values </title> <p>Initial values are assigned to |
|
106 settings in the Main section of an initialisation file. Each line begins with |
|
107 a setting identified by an individual key or a group of settings identified |
|
108 by a pair of keys representing a range or else a keymask and a partial key. |
|
109 Following the key or keys comes the data type of the setting, one of <codeph>int</codeph>, <codeph>real</codeph>, |
|
110 string, <codeph>string8</codeph> or <codeph>binary</codeph>. Next comes the |
|
111 actual initial value of the setting and finally, as an optional item, the |
|
112 metadata value of the setting. Example: </p> <codeblock id="GUID-585347BA-219A-5372-8C62-77E927A5D690" xml:space="preserve"> |
|
113 [main] |
|
114 |
|
115 1 int 1 0 |
|
116 2 real 2.732 0xa |
|
117 5 string "test\\\"string\"" 2 |
|
118 6 int 12 0xf |
|
119 8 real 1.5 1 |
|
120 11 string string 0x305 |
|
121 12 string8 string 0x305 |
|
122 |
|
123 0x11 real 1.5 12 |
|
124 0x101 int 100 0 |
|
125 </codeblock> </section> |
|
126 <section id="GUID-12599A2C-BE97-5B18-9BB9-EB833A40536A"><title>Initialisation |
|
127 file format</title> <p>You use an initialisation file to register a repository |
|
128 by saving it to device memory. Ideally you do this at ROM build time and save |
|
129 to the directory <filepath>z:\private\10202BE9\</filepath> (this is the Central |
|
130 Repository directory, named after its UID). It is also possible to register |
|
131 a repository after build time using the Symbian Software Installer to save |
|
132 it to the C drive. This process requires a signed SIS file and is explained |
|
133 below. In either case, the file name of the repository is the same as its |
|
134 UID. </p> <p>A repository may be saved to memory as a text file. The encoding |
|
135 must be UTF-16, no other format being supported. However, you are recommended |
|
136 to convert this text file to binary format and save the binary to device memory |
|
137 for reasons of performance. Retrieval times are an order of magnitude faster |
|
138 using binary files. You convert text to binary with the tool CentRepConv.exe |
|
139 as documented in <xref href="id1236097240207" scope="external">CenRep Converter |
|
140 Tool Tutorial</xref>. CentRepConv.exe can also be used to convert binary files |
|
141 back to text format (in a slightly lossy way due to differences in the specification |
|
142 of the two formats). </p> </section> |
|
143 </conbody><related-links> |
|
144 <link href="GUID-CBC57511-7F28-596A-9763-5674EB41BCAC.dita"><linktext>Central Repository |
|
145 Overview</linktext></link> |
|
146 <link href="GUID-E3BE62B2-9625-5F79-84A4-0248A3F36225.dita"><linktext>Central Repository |
|
147 Guide</linktext></link> |
|
148 <link href="GUID-53E5C9EA-0A38-54A1-AE24-95B71BFFB4B5.dita"><linktext>CenRep Converter |
|
149 Tool Tutorial</linktext></link> |
|
150 </related-links></concept> |