This patch updates the documentation and extends the 'xm' man page with

the integrated access control management commands. The man page is a 
good place to start exploring these commands.

Signed-off by: Reiner Sailer <sailer@us.ibm.com>

5 files changed, 575 insertions, 277 deletions

diff --git a/docs/man/xm.pod.1 b/docs/man/xm.pod.1
index d6e3697abe..11456687ff 100644
--- a/docs/man/xm.pod.1
+++ b/docs/man/xm.pod.1
@@ -136,7 +136,7 @@ Displays the short help message (i.e. common commands).
 The I<--long> option prints out the complete set of B<xm> subcommands,
 grouped by function.
 
-=item B<list> I<[--long]> I<[domain-id, ...]>
+=item B<list> I<[--long | --label]> I<[domain-id, ...]>
 
 Prints information about one or more domains.  If no domains are
 specified it prints out information about all domains.
@@ -213,6 +213,18 @@ Use at your own risk.
 
 =back
 
+B<LABEL OUTPUT>
+
+=over 4
+
+If I<--label> is specified, the security labels are added to the
+output of xm list and the lines are sorted by the labels (ignoring
+case). The I<--long> option prints the labels by default and cannot be
+combined with I<--label>. See the ACCESS CONTROL SUBCOMMAND section of
+this man page for more information about labels.
+
+==back
+
 B<NOTES>
 
 =over 4
@@ -775,6 +787,262 @@ Delete a vnet.
 
 =back
 
