view tools/security/example.txt @ 11330:3e54734e55f3

[IA64] Remove extraneous verbose output to clean up Fedora boot.

Signed-off-by: Aron Griffis <>
date Wed Aug 23 13:26:46 2006 -0600 (2006-08-23)
parents c7b9b8a64755
line source
1 ##
2 # example.txt <description to the xen access control architecture>
3 #
4 # Author:
5 # Reiner Sailer 08/15/2005 <>
6 # 04/07/2006 update to using labels instead of ssidref
7 #
8 #
9 # This file introduces into the tools to manage policies
10 # and to label domains and resources.
11 ##
13 We will show how to install and use the example one of the client_v1
14 policies. Other policies work similarly. Feedback welcome!
18 1. Using xm tools to translate example.chwall_ste.client_v1 policy:
19 ===================================================================
21 #xm makepolicy example.chwall_ste.client_v1
23 By default, the tool looks in directory /etc/xen/acm-security/policies
24 for a directory that matches the policy name
25 (here:example/chwall_ste/client_v1-security_policy.xml) to find the
26 policy files. The '-d' option can be used to override the default
27 /etc/xen/acm-security/policies policy-root directory.
29 The default policy directory structure under /etc/xen/acm-security (and
30 the Xen security tool build directory - tools/security) looks like:
32 policies
33 |-- security_policy.xsd
34 |-- example
35 |-- chwall
36 | |-- client_v1-security_policy.xml
37 |
38 |-- chwall_ste
39 | |-- client_v1-security_policy.xml
40 |
41 |-- ste
42 |-- client_v1-security_policy.xml
44 The security_policy.xsd file contains the schema against which the
45 policy files must validate during translation.
47 The policy files, ending in -security_policy.xml, define the policies,
48 the types known to the policies, and the label definitions that group
49 types together and make them easier to use for users.
51 After executing the above 'xm makepolicy' command, you will find 2 new
52 files in the /etc/xen/acm-security/policies/example/chwall_ste
53 sub-directory:
55 ... this file includes the mapping
56 of names from the xml files into their binary code representation.
58 client_v1.bin ... this is the binary policy file, the result of
59 parsing the xml files and using the mapping to create a binary
60 version that can be loaded into the hypervisor.
64 2. Loading and activating the policy:
65 =====================================
67 We assume that xen is already configured for security;
68 please refer to install.txt for instructions.
70 To activate the policy from the command line:
72 # xm loadpolicy example.chwall_ste.client_v1
74 See install.txt for how to install a policy at boot time. This the
75 recommended default. You can only load a policy if the currently
76 enforced policy is "DEFAULT", a minimal startup policy, or if the
77 currently enforced policy has the same name as the new one. Support
78 for dynamic policy changes at run-time are a current working item.
81 3. Labeling domains:
82 ====================
84 a) Labeling Domain0:
86 The chwall_ste-security_label_template.xml file includes an attribute
87 "bootstrap", which is set to the label name that will be assigned to
88 Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).
90 b) Labeling User Domains (domains started from dom0 using xm commands):
92 We distinguish two kinds of labels: a) VM labels (for domains) and RES
93 Labels (for resources). We focus here on VM labels. Resource labels
94 will be supported later.
96 To list all available domain labels of a policy, use:
97 #xm labels example.chwall_ste.client_v1
99 To list all available labels including resource labels (their support
100 is current work), use:
102 #xm labels example.chwall_ste.client_v1 type=any
104 The policy parameter is optional. The currently enforced hypervisor
105 policy is used by default.
107 If you would like to assign the dom_HomeBanking label to one of your user domains,
108 look at the hypothetical domain configuration contained in /etc/xen/homebanking.xm:
110 #------FOR HOME/ONLINE BANKING---------
111 kernel = "/boot/vmlinuz-2.6.16-xen"
112 ramdisk="/boot/U1_ramdisk.img"
113 memory = 164
114 name = "homebanking"
115 vif=['']
116 dhcp = "dhcp"
117 #-------------------------
119 Now we label this domain (policy name is optional, see above):
121 # xm addlabel homebanking.xm dom_HomeBanking example.chwall_ste.client_v1
123 The domain configuration should look now like:
125 # cat homebanking.xm
126 #------FOR HOME/ONLINE BANKING---------
127 kernel = "/boot/vmlinuz-2.6.16-xen"
128 ramdisk="/boot/U1_ramdisk.img"
129 memory = 164
130 name = "homebanking"
131 vif=['']
132 dhcp = "dhcp"
133 access_control = ['policy=example.chwall_ste.client_v1, label=dom_HomeBanking']
135 You can see the access_control line that was added to the
136 configuration. This label will be translated into a local ssidref when
137 a domain is created or resumed (also after migration and
138 live-migration). The ssidref is a local security reference that is
139 used inside the hypervisor instead of the security label for
140 efficiency reasons. Since the same label can be mapped onto different
141 ssidrefs in different policy translations (e.g., if the position of
142 the label definition is changed in the policy file) or on different
143 systems, the ssidref is re-calculated from the label each time a
144 domain is instantiated or re-instantiated.
146 Currently, the labels are not held in the hypervisor but only in
147 .map files in the /etc/xen/acm-security/policies subdirectories. Only
148 ssidrefs are known inside the hypervisr. This of course can change in
149 the future.
152 4. Starting a labeled domain
153 ============================
155 Now, start the domain:
157 #xm create homebanking.xm
158 Using config file "homebanking.xm".
159 Started domain fun
162 [root@941e-4 VMconfigs]# xm list --label
164 Name ID Mem(MiB) VCPUs State Time(s) Label
165 fun 1 64 1 -b---- 5.9 dom_HomeBanking
166 Domain-0 0 1954 1 r----- 1321.4 dom_SystemManagement
170 If you label another domain configuration as dom_Fun and if
171 you try to start it afterwards, this create will fail.
173 Why? -- Because the running 'homebanking' domain has the chinese
174 wall type "cw_Sensitive". The new domain 'fun' has the chinese wall
175 label "cw_Distrusted". These domains are not allowed to run simultaneously
176 on the same system because of the defined conflict set
178 <conflictset name="Protection1">
179 <type>cw_Sensitive</type>
180 <type>cw_Distrusted</type>
181 </conflictset>
183 (in client_v1-security_policy.xml), which says that only one of the
184 types cw_Sensitive and cw_Distrusted can run at a time.
186 If you save or shutdown the 'homebanking' domain, you will be able to
187 start the 'fun' domain. You can look into the Xen log to see if a
188 domain was denied to start because of the access control framework
189 with the command 'xm dmesg'.
191 It is important (and usually non-trivial) to define the labels in a
192 way that the semantics of the labels are enforced and supported by the
193 types and the conflict sets. Usually, a workload abstraction seems
194 helpful on the hypervisor level.
196 Note: While the chinese wall policy enforcement is complete, the type
197 enforcement is currently enforced inside the Xen hypervisor
198 only. Therefore, only point-to-point sharing with regard to the type
199 enforcement is currently controlled. Enforcing the STE policy while
200 sharing virtual resources is ongoing work and assumed to be complete
201 by year end as well as enforcing the STE policy for network traffic
202 routed through dom0.
205 5. Adding your own policies
206 ===========================
208 Writing your own policy (e.g. "mypolicy.chwall.test") requires the policy
209 definition (types etc.) and the label definitions. Any policy name
210 must have chwall, ste, or chwall_ste in its name. This is used by the
211 configuration tool to identify existing binary policy entries in the
212 boot configuration file (menu.lst, grub.con). This part should, of
213 course, be consistent with policy type that is defined.
215 First, you create
216 /etc/xen/acm-security/policies/mypolicy/chwall/test-security_policy.xml.
218 You need to keep to the schema as defined in
219 /etc/xen/acm-security/security_policy.xsd since the translation tools
220 are written against this schema.
222 You can hand-edit the xml files to create your policy or you can use the
223 xensec_gen utility.
226 6. Generating policy files using xensec_gen:
227 ============================================
229 The xensec_gen utility starts a web-server that can be used to generate the
230 XML policy files needed to create a policy.
232 By default, xensec_gen runs as a daemon and listens on port 7777 for HTTP
233 requests. The xensec_gen command supports command line options to change the
234 listen port, run in the foreground, and a few others. Type 'xensec_gen -h'
235 to see the full list of options available.
237 Once the xensec_gen utility is running, point a browser at the host and port
238 on which the utility is running (e.g. http://localhost:7777/). You will be
239 presented with a web page that allows you to create or modify the XML policy
240 file:
242 - The Security Policy types section allows you to create or modify
243 the policy types and conflict set definitions
245 - The Security Policy Labeling section allows you to create or modify a
246 label definitions
248 The policy generation tool allows you to modify an existing policy
249 definition or create a new policy definition file. To modify an
250 existing policy definition, enter the full path to the existing file
251 (the "Browse" button can be used to aid in this) in the Policy File
252 entry field. To create a new policy definition file leave the Policy
253 File entry field blank. At this point click the "Create" button to
254 begin modifying or creating your policy definition.
256 Security Policy Types Section
257 -----------------------------
259 You will then be presented with a web page. The upper part of it will
260 allow you to create either Simple Type Enforcement types or Chinese
261 Wall types or both, as well as Chinese Wall conflict type sets.
263 As an example:
264 - To add a Simple Type Enforcement type:
265 - Enter the name of a new type under the Simple Type Enforcement Types
266 section in the entry field above the "New" button.
267 - Click the "New" button and the type will be added to the list of defined
268 Simple Type Enforcement types.
269 - To remove a Simple Type Enforcement type:
270 - Click on the type to be removed in the list of defined Simple Type
271 Enforcement types.
272 - Click the "Delete" button to remove the type.
274 Follow the same process to add Chinese Wall types. If you define Chinese Wall
275 types you need to define at least one Chinese Wall Conflict Set. The Chinese
276 Wall Conflict Set will allow you to add Chinese Wall types from the list of
277 defined Chinese Wall types.
279 Security Policy Labeling:
280 -------------------------
282 The security policy label section of the web page allows you to create labels
283 for classes of virtual machines. The input policy type definitions on the upper
284 part of the web page will provide the available types (Simple Type Enforcement
285 and/or Chinese Wall) that can be assigned to a virtual machine class.
287 As an example:
288 - To add a Virtual Machine class (the name entered will become the label
289 that will be used to identify the class):
290 - Enter the name of a new class under the Virtual Machine Classes section
291 in the entry field above the "New" button.
292 - Click the "New" button and the class will be added to the table of defined
293 Virtual Machine classes.
294 - To remove a Virtual Machine class:
295 - Click the "Delete" link associated with the class in the table of Virtual
296 Machine classes.
298 Once you have defined one or more Virtual Machine classes, you will be able to
299 add any of the defined Simple Type Enforcement types or Chinese Wall types to a
300 particular Virtual Machine.
302 You must also define which Virtual Machine class is to be associated with the
303 bootstrap domain (or Dom0 domain). By default, the first Virtual Machine class
304 created will be associated as the bootstrap domain.
306 To save your policy definition file, click on the "Generate XML" button
307 on the top of the page. This will present you with a dialog box to save the
308 generated XML file on your system. The default name will be
309 security_policy.xml which you should change to follow the policy file
310 naming conventions based on the policy name that you choose to use.
312 To get a feel for the tool, you could use one of the example policy definitions
313 files from /etc/xen/acm-security/policies/example as input.
316 7. Hypervisor - OS Security Interface
317 =====================================
319 We currently provide 2 hypercalls through which user operating systems
320 can interact with the hypervisor Access Control Module. Examples of
321 using them are under "xen_root"/tools/security/python/xensec_tools:
324 I) acm_getdecision -i domainid -l labelname
325 Call this example script without arguments to show its usage
326 information.
328 This script enables a domain to retrieve an access control decision
329 regarding the STE policy from the hypervisor. It will be used to
330 control access to virtual/real resources in hosting domains.
332 The script can be provided with any combination of domain ids or
333 labelnames. Before calling into the hypervisor, labels are translated
334 into ssidrefs. The hypervisor then retrieves for any domain id
335 paramter the ssidref before deciding access.
337 Example:
338 #/etc/xen/acm-security/scripts/acm_getdecision -l dom_Fun
339 -l dom_SystemManagement
342 #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -i 1
345 #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l dom_Fun
348 #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l no_label
349 ACMError: Label 'nolabel' not found.
351 Now, assume domain 123454 does not exist:
352 #/etc/xen/acm-security/scripts/acm_getdecision -i 123454 -l dom_Fun
353 ACMError: Cannot determine decision (Invalid parameter).
355 Return values:
356 * DENIED: access is denied based on the current hypervisor
357 policy
359 * PERMITTED: access is permitted based on the current
361 * Exception ACMError: one of the parameters was illegal,
362 i.e. an unknown label or a
363 non-existing domain id
365 I) acm_getlabel -i domainid
366 Retrieves the label of a runing domain. This function can be used
367 by domains to determine their own label or (if authorized) the label
368 other domains.
370 Example (result is broken up into different lines to simplify description):
371 # /etc/xen/acm-security/scripts/acm_getlabel -i 0
372 ('example.chwall.client_v1', <--- policy describing labels etc.
373 'dom_SystemManagement', <--- label name of the domain
374 'CHINESE WALL', <--- policy type
375 65537) <--- hypervisor internal ssidref