ia64/xen-unstable

view docs/misc/shype4xen_readme.txt @ 6191:430ce2bade9b

Trivial fixes for a couple of xenlinux compile warnings.

Signed-off-by: <andrew.warfield@cl.cam.ac.uk>
author akw27@arcadians.cl.cam.ac.uk
date Mon Aug 15 13:50:39 2005 +0000 (2005-08-15)
parents f294acb25858
children e3d811cca4e1 1ae656509f02 23979fb12c49 84ee014ebd41 99914b54f7bf
line source
1 Copyright: IBM Corporation (C)
2 20 June 2005
3 Author: Reiner Sailer
5 This document is a very short introduction into the sHype access control
6 security architecture implementation and how it is perceived by users. It
7 is a very preliminary draft for the courageous ones to get "their feet wet"
8 and to be able to give feedback (via the xen-devel/xense-devel mailing lists).
10 Install:
12 cd into xeno-unstable.bk
13 (use --dry-run option if you want to test the patch only)
14 patch -p1 -g0 < *tools.diff
15 patch -p1 -g0 < *xen.diff
17 (no rejects, probably some line offsets)
19 make uninstall; make mrproper; make; ./install.sh should install the default
20 sHype into Xen (rebuild your initrd images if necessary). Reboot.
22 Debug output: there are two triggers for debug output:
23 a) General sHype debug:
24 xeno-unstable.bk/xen/include/public/acm.h
25 undefine ACM_DEBUG to switch this debug off
27 b) sHype enforcement hook trace: This prints a small trace for each enforcement
28 hook that is executed. The trigger is in
29 xeno-unstable.bk/xen/include/acm/acm_hooks.h
30 undefine ACM_TRACE_MODE to switch this debug off
32 1. The default NULL policy
33 ***************************
34 When you apply the patches and startup xen, you should at first not notice any
35 difference because the default policy is the "NULL" policy, which as the name
36 implies does not enforce anything.
38 To display the currently enforced policy, use the policy tool under xeno-
39 unstable.bk/tools/policy: policy_tool getpolicy. You should see output like the
40 one below.
42 [root@laptop policy]#./policy_tool getpolicy
44 Policy dump:
45 ============
46 Magic = 1debc.
47 PolVer = aaaa0000.
48 Len = 14.
49 Primary = NULL policy (c=0, off=14).
50 Secondary = NULL policy (c=0, off=14).
51 No primary policy (NULL).
52 No secondary policy (NULL).
54 Policy dump End.
56 Since this is a dump of a binary policy, it's not pretty. The important parts
57 are the "Primary" and "Secondary" policy fields set to "NULL policy". sHype
58 currently allows to set two independent policies; thus the two SSID-REF parts
59 shown in 'xm list'. Right here: primary policy only means this policy is
60 checked first, the secondary policy is checked if the primary results in
61 "permitted access". The result of the combined policy is "permitted" if both
62 policies return permitted (NULL policy always returns permitted). The result is
63 "denied" if at least one of the policies returns "denied". Look into xeno-
64 unstable.bk/xen/include/acm/acm_hooks.h for the general hook structure
65 integrating the policy decisions (if you like, you won't need it for the rest
66 of the Readme file).
68 2. Setting Chinese Wall and Simple Type Enforcement policies:
69 *************************************************************
71 We'll get fast to the point. However, in order to understand what we are doing,
72 we must at least understand the purpose of the policies that we are going to
73 enforce. The two policies presented here are just examples and the
74 implementation encourages adding new policies easily.
76 2.1. Chinese Wall policy: "decides whether a domain can be started based on
77 this domain's ssidref and the ssidrefs of the currently running domains".
78 Generally, the Chinese wall policy allows specifying certain types (or classes
79 or categories, whatever the preferred word) that conflict; we usually assign a
80 type to a workload and the set of types of those workloads running in a domain
81 make up the type set for this domain. Each domain is assigned a set of types
82 through its SSID-REF (we register Chinese Wall as primary policy, so the
83 ssidref used for determining the Chinese Wall types is the one annotated with
84 "p:" in xm list) since each SSID-REF points at a set of types. We'll see how
85 SSIDREFs are represented in Xen later when we will look at the policy. (A good
86 read for Chinese Wall is: Brewer/Nash The Chinese Wall Security Policy 1989.)
88 So let's assume the Chinese Wall policy we are running distinguishes 10 types:
89 t0 ... t9. Let us assume further that each SSID-REF points to a set that
90 includes exactly one type (attached to domains that run workloads of a single
91 type). SSID-REF 0 points to {t0}, ssidref 1 points to {t1} ... 9 points to
92 {t9}. [This is actually the example policy we are going to push into xen later]
94 Now the Chinese Wall policy allows you to define "Conflict type sets" and it
95 guarantees that of any conflict set at most one type is "running" at any time.
96 As an example, we have defined 2 conflict set: {t2, t3} and {t0, t5, t6}.
97 Specifying these conflict sets, sHype ensures that at most one type of each set
98 is running (either t2 or t3 but not both; either t0 or t5 or t6 but not
99 multiple of them).
101 The effect is that administrators can define which workload types cannot run
102 simultaneously on a single Xen system. This is useful to limit the covert
103 timing channels between such payloads or to ensure that payloads don't
104 interfere with each other through existing resource dependencies.
106 2.2. Simple Type Enforcement (ste) policy: "decides whether two domains can
107 share data, e.g., setup event channels or grant tables to each other, based on
108 the two domains' ssidref. This, as the name says, is a simple policy. Think of
109 each type as of a single color. Each domain has one or more colors, i.e., the
110 domains ssid for the ste policy points to a set that has set one or multiple
111 types. Let us assume in our example policy we differentiate 5 colors (types)
112 and define 5 different ssids referenced by ssidref=0..4. Each ssid shall have
113 exactly one type set, i.e., describes a uni-color. Only ssid(0) has all types
114 set, i.e., has all defined colors.
116 Sharing is enforced by the ste policy by requiring that two domains that want
117 to establish an event channel or grant pages to each other must have a common
118 color. Currently all domains communicate through DOM0 by default; i.e., Domain0
119 will necessarily have all colors to be able to create domains (thus, we will
120 assign ssidref(0) to Domain0 in our example below.
122 More complex mandatory access control policies governing sharing will follow;
123 such policies are more sophisticated than the "color" scheme above by allowing
124 more flexible (and complex :_) access control decisions than "share a color" or
125 "don't share a color" and will be able to express finer-grained policies.
128 2.3 Binary Policy:
129 In the future, we will have a policy tool that takes as input a more humane
130 policy description, using types such as development, home-banking, donated-
131 Grid, CorpA-Payload ... and translates the respective policy into what we see
132 today as the binary policy using 1s and 0s and sets of them. For now, we must
133 live with the binary policy when working with sHype.
136 2.4 Exemplary use of a real sHype policy on Xen. To activate a real policy,
137 edit the file (yes, this will soon be a compile option):
138 xeno-unstable.bk/xen/include/public/acm.h
139 Change: #define ACM_USE_SECURITY_POLICY ACM_NULL_POLICY
140 To : #define ACM_USE_SECURITY_POLICY ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
141 cd xeno-unstable.bk
142 make mrproper
143 make uninstall (manually remove /etc/xen.old if necessary)
144 make
145 ./install.sh (recreate your kernel initrd's if necessary)
146 Reboot into new xen.gz
148 After booting, check out 'xm dmesg'; should show somewhere in the middle:
150 (XEN) acm_init: Enforcing Primary CHINESE WALL policy, Secondary SIMPLE TYPE
151 ENFORCEMENT policy.
153 Even though you can activate those policies in any combination and also
154 independently, the policy tool currently only supports setting the policy for
155 the above combination.
157 Now look at the minimal startup policy with:
158 xeno-unstable.bk/tools/policytool getpolicy
160 You should see something like:
162 [root@laptop policy]# ./policy_tool getpolicy
164 Policy dump:
165 ============
166 Magic = 1debc.
167 PolVer = aaaa0000.
168 Len = 36.
169 Primary = CHINESE WALL policy (c=1, off=14).
170 Secondary = SIMPLE TYPE ENFORCEMENT policy (c=2, off=2c).
173 Chinese Wall policy:
174 ====================
175 Max Types = 1.
176 Max Ssidrefs = 1.
177 Max ConfSets = 1.
178 Ssidrefs Off = 10.
179 Conflicts Off = 12.
180 Runing T. Off = 14.
181 C. Agg. Off = 16.
183 SSID To CHWALL-Type matrix:
185 ssidref 0: 00
187 Confict Sets:
189 c-set 0: 00
191 Running
192 Types: 00
194 Conflict
195 Aggregate Set: 00
198 Simple Type Enforcement policy:
199 ===============================
200 Max Types = 1.
201 Max Ssidrefs = 1.
202 Ssidrefs Off = 8.
204 SSID To STE-Type matrix:
206 ssidref 0: 01
209 Policy dump End.
211 This is a minimal policy (of little use), except it will disable starting any
212 domain that does not have ssidref set to 0x0. The Chinese Wall policy has
213 nothing to enforce and the ste policy only knows one type, which is set for the
214 only defined ssidref.
216 The item that defines the ssidref in a domain configuration is:
218 ssidref = 0x12345678
220 Where ssidref is interpreted as a 32bit number, where the lower 16bits become
221 the ssidref for the primary policy and the higher 16bits become the ssidref for
222 the secondary policy. sHype currently supports two policies but this is an
223 implementation decision and can be extended if necessary.
225 This reference defines the security information of a domain. The meaning of the
226 SSID-REF depends on the policy, so we explain it when we explain the real
227 policies.
230 Setting a new Security Policy:
231 ******************************
232 The policy tool with all its current limitations has one usable example policy
233 compiled-in. Please try at this time to use the setpolicy command:
234 xeno-unstable.bk/tools/policy/policy_tool setpolicy
236 You should see a dump of the policy you are setting. It should say at the very
237 end:
239 Policy successfully set.
241 Now try to dump the currently enforced policy, which is the policy we have just
242 set and the dynamic security state information of this policy
243 (<<< ... some additional explanations)
245 [root@laptop policy]# ./policy_tool getpolicy
247 Policy dump:
248 ============
249 Magic = 1debc.
250 PolVer = aaaa0000.
251 Len = 112.
252 Primary = CHINESE WALL policy (c=1, off=14).
253 Secondary = SIMPLE TYPE ENFORCEMENT policy (c=2, off=d8).
256 Chinese Wall policy:
257 ====================
258 Max Types = a.
259 Max Ssidrefs = 5.
260 Max ConfSets = 2.
261 Ssidrefs Off = 10.
262 Conflicts Off = 74.
263 Runing T. Off = 9c.
264 C. Agg. Off = b0.
266 SSID To CHWALL-Type matrix:
268 ssidref 0: 01 00 00 00 00 00 00 00 00 00 <<< type0 is set for ssidref0
269 ssidref 1: 00 01 00 00 00 00 00 00 00 00
270 ssidref 2: 00 00 01 00 00 00 00 00 00 00
271 ssidref 3: 00 00 00 01 00 00 00 00 00 00
272 ssidref 4: 00 00 00 00 01 00 00 00 00 00 <<< type4 is set for ssidref4
273 <<< types 5-9 are unused
274 Confict Sets:
276 c-set 0: 00 00 01 01 00 00 00 00 00 00 <<< type2 and type3 never run together
277 c-set 1: 01 00 00 00 00 01 01 00 00 00 <<< only one of types 0, 5 or 6
278 <<< can run simultaneously
279 Running
280 Types: 01 00 00 00 00 00 00 00 00 00 <<< ref-count for types of running domains
282 Conflict
283 Aggregate Set: 00 00 00 00 00 01 01 00 00 00 <<< aggregated set of types that
284 <<< cannot run because they
285 <<< are in conflict set 1 and
286 <<< (domain 0 is running w t0)
289 Simple Type Enforcement policy:
290 ===============================
291 Max Types = 5.
292 Max Ssidrefs = 5.
293 Ssidrefs Off = 8.
295 SSID To STE-Type matrix:
297 ssidref 0: 01 01 01 01 01 <<< ssidref0 points to a set that
298 <<< has all types set (colors)
299 ssidref 1: 00 01 00 00 00 <<< ssidref1 has color1 set
300 ssidref 2: 00 00 01 00 00 <<< ...
301 ssidref 3: 00 00 00 01 00
302 ssidref 4: 00 00 00 00 01
305 Policy dump End.
308 This is a small example policy with which we will demonstrate the enforcement.
310 Starting Domains with policy enforcement
311 ========================================
312 Now let us play with this policy.
314 Define 3 or 4 domain configurations. I use the following config using a ramdisk
315 only and about 8MBytes of memory for each DomU (test purposes):
317 #-------configuration xmsec1-------------------------
318 kernel = "/boot/vmlinuz-2.6.11-xenU"
319 ramdisk="/boot/U1_ramdisk.img"
320 #security reference identifier
321 ssidref= 0x00010001
322 memory = 10
323 name = "xmsec1"
324 cpu = -1 # leave to Xen to pick
325 # Number of network interfaces. Default is 1.
326 nics=1
327 dhcp="dhcp"
328 #-----------------------------------------------------
330 xmsec2 and xmsec3 look the same except for the name and the ssidref line. Use
331 your domain config file and add "ssidref = 0x00010001" to the first (xmsec1),
332 "ssidref= 0x00020002" to the second (call it xmsec2), and "ssidref=0x00030003"
333 to the third (we will call this one xmsec3).
335 First start xmsec1: xm create -c xmsec1 (succeeds)
337 Then
338 [root@laptop policy]# xm list
339 Name Id Mem(MB) CPU State Time(s) Console
340 Domain-0 0 620 0 r---- 42.3 s:00/p:00
341 xmnosec 1 9 0 -b--- 0.3 9601 s:00/p:05
342 xmsec1 2 9 0 -b--- 0.2 9602 s:01/p:01
344 Shows a new domain xmsec1 running with primary (here: chinese wall) ssidref 1
345 and secondary (here: simple type enforcement) ssidref 1. The ssidrefs are
346 independent and can differ for a domain.
348 [root@laptop policy]# ./policy_tool getpolicy
350 Policy dump:
351 ============
352 Magic = 1debc.
353 PolVer = aaaa0000.
354 Len = 112.
355 Primary = CHINESE WALL policy (c=1, off=14).
356 Secondary = SIMPLE TYPE ENFORCEMENT policy (c=2, off=d8).
359 Chinese Wall policy:
360 ====================
361 Max Types = a.
362 Max Ssidrefs = 5.
363 Max ConfSets = 2.
364 Ssidrefs Off = 10.
365 Conflicts Off = 74.
366 Runing T. Off = 9c.
367 C. Agg. Off = b0.
369 SSID To CHWALL-Type matrix:
371 ssidref 0: 01 00 00 00 00 00 00 00 00 00
372 ssidref 1: 00 01 00 00 00 00 00 00 00 00
373 ssidref 2: 00 00 01 00 00 00 00 00 00 00
374 ssidref 3: 00 00 00 01 00 00 00 00 00 00
375 ssidref 4: 00 00 00 00 01 00 00 00 00 00
377 Confict Sets:
379 c-set 0: 00 00 01 01 00 00 00 00 00 00
380 c-set 1: 01 00 00 00 00 01 01 00 00 00 <<< t1 is not part of any c-set
382 Running
383 Types: 01 01 00 00 00 00 00 00 00 00 <<< xmsec1 has ssidref 1->type1
384 ^^ <<< ref-count at position 1 incr
385 Conflict
386 Aggregate Set: 00 00 00 00 00 01 01 00 00 00 <<< domain 1 was allowed to
387 <<< start since type 1 was not
388 <<< in conflict with running
389 <<< types
391 Simple Type Enforcement policy:
392 ===============================
393 Max Types = 5.
394 Max Ssidrefs = 5.
395 Ssidrefs Off = 8.
397 SSID To STE-Type matrix:
399 ssidref 0: 01 01 01 01 01 <<< the ste policy does not maintain; we
400 ssidref 1: 00 01 00 00 00 <-- <<< see that domain xmsec1 has ste
401 ssidref 2: 00 00 01 00 00 <<< ssidref1->type1 and has this type in
402 ssidref 3: 00 00 00 01 00 <<< common with dom0
403 ssidref 4: 00 00 00 00 01
406 Policy dump End.
408 Look at sHype output in xen dmesg:
410 [root@laptop xen]# xm dmesg
411 .
412 .
413 [somewhere near the very end]
414 (XEN) chwall_init_domain_ssid: determined chwall_ssidref to 1.
415 (XEN) ste_init_domain_ssid.
416 (XEN) ste_init_domain_ssid: determined ste_ssidref to 1.
417 (XEN) acm_init_domain_ssid: Instantiated individual ssid for domain 0x01.
418 (XEN) chwall_post_domain_create.
419 (XEN) ste_pre_eventchannel_interdomain.
420 (XEN) ste_pre_eventchannel_interdomain: (evtchn 0 --> 1) common type #01.
421 (XEN) shype_authorize_domops.
422 (XEN) ste_pre_eventchannel_interdomain.
423 (XEN) ste_pre_eventchannel_interdomain: (evtchn 0 --> 1) common type #01.
424 (XEN) ste_pre_eventchannel_interdomain.
425 (XEN) ste_pre_eventchannel_interdomain: (evtchn 0 --> 1) common type #01.
428 You can see that the chinese wall policy does not complain and that the ste
429 policy makes three access control decisions for three event-channels setup
430 between domain 0 and the new domain 1. Each time, the two domains share the
431 type1 and setting up the eventchannel is permitted.
434 Starting up a second domain xmsec2:
436 [root@laptop xen]# xm create -c xmsec2
437 Using config file "xmsec2".
438 Started domain xmsec2, console on port 9602
439 ************ REMOTE CONSOLE: CTRL-] TO QUIT ********
440 Linux version 2.6.11-xenU (root@laptop.home.org) (gcc version 3.4.2 20041017
441 (Red Hat 3.4.2-6.fc3)) #1 Wed Mar 30 13:14:31 EST 2005
442 .
443 .
444 .
445 [root@laptop policy]# xm list
446 Name Id Mem(MB) CPU State Time(s) Console
447 Domain-0 0 620 0 r---- 71.7 s:00/p:00
448 xmsec1 1 9 0 -b--- 0.3 9601 s:01/p:01
449 xmsec2 2 7 0 -b--- 0.3 9602 s:02/p:02 << our domain runs both policies with ssidref 2
452 [root@laptop policy]# ./policy_tool getpolicy
454 Policy dump:
455 ============
456 Magic = 1debc.
457 PolVer = aaaa0000.
458 Len = 112.
459 Primary = CHINESE WALL policy (c=1, off=14).
460 Secondary = SIMPLE TYPE ENFORCEMENT policy (c=2, off=d8).
463 Chinese Wall policy:
464 ====================
465 Max Types = a.
466 Max Ssidrefs = 5.
467 Max ConfSets = 2.
468 Ssidrefs Off = 10.
469 Conflicts Off = 74.
470 Runing T. Off = 9c.
471 C. Agg. Off = b0.
473 SSID To CHWALL-Type matrix:
475 ssidref 0: 01 00 00 00 00 00 00 00 00 00
476 ssidref 1: 00 01 00 00 00 00 00 00 00 00
477 ssidref 2: 00 00 01 00 00 00 00 00 00 00 <<< our domain has type 2 set
478 ssidref 3: 00 00 00 01 00 00 00 00 00 00
479 ssidref 4: 00 00 00 00 01 00 00 00 00 00
481 Confict Sets:
483 c-set 0: 00 00 01 01 00 00 00 00 00 00 <<< t2 is in c-set0 with type 3
484 c-set 1: 01 00 00 00 00 01 01 00 00 00
486 Running
487 Types: 01 01 01 00 00 00 00 00 00 00 <<< t2 is running since the
488 ^^ <<< current aggregate conflict
489 <<< set (see above) does not
490 <<< include type 2
491 Conflict
492 Aggregate Set: 00 00 00 01 00 01 01 00 00 00 <<< type 3 is added to the
493 <<< conflict aggregate
496 Simple Type Enforcement policy:
497 ===============================
498 Max Types = 5.
499 Max Ssidrefs = 5.
500 Ssidrefs Off = 8.
502 SSID To STE-Type matrix:
504 ssidref 0: 01 01 01 01 01
505 ssidref 1: 00 01 00 00 00
506 ssidref 2: 00 00 01 00 00
507 ssidref 3: 00 00 00 01 00
508 ssidref 4: 00 00 00 00 01
511 Policy dump End.
514 The sHype xen dmesg output looks similar to the one above when starting the
515 first domain.
517 Now we start xmsec3 and it has ssidref3. Thus, it tries to run as type3 which
518 conflicts with running type2 (from xmsec2). As expected, creating this domain
519 fails for security policy enforcement reasons.
521 [root@laptop xen]# xm create -c xmsec3
522 Using config file "xmsec3".
523 Error: Error creating domain: (22, 'Invalid argument')
524 [root@laptop xen]#
526 [root@laptop xen]# xm dmesg
527 .
528 .
529 [somewhere near the very end]
530 (XEN) chwall_pre_domain_create.
531 (XEN) chwall_pre_domain_create: CHINESE WALL CONFLICT in type 03.
533 xmsec3 ssidref3 points to type3, which is in the current conflict aggregate
534 set. This domain cannot start until domain xmsec2 is destroyed, at which time
535 the aggregate conflict set is reduced and type3 is excluded from it. Then,
536 xmsec3 can start. Of course, afterwards, xmsec2 cannot be restarted. Try it.
538 3. Policy tool
539 **************
540 toos/policy/policy_tool.c
542 a) ./policy_tool getpolicy
543 prints the currently enforced policy
544 (see for example section 1.)
546 b) ./policy_tool setpolicy
547 sets a predefined and hardcoded security
548 policy (the one described in section 2.)
550 c) ./policy_tool dumpstats
551 prints some status information about the caching
552 of access control decisions (number of cache hits
553 and number of policy evaluations for grant_table
554 and event channels).
556 d) ./policy_tool loadpolicy <binary_policy_file>
557 sets the policy defined in the <binary_policy_file>
558 please use the policy_processor that is posted to this
559 mailing list to create such a binary policy from an XML
560 policy description
562 4. Policy interface:
563 ********************
564 The Policy interface is working in "network-byte-order" (big endian). The reason for this
565 is that policy files/management should be portable and independent of the platforms.
567 Our policy interface enables managers to create a single binary policy file in a trusted
568 environment and distributed it to multiple systems for enforcement.
570 5. Booting with a binary policy:
571 ********************************
572 The grub configuration file can be adapted to boot the hypervisor with an
573 already active policy. To do this, a binary policy file - this can be
574 the same file as used by the policy_tool - should be placed into the boot
575 partition. The following entry from the grub configuration file shows how
576 a binary policy can be added to the system during boot time. Note that the
577 binary policy must be of the same type that the hypervisor was compiled
578 for. The policy module line should also only be added as the last module
579 line if XEN was compiled with the access control module (ACM).
581 title XEN0 3.0 Devel
582 kernel /xen.gz dom0_mem=400000
583 module /vmlinuz-2.6.12-xen0 root=/dev/hda2 ro console=tty0
584 module /initrd-2.6.12-xen0.img
585 module /xen_sample_policy.bin
588 ====================end-of file=======================================