WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-devel

[Xen-devel] [Patch 8 / 8][ACM] - documentation and xm man page

To: xen-devel@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-devel] [Patch 8 / 8][ACM] - documentation and xm man page
From: Reiner Sailer <sailer@xxxxxxxxxx>
Date: Tue, 11 Apr 2006 22:29:40 -0400
Cc: sailer@xxxxxxxxxx
Delivery-date: Tue, 11 Apr 2006 19:33:36 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-devel-request@lists.xensource.com?subject=help>
List-id: Xen developer discussion <xen-devel.lists.xensource.com>
List-post: <mailto:xen-devel@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-devel>, <mailto:xen-devel-request@lists.xensource.com?subject=unsubscribe>
Sender: xen-devel-bounces@xxxxxxxxxxxxxxxxxxx
User-agent: Mozilla Thunderbird 1.0.7 (Windows/20050923)
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@xxxxxxxxxx>

---
 docs/man/xm.pod.1          |  271 +++++++++++++++++++++++++++
 tools/security/example.txt |  442 ++++++++++++++++++++++-----------------------
 tools/security/install.txt |   70 ++++---
 tools/security/policy.txt  |   58 +++--
 tools/security/readme.txt  |   15 +
 5 files changed, 577 insertions(+), 279 deletions(-)

Index: xen-unstable.hg-shype/docs/man/xm.pod.1
===================================================================
--- xen-unstable.hg-shype.orig/docs/man/xm.pod.1
+++ xen-unstable.hg-shype/docs/man/xm.pod.1
@@ -136,7 +136,7 @@ Displays the short help message (i.e. co
 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
Index: xen-unstable.hg-shype/tools/security/example.txt
===================================================================
--- xen-unstable.hg-shype.orig/tools/security/example.txt
+++ xen-unstable.hg-shype/tools/security/example.txt
@@ -3,119 +3,79 @@
 #
 # Author:
 # Reiner Sailer 08/15/2005 <sailer@xxxxxxxxxxxxxx>
+#               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.
+|-- 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:
 
-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
+  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
+To activate the policy from the command line:
 
-Add a module line to your /boot/grub/grub.conf Xen entry.
-My boot entry with chwall_ste enabled looks like this:
-
-    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.x
 "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:
+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.
 
-# /etc/xen/acm-security/scripts/setlabel.sh -l
+To list all available domain labels of a policy, use:
+   #xm labels example.chwall_ste.client_v1
 
-lists all available labels. For the default chwall_ste it should print
-the following:
-
-    [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
-
-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
+
+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
 
 
-If you label another domain configuration as dom_Fun and try to start
-it afterwards, its start will fail. Why?
 
-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:
-
-a) the policy definition (types etc.) file
-b) the label template definition (labels etc.) file
+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.
 
-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 availabl
 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.
-
-  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.
+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.
+
+  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
+
Index: xen-unstable.hg-shype/tools/security/install.txt
===================================================================
--- xen-unstable.hg-shype.orig/tools/security/install.txt
+++ xen-unstable.hg-shype/tools/security/install.txt
@@ -3,10 +3,11 @@
 #
 # Author:
 # Reiner Sailer 08/15/2005 <sailer@xxxxxxxxxxxxxx>
+#               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 fil
 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
-
-       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"
-
-       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").]
+       # make install
 
+       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
+
+       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.
Index: xen-unstable.hg-shype/tools/security/policy.txt
===================================================================
--- xen-unstable.hg-shype.orig/tools/security/policy.txt
+++ xen-unstable.hg-shype/tools/security/policy.txt
@@ -59,22 +59,34 @@ migrate). These controls decide based on
 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).
Index: xen-unstable.hg-shype/tools/security/readme.txt
===================================================================
--- xen-unstable.hg-shype.orig/tools/security/readme.txt
+++ xen-unstable.hg-shype/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
-
-

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel
<Prev in Thread] Current Thread [Next in Thread>
  • [Xen-devel] [Patch 8 / 8][ACM] - documentation and xm man page, Reiner Sailer <=