ia64/xen-unstable

view tools/security/example.txt @ 8740:3d7ea7972b39

Update patches for linux 2.6.15.

Signed-off-by: Christian Limpach <Christian.Limpach@cl.cam.ac.uk>
author cl349@firebug.cl.cam.ac.uk
date Thu Feb 02 17:16:00 2006 +0000 (2006-02-02)
parents 269abc1e4fa5
children c7b9b8a64755
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 example chwall_ste policy.
13 Other policies work similarly. Feedback welcome!
17 1. Using xensec_xml2bin to translate the chwall_ste policy:
18 ===========================================================
20 #xensec_xml2bin chwall_ste
22 Successful execution should print:
24 [root@laptopxn security]# xensec_xml2bin chwall_ste
25 Validating label file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_label_template.xml...
26 XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
27 Validating policy file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_policy.xml...
28 XML Schema /etc/xen/acm-security/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 By default, the tool looks in directory /etc/xen/acm-security/policies
39 for a directory that matches the policy name (i.e. chwall_ste) to find
40 the label and policy files.
41 The '-d' option can be used to override the /etc/xen/acm-security/policies
42 directory, for example if running the tool in the Xen security tool build
43 directory.
45 The default policy directory structure under /etc/xen/acm-security (and
46 the Xen security tool build directory - tools/security) looks like:
48 policies
49 |-- security_policy.xsd
50 |-- chwall
51 | |-- chwall-security_label_template.xml
52 | `-- chwall-security_policy.xml
53 |-- chwall_ste
54 | |-- chwall_ste-security_label_template.xml
55 | `-- chwall_ste-security_policy.xml
56 |-- null
57 | |-- null-security_label_template.xml
58 | `-- null-security_policy.xml
59 `-- ste
60 |-- ste-security_label_template.xml
61 `-- ste-security_policy.xml
63 The security_policy.xsd file contains the schema against which both the
64 label-template and the policy files must validate during translation.
66 The files ending in -security_policy.xml define the policies and the
67 types known to the policies.
69 The files ending in -security_label_template.xml contain the label
70 definitions that group types together and make them easier to use for
71 users.
73 After executing the above xensec_xml2bin command, you will find 2 new
74 files in the /etc/xen/acm-security/policies/chwall_ste sub-directory:
76 chwall_ste.map ... this file includes the mapping
77 of names from the xml files into their binary code representation.
79 chwall_ste.bin ... this is the binary policy file,
80 the result of parsing the xml files and using the mapping to extract a
81 binary version that can be loaded into the hypervisor.
85 2. Loading and activating the policy:
86 =====================================
88 We assume that xen is already configured to use the chwall_ste policy;
89 please refer to install.txt for instructions.
91 To activate the policy from the command line (assuming that the
92 currently established policy is the minimal boot-policy that is
93 hard-coded into the hypervisor):
95 # xensec_tool loadpolicy /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin
97 To activate the policy at next reboot:
99 # cp /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin /boot
101 Add a module line to your /boot/grub/grub.conf Xen entry.
102 My boot entry with chwall_ste enabled looks like this:
104 title Xen (2.6.12)
105 root (hd0,5)
106 kernel /boot/xen.gz dom0_mem=1200000 console=vga
107 module /boot/vmlinuz-2.6.12-xen0 ro root=/dev/hda6 rhgb
108 module /boot/initrd-2.6.12-xen0.img
109 module /boot/chwall_ste.bin
111 This tells the grub boot-loader to load the binary policy, which
112 the hypervisor will recognize. The hypervisor will then establish
113 this binary policy during boot instead of the minimal policy that
114 is hardcoded as default.
116 If you have any trouble here, maks sure you have the access control
117 framework enabled (see: install.txt).
121 3. Labeling domains:
122 ====================
124 a) Labeling Domain0:
126 The chwall_ste-security_label_template.xml file includes an attribute
127 "bootstrap", which is set to the label name that will be assigned to
128 Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).
130 b) Labeling User Domains:
132 Use the script tools/security/setlabel.sh to choose a label and to
133 assign labels to user domains.
135 To show available labels for the chwall_ste policy:
137 # /etc/xen/acm-security/scripts/setlabel.sh -l
139 lists all available labels. For the default chwall_ste it should print
140 the following:
142 [root@laptopxn security]# /etc/xen/acm-security/scripts/setlabel.sh -l chwall_ste
143 The following labels are available:
144 dom_SystemManagement
145 dom_HomeBanking
146 dom_Fun
147 dom_BoincClient
148 dom_StorageDomain
149 dom_NetworkDomain
151 You need to have compiled the policy beforehand so that a .map file
152 exists. Setlabel.sh uses the mapping file created throughout the
153 policy translation to translate a user-friendly label string into a
154 ssidref-number that is eventually used by the Xen hypervisor.
156 We distinguish two kinds of labels: a) VM labels (for domains) and RES
157 Labels (for resources). We are currently working on support for
158 resource labeling but will focus here on VM labels.
160 Setlabel.sh only prints VM labels (which we have prefixed with "dom_")
161 since only those are used at this time.
163 If you would like to assign the dom_HomeBanking label to one of your
164 user domains (which you hopefully keep clean), look at the hypothetical
165 domain configuration contained in /etc/xen/homebanking.xm:
167 #------HOMEBANKING---------
168 kernel = "/boot/vmlinuz-2.6.12-xenU"
169 ramdisk="/boot/U1_ramdisk.img"
170 memory = 65
171 name = "test34"
172 cpu = -1 # leave to Xen to pick
173 # Number of network interfaces. Default is 1.
174 nics=1
175 dhcp="dhcp"
176 #-------------------------
178 Now we label this domain
180 [root@laptopxn security]# /etc/xen/acm-securit/scripts/setlabel.sh /etc/xen/homebanking.xm dom_HomeBanking chwall_ste
181 Mapped label 'dom_HomeBanking' to ssidref '0x00020002'.
183 The domain configuration my look now like:
185 [root@laptopxn security]# cat homebanking.xm
186 #------HOMEBANKING---------
187 kernel = "/boot/vmlinuz-2.6.12-xenU"
188 ramdisk="/boot/U1_ramdisk.img"
189 memory = 65
190 name = "test34"
191 cpu = -1 # leave to Xen to pick
192 # Number of network interfaces. Default is 1.
193 nics=1
194 dhcp="dhcp"
195 #-------------------------
196 #ACM_POLICY=chwall_ste-security_policy.xml
197 #ACM_LABEL=dom_HomeBanking
198 ssidref = 0x00020002
200 You can see 3 new entries, two of which are comments. The only value
201 that the hypervisor cares about is the ssidref that will reference
202 those types assigned to this label. You can look them up in the
203 xml label-template file for the chwall_ste policy.
205 This script will eventually move into the domain management and will
206 be called when the domain is instantiated. For now, the setlabel
207 script must be run on domains whenever the policy files change since
208 the mapping between label names and ssidrefs can change in this case.
211 4. Starting a labeled domain
212 ============================
214 Now, start the domain:
215 #xm create -c homebanking.xm
218 If you label another domain configuration as dom_Fun and try to start
219 it afterwards, its start will fail. Why?
221 Because the running homebanking domain has the chinese wall type
222 "cw_Sensitive". The new domain dom_Fun has the chinese wall label
223 "cw_Distrusted". This domain is not allowed to run simultaneously
224 because of the defined conflict set
226 <conflictset name="Protection1">
227 <type>cw_Sensitive</type>
228 <type>cw_Distrusted</type>
229 </conflictset>
231 (in chwall_ste-security_policy.xml), which says that only one of the
232 types cw_Sensitive and cw_Distrusted can run at a time.
234 If you save or shutdown the HomeBanking domain, you will be able to
235 start the "Fun" domain. You can look into the Xen log to see if a
236 domain was denied to start because of the access control framework
237 with the command 'xm dmesg'.
239 It is important (and usually non-trivial) to define the labels in a
240 way that the semantics of the labels are enforced and supported by the
241 types and the conflict sets.
243 Note: While the chinese wall policy enforcement is complete, the type
244 enforcement is currently enforced in the Xen hypervisor
245 only. Therefore, only point-to-point sharing with regard to the type
246 enforcement is currently controlled. We are working on enhancements to
247 Dom0 that enforce types also for network traffic that is routed
248 through Dom0 and on the enforcement of resource labeling when binding
249 resources to domains (e.g., enforcing types between domains and
250 hardware resources, such as disk partitions).
253 4. Adding your own policies
254 ===========================
256 Writing your own policy (e.g. "mypolicy") requires the following:
258 a) the policy definition (types etc.) file
259 b) the label template definition (labels etc.) file
261 If your policy name is "mypolicy", you need to create a
262 subdirectory mypolicy in /etc/xen/acm-security/policies.
264 Then you create
265 /etc/xen/acm-security/policies/mypolicy/mypolicy-security_policy.xml and
266 /etc/xen/acm-security/policies/mypolicy/mypolicy-security_label_template.xml.
268 You need to keep to the schema as defined in
269 /etc/xen/acm-security/security_policy.xsd since the translation tool
270 xensec_xml2bin is written against this schema.
272 If you keep to the security policy schema, then you can use all the
273 tools described above. Refer to install.txt to install it.
275 You can hand-edit the xml files to create your policy or you can use the
276 xensec_gen utility.
279 5. Generating policy files using xensec_gen:
280 ============================================
282 The xensec_gen utility starts a web-server that can be used to generate the
283 XML policy files needed to create a policy.
285 By default, xensec_gen runs as a daemon and listens on port 7777 for HTTP
286 requests. The xensec_gen command supports command line options to change the
287 listen port, run in the foreground, and a few others. Type 'xensec_gen -h'
288 to see the full list of options available.
290 Once the xensec_gen utility is running, point a browser at the host and port
291 on which the utility is running (e.g. http://localhost:7777/). You will be
292 presented with a web page that allows you to create or modify the XML policy
293 files:
295 - The Security Policy section allows you to create or modify a policy
296 definition file
298 - The Security Policy Labeling section allows you to create or modify a
299 label template definition file
301 Security Policy:
302 ----------------
303 The Security Policy section allows you to modify an existing policy definition
304 file or create a new policy definition file. To modify an existing policy
305 definition, enter the full path to the existing file (the "Browse" button can
306 be used to aid in this) in the Policy File entry field. To create a new
307 policy definition file leave the Policy File entry field blank. At this point
308 click the "Create" button to begin modifying or creating your policy definition.
310 You will then be presented with a web page that will allow you to create either
311 Simple Type Enforcement types or Chinese Wall types or both.
313 As an example:
314 - To add a Simple Type Enforcement type:
315 - Enter the name of a new type under the Simple Type Enforcement Types
316 section in the entry field above the "New" button.
317 - Click the "New" button and the type will be added to the list of defined
318 Simple Type Enforcement types.
319 - To remove a Simple Type Enforcement type:
320 - Click on the type to be removed in the list of defined Simple Type
321 Enforcement types.
322 - Click the "Delete" button to remove the type.
324 Follow the same process to add Chinese Wall types. If you define Chinese Wall
325 types you need to define at least one Chinese Wall Conflict Set. The Chinese
326 Wall Conflict Set will allow you to add Chinese Wall types from the list of
327 defined Chinese Wall types.
329 To create your policy definition file, click on the "Generate XML" button on
330 the top of the page. This will present you with a dialog box to save the
331 generated XML file on your system. The default name will be security_policy.xml
332 which you should change to follow the policy file naming conventions based on
333 the policy name that you choose to use.
335 To get a feel for the tool, you could use one of the example policy definition
336 files from /etc/xen/acm-security/policies as input.
339 Security Policy Labeling:
340 -------------------------
341 The Security Policy Labeling section allows you to modify an existing label
342 template definition file or create a new label template definition file. To
343 modify an existing label template definition, enter the full path to the
344 existing file (the "Browse" button can be used to aid in this) in the Policy
345 Labeling File entry field. Whether creating a new label template definition
346 file or modifying an existing one, you will need to specify the policy
347 definition file that is or will be associated with this label template
348 definition file. At this point click the "Create" button to begin modifying
349 or creating your label template definition file.
351 You will then be presented with a web page that will allow you to create labels
352 for classes of virtual machines. The input policy definition file will provide
353 the available types (Simple Type Enforcement and/or Chinese Wall) that can be
354 assigned to a virtual machine class.
356 As an example:
357 - To add a Virtual Machine class (the name entered will become the label
358 that will be used to identify the class):
359 - Enter the name of a new class under the Virtual Machine Classes section
360 in the entry field above the "New" button.
361 - Click the "New" button and the class will be added to the table of defined
362 Virtual Machine classes.
363 - To remove a Virtual Machine class:
364 - Click the "Delete" link associated with the class in the table of Virtual
365 Machine classes.
367 Once you have defined one or more Virtual Machine classes, you will be able to
368 add any of the defined Simple Type Enforcement types or Chinese Wall types to a
369 particular Virtual Machine.
371 You must also define which Virtual Machine class is to be associated with the
372 bootstrap domain (or Dom0 domain). By default, the first Virtual Machine class
373 created will be associated as the bootstrap domain.
375 To create your label template definition file, click on the "Generate XML" button
376 on the top of the page. This will present you with a dialog box to save the
377 generated XML file on your system. The default name will be
378 security_label_template.xml which you should change to follow the policy file
379 naming conventions based on the policy name that you choose to use.
381 To get a feel for the tool, you could use one of the example policy definition
382 and label template definition files from /etc/xen/acm-security/policies as input.