+=head1 ACCESS CONTROL SUBCOMMANDS
+
+Access Control in Xen consists of two components: (i) The Access
+Control Policy (ACP) defines security labels and access rules based on
+these labels. (ii) The Access Control Module (ACM) makes access control
+decisions by interpreting the policy when domains require to
+communicate or to access resources. The Xen access control has
+sufficient mechanisms in place to enforce the access decisions even
+against maliciously acting user domains (mandatory access control).
+
+Access rights for domains in Xen are determined by the domain security
+label only and not based on the domain Name or ID. The ACP specifies
+security labels that can then be assigned to domains and
+resources. Every domain must be assigned exactly one security label,
+otherwise access control decisions could become indeterministic. ACPs
+are distinguished by their name, which is a parameter to most of the
+subcommands described below. Currently, the ACP specifies two ways to
+interpret labels:
+
+(1) Simple Type Enforcement: Labels are interpreted to decide access
+of domains to comunication means and virtual or physical
+resources. Communication between domains as well as access to
+resources are forbidden by default and can only take place if they are
+explicitly allowed by the security policy. The proper assignment of
+labels to domains controls the sharing of information (directly
+through communication or indirectly through shared resources) between
+domains. This interpretation allows to control the overt (intended)
+communication channels in Xen.
+
+(2) Chinese Wall: Labels are interpreted to decide which domains can
+co-exist (be run simultaneously) on the same system. This
+interpretation allows to prevent direct covert (unintended) channels
+and mitigates risks caused by imperfect core domain isolation
+(trade-off between security and other system requirements). For a
+short introduction to covert channels, please refer to
+http://www.multicians.org/timing-chn.html.
+
+The following subcommands help you to manage security policies in Xen
+and to assign security labels to domains. To enable access control
+security in Xen, you must compile Xen with ACM support enabled as
+described under "Configuring Security" below. There, you will find
+also examples of each subcommand described here.
+
+=item B<makepolicy> I<policy>
+
+Compiles the XML source representation of the security I<policy>. It
+creates a mapping (.map) as well as a binary (.bin) version of the
+policy. The compiled policy can be loaded into Xen with the
+B<loadpolicy> subcommand or can be configured to be loaded at boot
+time with the B<cfgbootpolicy> subcommand.
+
+=over 4
+
+I<policy> is a dot-separated list of names. The last part is the file
+name pre-fix for the policy xml file. The preceding name parts are
+translated into the local path pointing to the policy xml file
+relative to the global policy root directory
+(/etc/xen/acm-security/policies). For example,
+example.chwall_ste.client_v1 denotes the policy file
+example/chwall_ste/client_v1-security_policy.xml relative to the
+global policy root directory.
+
+=back
+
+=item B<loadpolicy> I<policy>
+
+Loads the binary representation of the I<policy> into Xen. The binary
+representation can be created with the B<makepolicy> subcommand.
+
+=item B<cfgbootpolicy> I<policy> [I<kernelversion>]
+
+Configures I<policy> as the boot policy for Xen. It copies the binary
+policy representation into the /boot directory and adds a module line
+specifying the binary policy to the /boot/grub/menu.lst file. If your
+boot configuration includes multiple Xen boot titles, then use the
+I<kernelversion> parameter to select the proper title.
+
+=item B<dumppolicy>
+
+Prints the current security policy state information of Xen.
+
+=item B<labels> [I<policy>] [I<type>=dom|res|any]
+
+Lists all labels of a I<type> (domain, resource, or both) that are
+defined in the I<policy>. Unless specified, the default I<policy> is
+the currently enforced access control policy. The default for I<type>
+is 'dom'. The labels are arranged in alphabetical order.
+
+=item B<addlabel> I<configfile> I<label> [I<policy>]
+
+Adds the security label with name I<label> to a domain
+I<configfile>. Unless specified, the default I<policy> is the
+currently enforced access control policy. This subcommand also
+verifies that the I<policy> definition supports the specified I<label>
+name.
+
+B<CONFIGURING SECURITY>
+
+=over 4
+
+In xen_source_dir/Config.mk set the following parameters:
+
+    ACM_SECURITY ?= y
+    ACM_DEFAULT_SECURITY_POLICY ?= \
+        ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
+
+Then recompile and install xen and the security tools and then reboot:
+
+    cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
+    cd xen_source_dir/tools/security; make install;
+    reboot into xen
+
+=back
+
+B<COMPILING A SECURITY POLICY>
+
+=over 4
+
+This step creates client_v1.map and client_v1.bin files in
+/etc/xen/acm-security/policies/example/chwall_ste.
+
+    xm makepolicy example.chwall_ste.client_v1
+
+=back
+
+B<LOADING A SECURITY POLICY>
+
+=over 4
+
+This step activates client_v1.bin as new security policy in Xen. You
+can use the dumppolicy subcommand before and afterwards to see the
+change in the Xen policy state.
+
+    xm loadpolicy example.chwall_ste.client_v1
+
+=back
+
+B<CONFIGURING A BOOT SECURITY POLICY>
+
+=over 4
+
+This configures the boot loader to load client_v1.bin at boot
+time. During system start, the ACM configures Xen with this policy and
+Xen enforces this policy from then on.
+
+    xm cfgbootpolicy example.chwall_ste.client_v1
+
+=back
+
+B<LISTING SECURITY LABELS>
+
+=over 4
+
+This subcommand shows all labels that are defined and which can be
+attached to domains.
+
+    xm labels example.chwall_ste.client_v1 type=dom
+
+will print for our example policy:
+
+        dom_BoincClient
+        dom_Fun
+        dom_HomeBanking
+        dom_NetworkDomain
+        dom_StorageDomain
+        dom_SystemManagement
+
+=back
+
+B<ATTACHING A SECURITY LABEL TO A DOMAIN>
+
+=over 4
+
+This subcommand attaches a security label to a domain configuration
+file, here a HomeBanking label. The example policy ensures that this
+domain does not share information with other non-hombanking user
+domains (i.e., domains labeled as dom_Fun or dom_Boinc) and that it
+will not run simultaneously with domains labeled as dom_Fun.
+
+We assume that the specified myconfig.xm configuration file actually
+instantiates a domain that runs workloads related to home-banking,
+probably just a browser environment for online-banking.
+
+    xm addlabel myconfig.xm dom_HomeBanking
+
+The very simple configuration file might now look as printed
+below. The I<addlabel> subcommand added the B<access_control> entry at
+the end of the file, consisting of a label name and the policy that
+specifies this label name:
+
+    kernel = "/boot/vmlinuz-2.6.16-xen"
+    ramdisk="/boot/U1_home_banking_ramdisk.img"
+    memory = 164
+    name = "homebanking"
+    vif = [ '' ]
+    dhcp = "dhcp"
+    access_control = ['policy=example.chwall_ste.client_v1,
+                       label=dom_HomeBanking']
+
+Security labels must be assigned to domain configurations because
+these labels are essential for making access control decisions as
+early as during the configuration phase of a newly instantiated
+domain. Consequently, a security-enabled Xen hypervisor will only
+start domains that have a security label configured and whose security
+label is consistent with the currently enforced policy. Otherwise,
+starting the domain will fail with the error condition "operation not
+permitted".
+
+=back
+
+B<STARTING AND LISTING LABELED DOMAINS>
+
+=over 4
+
+    xm create myconfig.xm
+
+    xm list --label
+
+      Name         ID ...  Time(s)  Label
+      homebanking  23 ...      4.4  dom_HomeBanking
+      Domain-0      0 ...   2658.8  dom_SystemManagement
+
+=back
+
+B<POLICY REPRESENTATIONS>
+
+=over 4
+
+We distinguish three representations of the Xen access control policy:
+the I<source XML> version, its I<binary> counterpart, and a I<mapping>
+representation that enables the tools to deterministically translate
+back and forth between label names of the XML policy and label
+identifiers of the binary policy. All three versions must be kept
+consistent to achieve predictable security guarantees.
+
+The XML version is the version that users are supposed to create or
+change, either by manually editing the XML file or by using the Xen
+policy generation tool (B<xensec_gen>). After changing the XML file,
+run the B<makepolicy> subcommand to ensure that these changes are
+reflected in the other versions. Use, for example, the subcommand
+B<cfgbootpolicy> to activate the changes during the next system
+reboot.
+
+The binary version of the policy is derived from the XML policy by
+tokenizing the specified labels and is used inside Xen only. It is
+created with the B<makepolicy> subcommand. Essentially, the binary
+version is much more compact than the XML version and is easier to
+evaluate during access control decisions.
+
+The mapping version of the policy is created during the XML-to-binary
+policy translation (B<makepolicy>) and is used by the Xen management
+tools to translate between label names used as input to the tools and
+their binary identifiers (ssidrefs) used inside Xen.
+
+=back
+
 =head1 EXAMPLES
 
 =head1 SEE ALSO
@@ -791,5 +1059,6 @@ Operating Systems Review, pages 261-267
 
   Sean Dague <sean at dague dot net>
   Daniel Stekloff <dsteklof at us dot ibm dot com>
+  Reiner Sailer <sailer at us dot ibm dot com>
 
 =head1 BUGS
diff --git a/tools/security/example.txt b/tools/security/example.txt
index 1a6f62e6ca..c9afe88714 100644
--- a/tools/security/example.txt
+++ b/tools/security/example.txt
@@ -3,119 +3,79 @@
 #
 # Author:
 # Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
+#               04/07/2006 update to using labels instead of ssidref
 #
 #
 # This file introduces into the tools to manage policies
 # and to label domains and resources.
 ##
 
-We will show how to install and use the example chwall_ste policy.
-Other policies work similarly. Feedback welcome!
+We will show how to install and use the example one of the client_v1
+policies. Other policies work similarly. Feedback welcome!
 
 
 
-1. Using xensec_xml2bin to translate the chwall_ste policy:
-===========================================================
+1. Using xm tools to translate example.chwall_ste.client_v1 policy:
+===================================================================
 
-#xensec_xml2bin chwall_ste
-
-Successful execution should print:
-
-    [root@laptopxn security]# xensec_xml2bin chwall_ste
-    Validating label file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_label_template.xml...
-    XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
-    Validating policy file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_policy.xml...
-    XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
-    Creating ssid mappings ...
-    Creating label mappings ...
-    Max chwall labels:  7
-    Max chwall-types:   4
-    Max chwall-ssids:   5
-    Max ste labels:     14
-    Max ste-types:      6
-    Max ste-ssids:      10
+#xm makepolicy example.chwall_ste.client_v1
 
 By default, the tool looks in directory /etc/xen/acm-security/policies
-for a directory that matches the policy name (i.e. chwall_ste) to find
-the label and policy files.
-The '-d' option can be used to override the /etc/xen/acm-security/policies
-directory, for example if running the tool in the Xen security tool build
-directory.
+for a directory that matches the policy name
+(here:example/chwall_ste/client_v1-security_policy.xml) to find the
+policy files.  The '-d' option can be used to override the default
+/etc/xen/acm-security/policies policy-root directory.
 
 The default policy directory structure under /etc/xen/acm-security (and
 the Xen security tool build directory - tools/security) looks like:
 
 policies
 |-- security_policy.xsd
-|-- chwall
-|   |-- chwall-security_label_template.xml
-|   `-- chwall-security_policy.xml
-|-- chwall_ste
-|   |-- chwall_ste-security_label_template.xml
-|   `-- chwall_ste-security_policy.xml
-|-- null
-|   |-- null-security_label_template.xml
-|   `-- null-security_policy.xml
-`-- ste
-    |-- ste-security_label_template.xml
-    `-- ste-security_policy.xml
-
-The security_policy.xsd file contains the schema against which both the
-label-template and the policy files must validate during translation.
-
-The files ending in -security_policy.xml define the policies and the
-types known to the policies.
-
-The files ending in -security_label_template.xml contain the label
-definitions that group types together and make them easier to use for
-users.
-
-After executing the above xensec_xml2bin command, you will find 2 new
-files in the /etc/xen/acm-security/policies/chwall_ste sub-directory:
-
-  chwall_ste.map ... this file includes the mapping
+|-- example
+    |-- chwall
+    |   |-- client_v1-security_policy.xml
+    |
+    |-- chwall_ste
+    |   |-- client_v1-security_policy.xml
+    |
+    |-- ste
+        |-- client_v1-security_policy.xml
+
+The security_policy.xsd file contains the schema against which the
+policy files must validate during translation.
+
+The policy files, ending in -security_policy.xml, define the policies,
+the types known to the policies, and the label definitions that group
+types together and make them easier to use for users.
+
+After executing the above 'xm makepolicy' command, you will find 2 new
+files in the /etc/xen/acm-security/policies/example/chwall_ste
+sub-directory:
+
+  client_v1.map ... this file includes the mapping
     of names from the xml files into their binary code representation.
 
-  chwall_ste.bin ... this is the binary policy file,
-    the result of parsing the xml files and using the mapping to extract a
-    binary version that can be loaded into the hypervisor.
+  client_v1.bin ... this is the binary policy file, the result of
+    parsing the xml files and using the mapping to create a binary
+    version that can be loaded into the hypervisor.
 
 
 
 2. Loading and activating the policy:
 =====================================
 
-We assume that xen is already configured to use the chwall_ste policy;
+We assume that xen is already configured for security;
 please refer to install.txt for instructions.
 
-To activate the policy from the command line (assuming that the
-currently established policy is the minimal boot-policy that is
-hard-coded into the hypervisor):
-
-# xensec_tool loadpolicy /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin
-
-To activate the policy at next reboot:
-
-# cp /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin /boot
-
-Add a module line to your /boot/grub/grub.conf Xen entry.
-My boot entry with chwall_ste enabled looks like this:
+To activate the policy from the command line:
 
-    title Xen (2.6.12)
-        root (hd0,5)
-        kernel /boot/xen.gz dom0_mem=1200000 console=vga
-        module /boot/vmlinuz-2.6.12-xen0 ro root=/dev/hda6 rhgb
-        module /boot/initrd-2.6.12-xen0.img
-        module /boot/chwall_ste.bin
-
-This tells the grub boot-loader to load the binary policy, which
-the hypervisor will recognize. The hypervisor will then establish
-this binary policy during boot instead of the minimal policy that
-is hardcoded as default.
-
-If you have any trouble here, maks sure you have the access control
-framework enabled (see: install.txt).
+# xm loadpolicy example.chwall_ste.client_v1
 
+See install.txt for how to install a policy at boot time. This the
+recommended default. You can only load a policy if the currently
+enforced policy is "DEFAULT", a minimal startup policy, or if the
+currently enforced policy has the same name as the new one. Support
+for dynamic policy changes at run-time are a current working item.
 
 
 3. Labeling domains:
@@ -127,156 +87,143 @@ The chwall_ste-security_label_template.xml file includes an attribute
 "bootstrap", which is set to the label name that will be assigned to
 Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).
 
-b) Labeling User Domains:
-
-Use the script tools/security/setlabel.sh to choose a label and to
-assign labels to user domains.
+b) Labeling User Domains (domains started from dom0 using xm commands):
 
-To show available labels for the chwall_ste policy:
-
-# /etc/xen/acm-security/scripts/setlabel.sh -l
-
-lists all available labels. For the default chwall_ste it should print
-the following:
+We distinguish two kinds of labels: a) VM labels (for domains) and RES
+Labels (for resources). We focus here on VM labels. Resource labels
+will be supported later.
 
-    [root@laptopxn security]# /etc/xen/acm-security/scripts/setlabel.sh -l chwall_ste
-    The following labels are available:
-    dom_SystemManagement
-    dom_HomeBanking
-    dom_Fun
-    dom_BoincClient
-    dom_StorageDomain
-    dom_NetworkDomain
+To list all available domain labels of a policy, use:
+   #xm labels example.chwall_ste.client_v1
 
-You need to have compiled the policy beforehand so that a .map file
-exists. Setlabel.sh uses the mapping file created throughout the
-policy translation to translate a user-friendly label string into a
-ssidref-number that is eventually used by the Xen hypervisor.
+To list all available labels including resource labels (their support
+is current work), use:
 
-We distinguish two kinds of labels: a) VM labels (for domains) and RES
-Labels (for resources). We are currently working on support for
-resource labeling but will focus here on VM labels.
+   #xm labels example.chwall_ste.client_v1 type=any
 
-Setlabel.sh only prints VM labels (which we have prefixed with "dom_")
-since only those are used at this time.
+The policy parameter is optional. The currently enforced hypervisor
+policy is used by default.
 
-If you would like to assign the dom_HomeBanking label to one of your
-user domains (which you hopefully keep clean), look at the hypothetical
-domain configuration contained in /etc/xen/homebanking.xm:
+If you would like to assign the dom_HomeBanking label to one of your user domains,
+look at the hypothetical domain configuration contained in /etc/xen/homebanking.xm:
 
-    #------HOMEBANKING---------
-    kernel = "/boot/vmlinuz-2.6.12-xenU"
+    #------FOR HOME/ONLINE BANKING---------
+    kernel = "/boot/vmlinuz-2.6.16-xen"
     ramdisk="/boot/U1_ramdisk.img"
-    memory = 65
-    name = "test34"
-    cpu = -1   # leave to Xen to pick
-    # Number of network interfaces. Default is 1.
-    nics=1
-    dhcp="dhcp"
+    memory = 164
+    name = "homebanking"
+    vif=['']
+    dhcp = "dhcp"
     #-------------------------
 
-Now we label this domain
+Now we label this domain (policy name is optional, see above):
 
-[root@laptopxn security]# /etc/xen/acm-securit/scripts/setlabel.sh /etc/xen/homebanking.xm dom_HomeBanking chwall_ste
-Mapped label 'dom_HomeBanking' to ssidref '0x00020002'.
+    # xm addlabel homebanking.xm dom_HomeBanking example.chwall_ste.client_v1
 
-The domain configuration my look now like:
+The domain configuration should look now like:
 
-    [root@laptopxn security]# cat homebanking.xm
-    #------HOMEBANKING---------
-    kernel = "/boot/vmlinuz-2.6.12-xenU"
+    # cat homebanking.xm
+    #------FOR HOME/ONLINE BANKING---------
+    kernel = "/boot/vmlinuz-2.6.16-xen"
     ramdisk="/boot/U1_ramdisk.img"
-    memory = 65
-    name = "test34"
-    cpu = -1   # leave to Xen to pick
-    # Number of network interfaces. Default is 1.
-    nics=1
-    dhcp="dhcp"
-    #-------------------------
-    #ACM_POLICY=chwall_ste-security_policy.xml
-    #ACM_LABEL=dom_HomeBanking
-    ssidref = 0x00020002
-
-You can see 3 new entries, two of which are comments.  The only value
-that the hypervisor cares about is the ssidref that will reference
-those types assigned to this label. You can look them up in the
-xml label-template file for the chwall_ste policy.
-
-This script will eventually move into the domain management and will
-be called when the domain is instantiated. For now, the setlabel
-script must be run on domains whenever the policy files change since
-the mapping between label names and ssidrefs can change in this case.
+    memory = 164
+    name = "homebanking"
+    vif=['']
+    dhcp = "dhcp"
+    access_control = ['policy=example.chwall_ste.client_v1, label=dom_HomeBanking']
+
+You can see the access_control line that was added to the
+configuration. This label will be translated into a local ssidref when
+a domain is created or resumed (also after migration and
+live-migration). The ssidref is a local security reference that is
+used inside the hypervisor instead of the security label for
+efficiency reasons. Since the same label can be mapped onto different
+ssidrefs in different policy translations (e.g., if the position of
+the label definition is changed in the policy file) or on different
+systems, the ssidref is re-calculated from the label each time a
+domain is instantiated or re-instantiated.
+
+Currently, the labels are not held in the hypervisor but only in
+.map files in the /etc/xen/acm-security/policies subdirectories. Only
+ssidrefs are known inside the hypervisr. This of course can change in
+the future.
 
 
 4. Starting a labeled domain
 ============================
 
 Now, start the domain:
-    #xm create -c homebanking.xm
 
+    #xm create homebanking.xm
+    Using config file "homebanking.xm".
+    Started domain fun
+
+
+[root@941e-4 VMconfigs]# xm list --label
 
-If you label another domain configuration as dom_Fun and try to start
-it afterwards, its start will fail. Why?
+Name         ID Mem(MiB) VCPUs State  Time(s)  Label
+fun           1       64     1 -b----     5.9  dom_HomeBanking
+Domain-0      0     1954     1 r-----  1321.4  dom_SystemManagement
 
-Because the running homebanking domain has the chinese wall type
-"cw_Sensitive". The new domain dom_Fun has the chinese wall label
-"cw_Distrusted". This domain is not allowed to run simultaneously
-because of the defined conflict set
+
+
+If you label another domain configuration as dom_Fun and if
+you try to start it afterwards, this create will fail.
+
+Why? -- Because the running 'homebanking' domain has the chinese
+wall type "cw_Sensitive". The new domain 'fun' has the chinese wall
+label "cw_Distrusted". These domains are not allowed to run simultaneously
+on the same system because of the defined conflict set
 
 			<conflictset name="Protection1">
 				<type>cw_Sensitive</type>
 				<type>cw_Distrusted</type>
 			</conflictset>
 
-(in chwall_ste-security_policy.xml), which says that only one of the
+(in client_v1-security_policy.xml), which says that only one of the
 types cw_Sensitive and cw_Distrusted can run at a time.
 
-If you save or shutdown the HomeBanking domain, you will be able to
-start the "Fun" domain. You can look into the Xen log to see if a
+If you save or shutdown the 'homebanking' domain, you will be able to
+start the 'fun' domain. You can look into the Xen log to see if a
 domain was denied to start because of the access control framework
 with the command 'xm dmesg'.
 
 It is important (and usually non-trivial) to define the labels in a
 way that the semantics of the labels are enforced and supported by the
-types and the conflict sets.
+types and the conflict sets. Usually, a workload abstraction seems
+helpful on the hypervisor level.
 
 Note: While the chinese wall policy enforcement is complete, the type
-enforcement is currently enforced in the Xen hypervisor
+enforcement is currently enforced inside the Xen hypervisor
 only. Therefore, only point-to-point sharing with regard to the type
-enforcement is currently controlled. We are working on enhancements to
-Dom0 that enforce types also for network traffic that is routed
-through Dom0 and on the enforcement of resource labeling when binding
-resources to domains (e.g., enforcing types between domains and
-hardware resources, such as disk partitions).
+enforcement is currently controlled. Enforcing the STE policy while
+sharing virtual resources is ongoing work and assumed to be complete
+by year end as well as enforcing the STE policy for network traffic
+routed through dom0.
 
 
-4. Adding your own policies
+5. Adding your own policies
 ===========================
 
-Writing your own policy (e.g. "mypolicy") requires the following:
+Writing your own policy (e.g. "mypolicy.chwall.test") requires the policy
+definition (types etc.) and the label definitions. Any policy name
+must have chwall, ste, or chwall_ste in its name. This is used by the
+configuration tool to identify existing binary policy entries in the
+boot configuration file (menu.lst, grub.con). This part should, of
+course, be consistent with policy type that is defined.
 
-a) the policy definition (types etc.) file
-b) the label template definition (labels etc.) file
-
-If your policy name is "mypolicy", you need to create a
-subdirectory mypolicy in /etc/xen/acm-security/policies.
-
-Then you create
-/etc/xen/acm-security/policies/mypolicy/mypolicy-security_policy.xml and
-/etc/xen/acm-security/policies/mypolicy/mypolicy-security_label_template.xml.
+First, you create
+/etc/xen/acm-security/policies/mypolicy/chwall/test-security_policy.xml.
 
 You need to keep to the schema as defined in
-/etc/xen/acm-security/security_policy.xsd since the translation tool
-xensec_xml2bin is written against this schema.
-
-If you keep to the security policy schema, then you can use all the
-tools described above. Refer to install.txt to install it.
+/etc/xen/acm-security/security_policy.xsd since the translation tools
+are written against this schema.
 
 You can hand-edit the xml files to create your policy or you can use the
 xensec_gen utility.
 
 
-5. Generating policy files using xensec_gen:
+6. Generating policy files using xensec_gen:
 ============================================
 
 The xensec_gen utility starts a web-server that can be used to generate the
@@ -290,25 +237,28 @@ to see the full list of options available.
 Once the xensec_gen utility is running, point a browser at the host and port
 on which the utility is running (e.g. http://localhost:7777/).  You will be
 presented with a web page that allows you to create or modify the XML policy
-files:
+file:
 
-  - The Security Policy section allows you to create or modify a policy
-    definition file
+  - The Security Policy types section allows you to create or modify
+    the policy types and conflict set definitions
 
   - The Security Policy Labeling section allows you to create or modify a
-    label template definition file
+    label definitions
 
-  Security Policy:
-  ----------------
-  The Security Policy section allows you to modify an existing policy definition
-  file or create a new policy definition file.  To modify an existing policy
-  definition, enter the full path to the existing file (the "Browse" button can
-  be used to aid in this) in the Policy File entry field.  To create a new
-  policy definition file leave the Policy File entry field blank.  At this point
-  click the "Create" button to begin modifying or creating your policy definition.
+The policy generation tool allows you to modify an existing policy
+definition or create a new policy definition file. To modify an
+existing policy definition, enter the full path to the existing file
+(the "Browse" button can be used to aid in this) in the Policy File
+entry field.  To create a new policy definition file leave the Policy
+File entry field blank.  At this point click the "Create" button to
+begin modifying or creating your policy definition.
 
-  You will then be presented with a web page that will allow you to create either
-  Simple Type Enforcement types or Chinese Wall types or both.
+  Security Policy Types Section
+  -----------------------------
+
+You will then be presented with a web page. The upper part of it will
+allow you to create either Simple Type Enforcement types or Chinese
+Wall types or both, as well as Chinese Wall conflict type sets.
 
   As an example:
     - To add a Simple Type Enforcement type:
@@ -326,32 +276,13 @@ files:
   Wall Conflict Set will allow you to add Chinese Wall types from the list of
   defined Chinese Wall types.
 
-  To create your policy definition file, click on the "Generate XML" button on
-  the top of the page.  This will present you with a dialog box to save the
-  generated XML file on your system.  The default name will be security_policy.xml
-  which you should change to follow the policy file naming conventions based on
-  the policy name that you choose to use.
-
-  To get a feel for the tool, you could use one of the example policy definition
-  files from /etc/xen/acm-security/policies as input.
-
-
   Security Policy Labeling:
   -------------------------
-  The Security Policy Labeling section allows you to modify an existing label
-  template definition file or create a new label template definition file.  To
-  modify an existing label template definition, enter the full path to the
-  existing file (the "Browse" button can be used to aid in this) in the Policy
-  Labeling File entry field.  Whether creating a new label template definition
-  file or modifying an existing one, you will need to specify the policy
-  definition file that is or will be associated with this label template
-  definition file.  At this point click the "Create" button to begin modifying
-  or creating your label template definition file.
-
-  You will then be presented with a web page that will allow you to create labels
-  for classes of virtual machines.  The input policy definition file will provide
-  the available types (Simple Type Enforcement and/or Chinese Wall) that can be
-  assigned to a virtual machine class.
+
+  The security policy label section of the web page allows you to create labels
+  for classes of virtual machines.  The input policy type definitions on the upper
+  part of the web page will provide the available types (Simple Type Enforcement
+  and/or Chinese Wall) that can be assigned to a virtual machine class.
 
   As an example:
     - To add a Virtual Machine class (the name entered will become the label
@@ -372,11 +303,74 @@ files:
   bootstrap domain (or Dom0 domain).  By default, the first Virtual Machine class
   created will be associated as the bootstrap domain.
 
-  To create your label template definition file, click on the "Generate XML" button
+  To save your policy definition file, click on the "Generate XML" button
   on the top of the page.  This will present you with a dialog box to save the
   generated XML file on your system.  The default name will be
-  security_label_template.xml which you should change to follow the policy file
+  security_policy.xml which you should change to follow the policy file
   naming conventions based on the policy name that you choose to use.
 
-  To get a feel for the tool, you could use one of the example policy definition
-  and label template definition files from /etc/xen/acm-security/policies as input.
+  To get a feel for the tool, you could use one of the example policy definitions
+  files from /etc/xen/acm-security/policies/example as input.
+
+
+7. Hypervisor - OS Security Interface
+=====================================
+
+We currently provide 2 hypercalls through which user operating systems
+can interact with the hypervisor Access Control Module. Examples of
+using them are under "xen_root"/tools/security/python/xensec_tools:
+
+
+I) acm_getdecision -i domainid -l labelname
+   Call this example script without arguments to show its usage
+   information.
+
+   This script enables a domain to retrieve an access control decision
+   regarding the STE policy from the hypervisor. It will be used to
+   control access to virtual/real resources in hosting domains.
+
+   The script can be provided with any combination of domain ids or
+   labelnames. Before calling into the hypervisor, labels are translated
+   into ssidrefs. The hypervisor then retrieves for any domain id
+   paramter the ssidref before deciding access.
+
+   Example:
+   #/etc/xen/acm-security/scripts/acm_getdecision -l dom_Fun
+						 -l dom_SystemManagement
+   PERMITTED
+
+   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -i 1
+   PERMITTED
+
+   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l dom_Fun
+   PERMITTED
+
+   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l no_label
+   ACMError: Label 'nolabel' not found.
+
+   Now, assume domain 123454 does not exist:
+   #/etc/xen/acm-security/scripts/acm_getdecision -i 123454 -l dom_Fun
+   ACMError: Cannot determine decision (Invalid parameter).
+
+   Return values:
+            * DENIED: access is denied based on the current hypervisor
+                      policy
+
+            * PERMITTED: access is permitted based on the current
+
+            * Exception ACMError: one of the parameters was illegal,
+                                  i.e. an unknown label or a
+                                  non-existing domain id
+
+I) acm_getlabel -i domainid
+   Retrieves the label of a runing domain. This function can be used
+   by domains to determine their own label or (if authorized) the label
+   other domains.
+
+   Example (result is broken up into different lines to simplify description):
+   # /etc/xen/acm-security/scripts/acm_getlabel -i 0
+  ('example.chwall.client_v1',         <--- policy describing labels etc.
+   'dom_SystemManagement',             <--- label name of the domain
+   'CHINESE WALL',                     <--- policy type
+   65537)                              <--- hypervisor internal ssidref
+
diff --git a/tools/security/install.txt b/tools/security/install.txt
index 3eb4296536..ebdf84f7d4 100644
--- a/tools/security/install.txt
+++ b/tools/security/install.txt
@@ -3,10 +3,11 @@
 #
 # Author:
 # Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
+#               03/18/2006 update: new labeling
 #
 #
 # This file shows how to activate and install the access control
-# framework.
+# framework for Xen.
 ##
 
 
@@ -20,43 +21,54 @@ Simple Type Enforcement policy. Some file names need to be replaced
 below to activate the Chinese Wall OR the Type Enforcement policy
 exclusively (chwall_ste --> {chwall, ste}).
 
+0. build and install the xm man page. It includes the description of
+   available management commands for the security policy for Xen and
+   the labeling of domains. If not installed by default, you can make
+   and install the xm man page as follows:
+       # cd "xen_root"/doc
+       # make install
+   Then, use man xm to read it:
+       # man xm
+
 1. enable access control in Xen
        # cd "xen_root"
        # edit/xemacs/vi Config.mk
 
        change the lines:
        ACM_SECURITY ?= n
-       ACM_DEFAULT_SECURITY_POLICY ?= ACM_NULL_POLICY
-
        to:
        ACM_SECURITY ?= y
+
+       Now the hypervisor will boot into the policy that is specified
+       in the grub configuration. If you would like to boot into a
+       specific policy (even if you can't specify a boot policy but
+       need to set the policy later using the 'xensec_tool
+       loadpolicy'), then use the other config parameter to change
+       from NULL to any other default policy, e.g.:
        ACM_DEFAULT_SECURITY_POLICY ?= ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
 
-       # make all
+       # make dist
        # ./install.sh
 
-2. compile the policy from xml to a binary format that can be loaded
-   into the hypervisor for enforcement
+2. Build acm and policy tools and create boot-able policy:
        # cd tools/security
-       # make
+       # make install
 
-       manual steps (alternative to make boot_install):
-       # ./xensec_xml2bin -d policies/ chwall_ste
-       # cp policies/chwall_ste/chwall_ste.bin /boot
-       # edit /boot/grub/grub.conf
-        add the follwoing line to your xen boot entry:
-       "module /boot/chwall_ste.bin"
+       For description of the following commands, please see the xm
+       man page (docs/man1/xm.1). If it is not built, then you can
+       create it manually: cd "xen_root"/docs; make; man man1/xm.1
 
-       alternatively, you can try our automatic translation and
-       installation of the policy:
-       # make boot_install
-
-       [we try hard to do the right thing to the right boot entry but
-        please verify boot entry in /boot/grub/grub.conf afterwards;
-        your xen boot entry should have an additional module line
-        specifying a chwall_ste.bin file with the correct directory
-        (e.g. "/" or "/boot").]
+       Step1: Building binary version of an example policy:
+       # xm makepolicy example.chwall_ste.client_v1
+       # xm cfgbootpolicy example.chwall_ste.client_v1
 
+       Please verify boot entry in /boot/grub/grub.conf (or menu.lst):
+        title Xen (2.6.16)
+        root (hd0,0)
+        kernel /xen.gz dom0_mem=2000000 console=vga
+        module /vmlinuz-2.6.16-xen ro root=/dev/VolGroup00/LogVol00 rhgb
+        module /initrd-2.6.165-xen-U.img
+        module /example.chwall_ste.client_v1.bin
 
 3. reboot into the newly compiled hypervisor
 
@@ -64,6 +76,12 @@ exclusively (chwall_ste --> {chwall, ste}).
 	# xm dmesg should show an entry about the policy being loaded
             during the boot process
 
-        # xensec_tool getpolicy
-            should print the new chwall_ste binary policy representation
+        # xm dumppolicy
+            should print the new binary policy representation
+            including the policy name example.chwall_ste.client_v1
+
+	# xm list --label
+	    should show security label names behind the running domains
 
+For more information about how to use the security-enabled Xen, see
+the examples.txt file in this directory.
diff --git a/tools/security/policy.txt b/tools/security/policy.txt
index 792ed2c236..4888577a1a 100644
--- a/tools/security/policy.txt
+++ b/tools/security/policy.txt
@@ -59,22 +59,34 @@ migrate). These controls decide based on the active policy
 configuration (see i. and ii.) if the operation proceeds of if the
 operation is aborted (denied).
 
-
 In general, security policy instantiations in the Xen access control
-framework are defined by two files:
-
-a) a single "policy-name"-security_policy.xml file that defines the
-types known to the ACM and policy rules based on these types
-
-b) a single "policy-name"-security_label_template.xml file that
-defines labels based on known types
-
-Every security policy has its own sub-directory under
-"Xen-root"/tools/security/policies in order to simplify their
-management and the security policy tools. We will describe those files
-for our example policy (Chinese Wall and Simple Type Enforcement) in
-more detail as we go along. Eventually, we will move towards a system
-installation where the policies will reside under /etc.
+framework are defined by XML policy files. Each security policy has
+exactly one file including all the information the hypervisor needs to
+enforce the policy.
+
+The name of a policy is unique and consists of a colon-separated list
+of names, which can be translated into the location (subtree) where
+this policy must be located. The last part of the name is the file
+name pre-fix for the policy xml file. The preceding name parts are
+translated into the local path relative to the global policy root
+(/etc/xen/acm-security/policies) pointing to the policy xml file. For
+example: example.chwall_ste.client_v1 denotes the policy file
+example/chwall_ste/client_v1-security_policy.xml relative to the
+global policy root directory.
+
+Every security policy has its own sub-directory under the global
+policy root directory /etc/xen/acm-security/policies, which is
+installed during the Xen installation or can be manually installed
+(when switching from a "security disabled" Xen to a "security enabled"
+Xen AFTER configuring security, see install.txt) by the command
+sequence:
+
+   cd "Xen-root"/tools/security/policies; make install
+
+We will describe those files for our example policy (Chinese Wall and
+Simple Type Enforcement) in more detail as we go along. Eventually, we
+will move towards a system installation where the policies will reside
+under /etc.
 
 
 CHINESE WALL
@@ -117,9 +129,9 @@ constraints where necessary.
 Example of a Chinese Wall Policy Instantiation
 ----------------------------------------------
 
-The file chwall-security_policy.xml defines the Chinese Wall types as
-well as the conflict sets for our example policy (you find it in the
-directory "xen_root"/tools/security/policies/chwall).
+The file client_v1-security_policy.xml defines the Chinese Wall types
+as well as the conflict sets for our example policy (you find it in
+the directory "policy_root"/example/chwall).
 
 It defines four Chinese Wall types (prefixed with cw_) with the
 following meaning:
@@ -168,11 +180,11 @@ policy.
 SIMPLE TYPE ENFORCEMENT
 =======================
 
-The file ste-security_policy.xml defines the simple type enforcement
-types for our example policy (you find it in the directory
-"xen_root"/tools/security/policies/ste). The Simple Type Enforcement
-policy defines which domains can share information with which other
-domains. To this end, it controls
+The file client_v1-security_policy.xml defines the simple type
+enforcement types for our example policy (you find it in the directory
+"policy_root"/example/ste). The Simple Type Enforcement policy defines
+which domains can share information with which other domains. To this
+end, it controls
 
 i) inter-domain communication channels (e.g., network traffic, events,
 and shared memory).
diff --git a/tools/security/readme.txt b/tools/security/readme.txt
index 688d640b0c..9d8e18a4ec 100644
--- a/tools/security/readme.txt
+++ b/tools/security/readme.txt
@@ -10,20 +10,25 @@
 # the access control policy and tools in Xen.
 ##
 
-1. policy.txt:
+1. 'xm' man page
+
+   describes the commands related to Xen management, including the
+   commands to manage security policies and labels. Read the access
+   control subcommand section of the xm manual first. If it is not
+   built by default, check install.txt.
+
+2. policy.txt:
 
    describes the general reasoning and examples for access
    control policies in Xen
 
 
-2. install.txt
+3. install.txt
 
    describes the activation of the access control framework
    in Xen
 
-3. example.txt
+4. example.txt
 
    describes the available tools for managing security policies
    in Xen and the tools to label domains
-
-