# HG changeset patch
# User smh22@xxxxxxxxxxxxxxxxxxxx
# Node ID c7b9b8a64755c0000677938a9ca6f0890a8ea33f
# Parent 681a18bf049e320ddb11dde9cca08fa7bba4192e
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>
diff -r 681a18bf049e -r c7b9b8a64755 docs/man/xm.pod.1
--- a/docs/man/xm.pod.1 Mon Apr 24 10:59:17 2006 +0100
+++ b/docs/man/xm.pod.1 Mon Apr 24 10:59:57 2006 +0100
@@ -136,7 +136,7 @@ The I<--long> option prints out the comp
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.
@@ -212,6 +212,18 @@ Use at your own risk.
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>
@@ -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 -r 681a18bf049e -r c7b9b8a64755 tools/security/example.txt
--- a/tools/security/example.txt Mon Apr 24 10:59:17 2006 +0100
+++ b/tools/security/example.txt Mon Apr 24 10:59:57 2006 +0100
@@ -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!
-
-
-
-1. Using xensec_xml2bin to translate the chwall_ste 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
+We will show how to install and use the example one of the client_v1
+policies. Other policies work similarly. Feedback welcome!
+
+
+
+1. Using xm tools to translate example.chwall_ste.client_v1 policy:
+===================================================================
+
+#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:
-
- 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).
-
+To activate the policy from the command line:
+
+# 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.
-
-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:
-
- [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.
+b) Labeling User Domains (domains started from dom0 using xm commands):
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.
-
-Setlabel.sh only prints VM labels (which we have prefixed with "dom_")
-since only those are used at this time.
-
-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:
-
- #------HOMEBANKING---------
- kernel = "/boot/vmlinuz-2.6.12-xenU"
+Labels (for resources). We focus here on VM labels. Resource labels
+will be supported later.
+
+To list all available domain labels of a policy, use:
+ #xm labels example.chwall_ste.client_v1
+
+To list all available labels including resource labels (their support
+is current work), use:
+
+ #xm labels example.chwall_ste.client_v1 type=any
+
+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,
+look at the hypothetical domain configuration contained in
/etc/xen/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"
+ memory = 164
+ name = "homebanking"
+ vif=['']
+ dhcp = "dhcp"
#-------------------------
-Now we label this domain
-
-[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'.
-
-The domain configuration my look now like:
-
- [root@laptopxn security]# cat homebanking.xm
- #------HOMEBANKING---------
- kernel = "/boot/vmlinuz-2.6.12-xenU"
+Now we label this domain (policy name is optional, see above):
+
+ # xm addlabel homebanking.xm dom_HomeBanking example.chwall_ste.client_v1
+
+The domain configuration should look now like:
+
+ # 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
-
-
-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
+
+ #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 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).
-
-
-4. Adding your own policies
+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.
+
+
+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
-
-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.
+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.
+
+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 @@ Once the xensec_gen utility is running,
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:
-
- - The Security Policy section allows you to create or modify a policy
- definition file
+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
-
- 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.
+ label definitions
+
+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
+
diff -r 681a18bf049e -r c7b9b8a64755 tools/security/install.txt
--- a/tools/security/install.txt Mon Apr 24 10:59:17 2006 +0100
+++ b/tools/security/install.txt Mon Apr 24 10:59:57 2006 +0100
@@ -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 @@ below to activate the Chinese Wall OR th
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
+ Step1: Building binary version of an example policy:
+ # xm makepolicy example.chwall_ste.client_v1
+ # xm cfgbootpolicy example.chwall_ste.client_v1
- [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").]
-
+ 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 @@ 3. reboot into the newly compiled hyperv
# 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 -r 681a18bf049e -r c7b9b8a64755 tools/security/policy.txt
--- a/tools/security/policy.txt Mon Apr 24 10:59:17 2006 +0100
+++ b/tools/security/policy.txt Mon Apr 24 10:59:57 2006 +0100
@@ -59,22 +59,34 @@ configuration (see i. and ii.) if the op
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 @@ Example of a Chinese Wall Policy Instant
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 @@ SIMPLE TYPE ENFORCEMENT
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 -r 681a18bf049e -r c7b9b8a64755 tools/security/readme.txt
--- a/tools/security/readme.txt Mon Apr 24 10:59:17 2006 +0100
+++ b/tools/security/readme.txt Mon Apr 24 10:59:57 2006 +0100
@@ -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-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog
|
Home