ia64/xen-unstable

view tools/security/example.txt @ 7238:971e7c7411b3

Raise an exception if an error appears on the pipes to our children, and make
sure that the child's pipes are closed even under that exception. Move the
handling of POLLHUP to the end of the loop, so that we guarantee to read any
remaining data from the child if POLLHUP and POLLIN appear at the same time.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author emellor@ewan
date Thu Oct 06 10:13:11 2005 +0100 (2005-10-06)
parents 06d84bf87159
children 8aac8746047b
line source
1 ##
2 # example.txt <description to the xen access control architecture>
3 #
4 # Author:
5 # Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
6 #
7 #
8 # This file introduces into the tools to manage policies
9 # and to label domains and resources.
10 ##
12 We will show how to install and use the chwall_ste policy.
13 Other policies work similarly. Feedback welcome!
17 1. Using secpol_xml2bin to translate the chwall_ste policy:
18 ===========================================================
20 #tools/security/secpol_xml2bin chwall_ste
22 Successful execution should print:
24 [root@laptopxn security]# ./secpol_xml2bin chwall_ste
25 Validating label file policies/chwall_ste/chwall_ste-security_label_template.xml...
26 XML Schema policies/security_policy.xsd valid.
27 Validating policy file policies/chwall_ste/chwall_ste-security_policy.xml...
28 XML Schema policies/security_policy.xsd valid.
29 Creating ssid mappings ...
30 Creating label mappings ...
31 Max chwall labels: 7
32 Max chwall-types: 4
33 Max chwall-ssids: 5
34 Max ste labels: 14
35 Max ste-types: 6
36 Max ste-ssids: 10
38 The tool looks in directory policies/chwall_ste for
39 the label and policy files.
41 The default policy directory structure under tools/security looks like:
43 policies
44 |-- security_policy.xsd
45 |-- chwall
46 | |-- chwall-security_label_template.xml
47 | `-- chwall-security_policy.xml
48 |-- chwall_ste
49 | |-- chwall_ste-security_label_template.xml
50 | `-- chwall_ste-security_policy.xml
51 |-- null
52 | |-- null-security_label_template.xml
53 | `-- null-security_policy.xml
54 `-- ste
55 |-- ste-security_label_template.xml
56 `-- ste-security_policy.xml
58 policies/security_policy.xsd contains the schema against which both the
59 label-template and the policy files must validate during translation.
61 policies/chwall_ste/chwall_ste-security_policy.xml defines the
62 policies and the types known to the policies.
64 policies/chwall_ste/chwall_ste-security_label_template.xml contains
65 label definitions that group chwall and ste types together and make
66 them easier to use for users
68 After executing the above secpol_xml2bin command, you will find 2 new
69 files in the policies/chwall_ste sub-directory:
71 policies/chwall_ste/chwall_ste.map ... this file includes the mapping
72 of names from the xml files into their binary code representation.
74 policies/chwall_ste/chwall_ste.bin ... this is the binary policy file,
75 the result of parsing the xml files and using the mapping to extract a
76 binary version that can be loaded into the hypervisor.
80 2. Loading and activating the policy:
81 =====================================
83 We assume that xen is already configured to use the chwall_ste policy;
84 please refer to install.txt for instructions.
86 To activate the policy from the command line (assuming that the
87 currently established policy is the minimal boot-policy that is
88 hard-coded into the hypervisor:
90 # ./secpol_tool loadpolicy policies/chwall_ste/chwall_ste.bin
92 To activate the policy at next reboot:
94 # cp policies/chwall_ste/chwall_ste.bin /boot
96 Add a module line to your /boot/grub/grub.conf Xen entry.
97 My boot entry with chwall_ste enabled looks like this:
99 title Xen (2.6.12)
100 root (hd0,5)
101 kernel /boot/xen.gz dom0_mem=1200000 console=vga
102 module /boot/vmlinuz-2.6.12-xen0 ro root=/dev/hda6 rhgb
103 module /boot/initrd-2.6.12-xen0.img
104 module /boot/chwall_ste.bin
106 This tells the grub boot-loader to load the binary policy, which
107 the hypervisor will recognize. The hypervisor will then establish
108 this binary policy during boot instead of the minimal policy that
109 is hardcoded as default.
111 If you have any trouble here, maks sure you have the access control
112 framework enabled (see: install.txt).
116 3. Labeling domains:
117 ====================
119 a) Labeling Domain0:
121 The chwall_ste-security_label_template.xml file includes an attribute
122 "bootstrap", which is set to the label name that will be assigned to
123 Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).
125 b) Labeling User Domains:
127 Use the script tools/security/setlabel.sh to choose a label and to
128 assign labels to user domains.
130 To show available labels for the chwall_ste policy:
132 #tools/security/setlabel.sh -l
134 lists all available labels. For the default chwall_ste it should print
135 the following:
137 [root@laptopxn security]# ./setlabel.sh -l chwall_ste
138 The following labels are available:
139 dom_SystemManagement
140 dom_HomeBanking
141 dom_Fun
142 dom_BoincClient
143 dom_StorageDomain
144 dom_NetworkDomain
146 You need to have compiled the policy beforehand so that a .map file
147 exists. Setlabel.sh uses the mapping file created throughout the
148 policy translation to translate a user-friendly label string into a
149 ssidref-number that is eventually used by the Xen hypervisor.
151 We distinguish two kinds of labels: a) VM labels (for domains) and RES
152 Labels (for resources). We are currently working on support for
153 resource labeling but will focus here on VM labels.
155 Setlabel.sh only prints VM labels (which we have prefixed with "dom_")
156 since only those are used at this time.
158 If you would like to assign the dom_HomeBanking label to one of your
159 user domains (which you hopefully keep clean), look at an example
160 domain configuration homebanking.xm:
162 #------HOMEBANKING---------
163 kernel = "/boot/vmlinuz-2.6.12-xenU"
164 ramdisk="/boot/U1_ramdisk.img"
165 memory = 65
166 name = "test34"
167 cpu = -1 # leave to Xen to pick
168 # Number of network interfaces. Default is 1.
169 nics=1
170 dhcp="dhcp"
171 #-------------------------
173 Now we label this domain
175 [root@laptopxn security]# ./setlabel.sh homebanking.xm dom_HomeBanking chwall_ste
176 Mapped label 'dom_HomeBanking' to ssidref '0x00020002'.
178 The domain configuration my look now like:
180 [root@laptopxn security]# cat homebanking.xm
181 #------HOMEBANKING---------
182 kernel = "/boot/vmlinuz-2.6.12-xenU"
183 ramdisk="/boot/U1_ramdisk.img"
184 memory = 65
185 name = "test34"
186 cpu = -1 # leave to Xen to pick
187 # Number of network interfaces. Default is 1.
188 nics=1
189 dhcp="dhcp"
190 #-------------------------
191 #ACM_POLICY=chwall_ste-security_policy.xml
192 #ACM_LABEL=dom_HomeBanking
193 ssidref = 0x00020002
195 You can see 3 new entries, two of which are comments. The only value
196 that the hypervisor cares about is the ssidref that will reference
197 those types assigned to this label. You can look them up in the
198 xml label-template file for the chwall_ste policy.
200 This script will eventually move into the domain management and will
201 be called when the domain is instantiated. For now, the setlabel
202 script must be run on domains whenever the policy files change since
203 the mapping between label names and ssidrefs can change in this case.
206 4. Starting a labeled domain
207 ============================
209 Now, start the domain:
210 #xm create -c homebanking.xm
213 If you label another domain configuration as dom_Fun and try to start
214 it afterwards, its start will fail. Why?
216 Because the running homebanking domain has the chinese wall type
217 "cw_Sensitive". The new domain dom_Fun has the chinese wall label
218 "cw_Distrusted". This domain is not allowed to run simultaneously
219 because of the defined conflict set
221 <conflictset name="Protection1">
222 <type>cw_Sensitive</type>
223 <type>cw_Distrusted</type>
224 </conflictset>
226 (in policies/chwall_ste/chwall_ste-security_policy.xml), which says
227 that only one of the types cw_sensitive and cw_Distrusted can run at a
228 time.
230 If you save or shutdown the HomeBanking domain, you will be able to
231 start the "Fun" domain. You can look into the Xen log to see if a
232 domain was denied to start because of the access control framework
233 with the command 'xm dmesg'.
235 It is important (and usually non-trivial) to define the labels in a
236 way that the semantics of the labels are enforced and supported by the
237 types and the conflict sets.
239 Note: While the chinese wall policy enforcement is complete, the type
240 enforcement is currently enforced in the Xen hypervisor
241 only. Therefore, only point-to-point sharing with regard to the type
242 enforcement is currently controlled. We are working on enhancements to
243 Dom0 that enforce types also for network traffic that is routed
244 through Dom0 and on the enforcement of resource labeling when binding
245 resources to domains (e.g., enforcing types between domains and
246 hardware resources, such as disk partitions).
249 4. Adding your own policies
250 ===========================
252 Writing your own policy (e.g. "mypolicy") requires the following:
254 a) the policy definition (types etc.) file
255 b) the label template definition (labels etc.) file
257 If your policy name is "mypolicy", you need to create a
258 subdirectory mypolicy in tools/security/policies.
260 Then you create
261 tools/security/policies/mypolicy/mypolicy-security_policy.xml and
262 tools/security/policies/mypolicy/mypolicy-security_label_template.xml.
264 You need to keep to the schema as defined in
265 tools/security/security_policy.xsd since the translation tool
266 secpol_xml2bin is written against this schema.
268 If you keep to the security policy schema, then you can use all the
269 tools described above. Refer to install.txt to install it.