ia64/xen-unstable

changeset 9837:c7b9b8a64755

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>
author smh22@firebug.cl.cam.ac.uk
date Mon Apr 24 10:59:57 2006 +0100 (2006-04-24)
parents 681a18bf049e
children 6da766b23d14
files docs/man/xm.pod.1 tools/security/example.txt tools/security/install.txt tools/security/policy.txt tools/security/readme.txt
line diff
     1.1 --- a/docs/man/xm.pod.1	Mon Apr 24 10:59:17 2006 +0100
     1.2 +++ b/docs/man/xm.pod.1	Mon Apr 24 10:59:57 2006 +0100
     1.3 @@ -136,7 +136,7 @@ Displays the short help message (i.e. co
     1.4  The I<--long> option prints out the complete set of B<xm> subcommands,
     1.5  grouped by function.
     1.6  
     1.7 -=item B<list> I<[--long]> I<[domain-id, ...]>
     1.8 +=item B<list> I<[--long | --label]> I<[domain-id, ...]>
     1.9  
    1.10  Prints information about one or more domains.  If no domains are
    1.11  specified it prints out information about all domains.
    1.12 @@ -213,6 +213,18 @@ Use at your own risk.
    1.13  
    1.14  =back
    1.15  
    1.16 +B<LABEL OUTPUT>
    1.17 +
    1.18 +=over 4
    1.19 +
    1.20 +If I<--label> is specified, the security labels are added to the
    1.21 +output of xm list and the lines are sorted by the labels (ignoring
    1.22 +case). The I<--long> option prints the labels by default and cannot be
    1.23 +combined with I<--label>. See the ACCESS CONTROL SUBCOMMAND section of
    1.24 +this man page for more information about labels.
    1.25 +
    1.26 +==back
    1.27 +
    1.28  B<NOTES>
    1.29  
    1.30  =over 4
    1.31 @@ -775,6 +787,262 @@ Delete a vnet.
    1.32  
    1.33  =back
    1.34  
    1.35 +=head1 ACCESS CONTROL SUBCOMMANDS
    1.36 +
    1.37 +Access Control in Xen consists of two components: (i) The Access
    1.38 +Control Policy (ACP) defines security labels and access rules based on
    1.39 +these labels. (ii) The Access Control Module (ACM) makes access control
    1.40 +decisions by interpreting the policy when domains require to
    1.41 +communicate or to access resources. The Xen access control has
    1.42 +sufficient mechanisms in place to enforce the access decisions even
    1.43 +against maliciously acting user domains (mandatory access control).
    1.44 +
    1.45 +Access rights for domains in Xen are determined by the domain security
    1.46 +label only and not based on the domain Name or ID. The ACP specifies
    1.47 +security labels that can then be assigned to domains and
    1.48 +resources. Every domain must be assigned exactly one security label,
    1.49 +otherwise access control decisions could become indeterministic. ACPs
    1.50 +are distinguished by their name, which is a parameter to most of the
    1.51 +subcommands described below. Currently, the ACP specifies two ways to
    1.52 +interpret labels:
    1.53 +
    1.54 +(1) Simple Type Enforcement: Labels are interpreted to decide access
    1.55 +of domains to comunication means and virtual or physical
    1.56 +resources. Communication between domains as well as access to
    1.57 +resources are forbidden by default and can only take place if they are
    1.58 +explicitly allowed by the security policy. The proper assignment of
    1.59 +labels to domains controls the sharing of information (directly
    1.60 +through communication or indirectly through shared resources) between
    1.61 +domains. This interpretation allows to control the overt (intended)
    1.62 +communication channels in Xen.
    1.63 +
    1.64 +(2) Chinese Wall: Labels are interpreted to decide which domains can
    1.65 +co-exist (be run simultaneously) on the same system. This
    1.66 +interpretation allows to prevent direct covert (unintended) channels
    1.67 +and mitigates risks caused by imperfect core domain isolation
    1.68 +(trade-off between security and other system requirements). For a
    1.69 +short introduction to covert channels, please refer to
    1.70 +http://www.multicians.org/timing-chn.html.
    1.71 +
    1.72 +The following subcommands help you to manage security policies in Xen
    1.73 +and to assign security labels to domains. To enable access control
    1.74 +security in Xen, you must compile Xen with ACM support enabled as
    1.75 +described under "Configuring Security" below. There, you will find
    1.76 +also examples of each subcommand described here.
    1.77 +
    1.78 +=item B<makepolicy> I<policy>
    1.79 +
    1.80 +Compiles the XML source representation of the security I<policy>. It
    1.81 +creates a mapping (.map) as well as a binary (.bin) version of the
    1.82 +policy. The compiled policy can be loaded into Xen with the
    1.83 +B<loadpolicy> subcommand or can be configured to be loaded at boot
    1.84 +time with the B<cfgbootpolicy> subcommand.
    1.85 +
    1.86 +=over 4
    1.87 +
    1.88 +I<policy> is a dot-separated list of names. The last part is the file
    1.89 +name pre-fix for the policy xml file. The preceding name parts are
    1.90 +translated into the local path pointing to the policy xml file
    1.91 +relative to the global policy root directory
    1.92 +(/etc/xen/acm-security/policies). For example,
    1.93 +example.chwall_ste.client_v1 denotes the policy file
    1.94 +example/chwall_ste/client_v1-security_policy.xml relative to the
    1.95 +global policy root directory.
    1.96 +
    1.97 +=back
    1.98 +
    1.99 +=item B<loadpolicy> I<policy>
   1.100 +
   1.101 +Loads the binary representation of the I<policy> into Xen. The binary
   1.102 +representation can be created with the B<makepolicy> subcommand.
   1.103 +
   1.104 +=item B<cfgbootpolicy> I<policy> [I<kernelversion>]
   1.105 +
   1.106 +Configures I<policy> as the boot policy for Xen. It copies the binary
   1.107 +policy representation into the /boot directory and adds a module line
   1.108 +specifying the binary policy to the /boot/grub/menu.lst file. If your
   1.109 +boot configuration includes multiple Xen boot titles, then use the
   1.110 +I<kernelversion> parameter to select the proper title.
   1.111 +
   1.112 +=item B<dumppolicy>
   1.113 +
   1.114 +Prints the current security policy state information of Xen.
   1.115 +
   1.116 +=item B<labels> [I<policy>] [I<type>=dom|res|any]
   1.117 +
   1.118 +Lists all labels of a I<type> (domain, resource, or both) that are
   1.119 +defined in the I<policy>. Unless specified, the default I<policy> is
   1.120 +the currently enforced access control policy. The default for I<type>
   1.121 +is 'dom'. The labels are arranged in alphabetical order.
   1.122 +
   1.123 +=item B<addlabel> I<configfile> I<label> [I<policy>]
   1.124 +
   1.125 +Adds the security label with name I<label> to a domain
   1.126 +I<configfile>. Unless specified, the default I<policy> is the
   1.127 +currently enforced access control policy. This subcommand also
   1.128 +verifies that the I<policy> definition supports the specified I<label>
   1.129 +name.
   1.130 +
   1.131 +B<CONFIGURING SECURITY>
   1.132 +
   1.133 +=over 4
   1.134 +
   1.135 +In xen_source_dir/Config.mk set the following parameters:
   1.136 +
   1.137 +    ACM_SECURITY ?= y
   1.138 +    ACM_DEFAULT_SECURITY_POLICY ?= \
   1.139 +        ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
   1.140 +
   1.141 +Then recompile and install xen and the security tools and then reboot:
   1.142 +
   1.143 +    cd xen_source_dir/xen; make clean; make; cp xen.gz /boot;
   1.144 +    cd xen_source_dir/tools/security; make install;
   1.145 +    reboot into xen
   1.146 +
   1.147 +=back
   1.148 +
   1.149 +B<COMPILING A SECURITY POLICY>
   1.150 +
   1.151 +=over 4
   1.152 +
   1.153 +This step creates client_v1.map and client_v1.bin files in
   1.154 +/etc/xen/acm-security/policies/example/chwall_ste.
   1.155 +
   1.156 +    xm makepolicy example.chwall_ste.client_v1
   1.157 +
   1.158 +=back
   1.159 +
   1.160 +B<LOADING A SECURITY POLICY>
   1.161 +
   1.162 +=over 4
   1.163 +
   1.164 +This step activates client_v1.bin as new security policy in Xen. You
   1.165 +can use the dumppolicy subcommand before and afterwards to see the
   1.166 +change in the Xen policy state.
   1.167 +
   1.168 +    xm loadpolicy example.chwall_ste.client_v1
   1.169 +
   1.170 +=back
   1.171 +
   1.172 +B<CONFIGURING A BOOT SECURITY POLICY>
   1.173 +
   1.174 +=over 4
   1.175 +
   1.176 +This configures the boot loader to load client_v1.bin at boot
   1.177 +time. During system start, the ACM configures Xen with this policy and
   1.178 +Xen enforces this policy from then on.
   1.179 +
   1.180 +    xm cfgbootpolicy example.chwall_ste.client_v1
   1.181 +
   1.182 +=back
   1.183 +
   1.184 +B<LISTING SECURITY LABELS>
   1.185 +
   1.186 +=over 4
   1.187 +
   1.188 +This subcommand shows all labels that are defined and which can be
   1.189 +attached to domains.
   1.190 +
   1.191 +    xm labels example.chwall_ste.client_v1 type=dom
   1.192 +
   1.193 +will print for our example policy:
   1.194 +
   1.195 +        dom_BoincClient
   1.196 +        dom_Fun
   1.197 +        dom_HomeBanking
   1.198 +        dom_NetworkDomain
   1.199 +        dom_StorageDomain
   1.200 +        dom_SystemManagement
   1.201 +
   1.202 +=back
   1.203 +
   1.204 +B<ATTACHING A SECURITY LABEL TO A DOMAIN>
   1.205 +
   1.206 +=over 4
   1.207 +
   1.208 +This subcommand attaches a security label to a domain configuration
   1.209 +file, here a HomeBanking label. The example policy ensures that this
   1.210 +domain does not share information with other non-hombanking user
   1.211 +domains (i.e., domains labeled as dom_Fun or dom_Boinc) and that it
   1.212 +will not run simultaneously with domains labeled as dom_Fun.
   1.213 +
   1.214 +We assume that the specified myconfig.xm configuration file actually
   1.215 +instantiates a domain that runs workloads related to home-banking,
   1.216 +probably just a browser environment for online-banking.
   1.217 +
   1.218 +    xm addlabel myconfig.xm dom_HomeBanking
   1.219 +
   1.220 +The very simple configuration file might now look as printed
   1.221 +below. The I<addlabel> subcommand added the B<access_control> entry at
   1.222 +the end of the file, consisting of a label name and the policy that
   1.223 +specifies this label name:
   1.224 +
   1.225 +    kernel = "/boot/vmlinuz-2.6.16-xen"
   1.226 +    ramdisk="/boot/U1_home_banking_ramdisk.img"
   1.227 +    memory = 164
   1.228 +    name = "homebanking"
   1.229 +    vif = [ '' ]
   1.230 +    dhcp = "dhcp"
   1.231 +    access_control = ['policy=example.chwall_ste.client_v1,
   1.232 +                       label=dom_HomeBanking']
   1.233 +
   1.234 +Security labels must be assigned to domain configurations because
   1.235 +these labels are essential for making access control decisions as
   1.236 +early as during the configuration phase of a newly instantiated
   1.237 +domain. Consequently, a security-enabled Xen hypervisor will only
   1.238 +start domains that have a security label configured and whose security
   1.239 +label is consistent with the currently enforced policy. Otherwise,
   1.240 +starting the domain will fail with the error condition "operation not
   1.241 +permitted".
   1.242 +
   1.243 +=back
   1.244 +
   1.245 +B<STARTING AND LISTING LABELED DOMAINS>
   1.246 +
   1.247 +=over 4
   1.248 +
   1.249 +    xm create myconfig.xm
   1.250 +
   1.251 +    xm list --label
   1.252 +
   1.253 +      Name         ID ...  Time(s)  Label
   1.254 +      homebanking  23 ...      4.4  dom_HomeBanking
   1.255 +      Domain-0      0 ...   2658.8  dom_SystemManagement
   1.256 +
   1.257 +=back
   1.258 +
   1.259 +B<POLICY REPRESENTATIONS>
   1.260 +
   1.261 +=over 4
   1.262 +
   1.263 +We distinguish three representations of the Xen access control policy:
   1.264 +the I<source XML> version, its I<binary> counterpart, and a I<mapping>
   1.265 +representation that enables the tools to deterministically translate
   1.266 +back and forth between label names of the XML policy and label
   1.267 +identifiers of the binary policy. All three versions must be kept
   1.268 +consistent to achieve predictable security guarantees.
   1.269 +
   1.270 +The XML version is the version that users are supposed to create or
   1.271 +change, either by manually editing the XML file or by using the Xen
   1.272 +policy generation tool (B<xensec_gen>). After changing the XML file,
   1.273 +run the B<makepolicy> subcommand to ensure that these changes are
   1.274 +reflected in the other versions. Use, for example, the subcommand
   1.275 +B<cfgbootpolicy> to activate the changes during the next system
   1.276 +reboot.
   1.277 +
   1.278 +The binary version of the policy is derived from the XML policy by
   1.279 +tokenizing the specified labels and is used inside Xen only. It is
   1.280 +created with the B<makepolicy> subcommand. Essentially, the binary
   1.281 +version is much more compact than the XML version and is easier to
   1.282 +evaluate during access control decisions.
   1.283 +
   1.284 +The mapping version of the policy is created during the XML-to-binary
   1.285 +policy translation (B<makepolicy>) and is used by the Xen management
   1.286 +tools to translate between label names used as input to the tools and
   1.287 +their binary identifiers (ssidrefs) used inside Xen.
   1.288 +
   1.289 +=back
   1.290 +
   1.291  =head1 EXAMPLES
   1.292  
   1.293  =head1 SEE ALSO
   1.294 @@ -791,5 +1059,6 @@ Operating Systems Review, pages 261-267
   1.295  
   1.296    Sean Dague <sean at dague dot net>
   1.297    Daniel Stekloff <dsteklof at us dot ibm dot com>
   1.298 +  Reiner Sailer <sailer at us dot ibm dot com>
   1.299  
   1.300  =head1 BUGS
     2.1 --- a/tools/security/example.txt	Mon Apr 24 10:59:17 2006 +0100
     2.2 +++ b/tools/security/example.txt	Mon Apr 24 10:59:57 2006 +0100
     2.3 @@ -3,119 +3,79 @@
     2.4  #
     2.5  # Author:
     2.6  # Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
     2.7 +#               04/07/2006 update to using labels instead of ssidref
     2.8  #
     2.9  #
    2.10  # This file introduces into the tools to manage policies
    2.11  # and to label domains and resources.
    2.12  ##
    2.13  
    2.14 -We will show how to install and use the example chwall_ste policy.
    2.15 -Other policies work similarly. Feedback welcome!
    2.16 +We will show how to install and use the example one of the client_v1
    2.17 +policies. Other policies work similarly. Feedback welcome!
    2.18  
    2.19  
    2.20  
    2.21 -1. Using xensec_xml2bin to translate the chwall_ste policy:
    2.22 -===========================================================
    2.23 -
    2.24 -#xensec_xml2bin chwall_ste
    2.25 -
    2.26 -Successful execution should print:
    2.27 +1. Using xm tools to translate example.chwall_ste.client_v1 policy:
    2.28 +===================================================================
    2.29  
    2.30 -    [root@laptopxn security]# xensec_xml2bin chwall_ste
    2.31 -    Validating label file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_label_template.xml...
    2.32 -    XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
    2.33 -    Validating policy file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_policy.xml...
    2.34 -    XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
    2.35 -    Creating ssid mappings ...
    2.36 -    Creating label mappings ...
    2.37 -    Max chwall labels:  7
    2.38 -    Max chwall-types:   4
    2.39 -    Max chwall-ssids:   5
    2.40 -    Max ste labels:     14
    2.41 -    Max ste-types:      6
    2.42 -    Max ste-ssids:      10
    2.43 +#xm makepolicy example.chwall_ste.client_v1
    2.44  
    2.45  By default, the tool looks in directory /etc/xen/acm-security/policies
    2.46 -for a directory that matches the policy name (i.e. chwall_ste) to find
    2.47 -the label and policy files.
    2.48 -The '-d' option can be used to override the /etc/xen/acm-security/policies
    2.49 -directory, for example if running the tool in the Xen security tool build
    2.50 -directory.
    2.51 +for a directory that matches the policy name
    2.52 +(here:example/chwall_ste/client_v1-security_policy.xml) to find the
    2.53 +policy files.  The '-d' option can be used to override the default
    2.54 +/etc/xen/acm-security/policies policy-root directory.
    2.55  
    2.56  The default policy directory structure under /etc/xen/acm-security (and
    2.57  the Xen security tool build directory - tools/security) looks like:
    2.58  
    2.59  policies
    2.60  |-- security_policy.xsd
    2.61 -|-- chwall
    2.62 -|   |-- chwall-security_label_template.xml
    2.63 -|   `-- chwall-security_policy.xml
    2.64 -|-- chwall_ste
    2.65 -|   |-- chwall_ste-security_label_template.xml
    2.66 -|   `-- chwall_ste-security_policy.xml
    2.67 -|-- null
    2.68 -|   |-- null-security_label_template.xml
    2.69 -|   `-- null-security_policy.xml
    2.70 -`-- ste
    2.71 -    |-- ste-security_label_template.xml
    2.72 -    `-- ste-security_policy.xml
    2.73 +|-- example
    2.74 +    |-- chwall
    2.75 +    |   |-- client_v1-security_policy.xml
    2.76 +    |
    2.77 +    |-- chwall_ste
    2.78 +    |   |-- client_v1-security_policy.xml
    2.79 +    |
    2.80 +    |-- ste
    2.81 +        |-- client_v1-security_policy.xml
    2.82  
    2.83 -The security_policy.xsd file contains the schema against which both the
    2.84 -label-template and the policy files must validate during translation.
    2.85 -
    2.86 -The files ending in -security_policy.xml define the policies and the
    2.87 -types known to the policies.
    2.88 +The security_policy.xsd file contains the schema against which the
    2.89 +policy files must validate during translation.
    2.90  
    2.91 -The files ending in -security_label_template.xml contain the label
    2.92 -definitions that group types together and make them easier to use for
    2.93 -users.
    2.94 +The policy files, ending in -security_policy.xml, define the policies,
    2.95 +the types known to the policies, and the label definitions that group
    2.96 +types together and make them easier to use for users.
    2.97  
    2.98 -After executing the above xensec_xml2bin command, you will find 2 new
    2.99 -files in the /etc/xen/acm-security/policies/chwall_ste sub-directory:
   2.100 +After executing the above 'xm makepolicy' command, you will find 2 new
   2.101 +files in the /etc/xen/acm-security/policies/example/chwall_ste
   2.102 +sub-directory:
   2.103  
   2.104 -  chwall_ste.map ... this file includes the mapping
   2.105 +  client_v1.map ... this file includes the mapping
   2.106      of names from the xml files into their binary code representation.
   2.107  
   2.108 -  chwall_ste.bin ... this is the binary policy file,
   2.109 -    the result of parsing the xml files and using the mapping to extract a
   2.110 -    binary version that can be loaded into the hypervisor.
   2.111 +  client_v1.bin ... this is the binary policy file, the result of
   2.112 +    parsing the xml files and using the mapping to create a binary
   2.113 +    version that can be loaded into the hypervisor.
   2.114  
   2.115  
   2.116  
   2.117  2. Loading and activating the policy:
   2.118  =====================================
   2.119  
   2.120 -We assume that xen is already configured to use the chwall_ste policy;
   2.121 +We assume that xen is already configured for security;
   2.122  please refer to install.txt for instructions.
   2.123  
   2.124 -To activate the policy from the command line (assuming that the
   2.125 -currently established policy is the minimal boot-policy that is
   2.126 -hard-coded into the hypervisor):
   2.127 -
   2.128 -# xensec_tool loadpolicy /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin
   2.129 -
   2.130 -To activate the policy at next reboot:
   2.131 -
   2.132 -# cp /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin /boot
   2.133 -
   2.134 -Add a module line to your /boot/grub/grub.conf Xen entry.
   2.135 -My boot entry with chwall_ste enabled looks like this:
   2.136 +To activate the policy from the command line:
   2.137  
   2.138 -    title Xen (2.6.12)
   2.139 -        root (hd0,5)
   2.140 -        kernel /boot/xen.gz dom0_mem=1200000 console=vga
   2.141 -        module /boot/vmlinuz-2.6.12-xen0 ro root=/dev/hda6 rhgb
   2.142 -        module /boot/initrd-2.6.12-xen0.img
   2.143 -        module /boot/chwall_ste.bin
   2.144 +# xm loadpolicy example.chwall_ste.client_v1
   2.145  
   2.146 -This tells the grub boot-loader to load the binary policy, which
   2.147 -the hypervisor will recognize. The hypervisor will then establish
   2.148 -this binary policy during boot instead of the minimal policy that
   2.149 -is hardcoded as default.
   2.150 -
   2.151 -If you have any trouble here, maks sure you have the access control
   2.152 -framework enabled (see: install.txt).
   2.153 -
   2.154 +See install.txt for how to install a policy at boot time. This the
   2.155 +recommended default. You can only load a policy if the currently
   2.156 +enforced policy is "DEFAULT", a minimal startup policy, or if the
   2.157 +currently enforced policy has the same name as the new one. Support
   2.158 +for dynamic policy changes at run-time are a current working item.
   2.159  
   2.160  
   2.161  3. Labeling domains:
   2.162 @@ -127,156 +87,143 @@ The chwall_ste-security_label_template.x
   2.163  "bootstrap", which is set to the label name that will be assigned to
   2.164  Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).
   2.165  
   2.166 -b) Labeling User Domains:
   2.167 -
   2.168 -Use the script tools/security/setlabel.sh to choose a label and to
   2.169 -assign labels to user domains.
   2.170 -
   2.171 -To show available labels for the chwall_ste policy:
   2.172 -
   2.173 -# /etc/xen/acm-security/scripts/setlabel.sh -l
   2.174 -
   2.175 -lists all available labels. For the default chwall_ste it should print
   2.176 -the following:
   2.177 -
   2.178 -    [root@laptopxn security]# /etc/xen/acm-security/scripts/setlabel.sh -l chwall_ste
   2.179 -    The following labels are available:
   2.180 -    dom_SystemManagement
   2.181 -    dom_HomeBanking
   2.182 -    dom_Fun
   2.183 -    dom_BoincClient
   2.184 -    dom_StorageDomain
   2.185 -    dom_NetworkDomain
   2.186 -
   2.187 -You need to have compiled the policy beforehand so that a .map file
   2.188 -exists. Setlabel.sh uses the mapping file created throughout the
   2.189 -policy translation to translate a user-friendly label string into a
   2.190 -ssidref-number that is eventually used by the Xen hypervisor.
   2.191 +b) Labeling User Domains (domains started from dom0 using xm commands):
   2.192  
   2.193  We distinguish two kinds of labels: a) VM labels (for domains) and RES
   2.194 -Labels (for resources). We are currently working on support for
   2.195 -resource labeling but will focus here on VM labels.
   2.196 -
   2.197 -Setlabel.sh only prints VM labels (which we have prefixed with "dom_")
   2.198 -since only those are used at this time.
   2.199 +Labels (for resources). We focus here on VM labels. Resource labels
   2.200 +will be supported later.
   2.201  
   2.202 -If you would like to assign the dom_HomeBanking label to one of your
   2.203 -user domains (which you hopefully keep clean), look at the hypothetical
   2.204 -domain configuration contained in /etc/xen/homebanking.xm:
   2.205 +To list all available domain labels of a policy, use:
   2.206 +   #xm labels example.chwall_ste.client_v1
   2.207  
   2.208 -    #------HOMEBANKING---------
   2.209 -    kernel = "/boot/vmlinuz-2.6.12-xenU"
   2.210 +To list all available labels including resource labels (their support
   2.211 +is current work), use:
   2.212 +
   2.213 +   #xm labels example.chwall_ste.client_v1 type=any
   2.214 +
   2.215 +The policy parameter is optional. The currently enforced hypervisor
   2.216 +policy is used by default.
   2.217 +
   2.218 +If you would like to assign the dom_HomeBanking label to one of your user domains,
   2.219 +look at the hypothetical domain configuration contained in /etc/xen/homebanking.xm:
   2.220 +
   2.221 +    #------FOR HOME/ONLINE BANKING---------
   2.222 +    kernel = "/boot/vmlinuz-2.6.16-xen"
   2.223      ramdisk="/boot/U1_ramdisk.img"
   2.224 -    memory = 65
   2.225 -    name = "test34"
   2.226 -    cpu = -1   # leave to Xen to pick
   2.227 -    # Number of network interfaces. Default is 1.
   2.228 -    nics=1
   2.229 -    dhcp="dhcp"
   2.230 +    memory = 164
   2.231 +    name = "homebanking"
   2.232 +    vif=['']
   2.233 +    dhcp = "dhcp"
   2.234      #-------------------------
   2.235  
   2.236 -Now we label this domain
   2.237 -
   2.238 -[root@laptopxn security]# /etc/xen/acm-securit/scripts/setlabel.sh /etc/xen/homebanking.xm dom_HomeBanking chwall_ste
   2.239 -Mapped label 'dom_HomeBanking' to ssidref '0x00020002'.
   2.240 +Now we label this domain (policy name is optional, see above):
   2.241  
   2.242 -The domain configuration my look now like:
   2.243 +    # xm addlabel homebanking.xm dom_HomeBanking example.chwall_ste.client_v1
   2.244  
   2.245 -    [root@laptopxn security]# cat homebanking.xm
   2.246 -    #------HOMEBANKING---------
   2.247 -    kernel = "/boot/vmlinuz-2.6.12-xenU"
   2.248 +The domain configuration should look now like:
   2.249 +
   2.250 +    # cat homebanking.xm
   2.251 +    #------FOR HOME/ONLINE BANKING---------
   2.252 +    kernel = "/boot/vmlinuz-2.6.16-xen"
   2.253      ramdisk="/boot/U1_ramdisk.img"
   2.254 -    memory = 65
   2.255 -    name = "test34"
   2.256 -    cpu = -1   # leave to Xen to pick
   2.257 -    # Number of network interfaces. Default is 1.
   2.258 -    nics=1
   2.259 -    dhcp="dhcp"
   2.260 -    #-------------------------
   2.261 -    #ACM_POLICY=chwall_ste-security_policy.xml
   2.262 -    #ACM_LABEL=dom_HomeBanking
   2.263 -    ssidref = 0x00020002
   2.264 +    memory = 164
   2.265 +    name = "homebanking"
   2.266 +    vif=['']
   2.267 +    dhcp = "dhcp"
   2.268 +    access_control = ['policy=example.chwall_ste.client_v1, label=dom_HomeBanking']
   2.269  
   2.270 -You can see 3 new entries, two of which are comments.  The only value
   2.271 -that the hypervisor cares about is the ssidref that will reference
   2.272 -those types assigned to this label. You can look them up in the
   2.273 -xml label-template file for the chwall_ste policy.
   2.274 +You can see the access_control line that was added to the
   2.275 +configuration. This label will be translated into a local ssidref when
   2.276 +a domain is created or resumed (also after migration and
   2.277 +live-migration). The ssidref is a local security reference that is
   2.278 +used inside the hypervisor instead of the security label for
   2.279 +efficiency reasons. Since the same label can be mapped onto different
   2.280 +ssidrefs in different policy translations (e.g., if the position of
   2.281 +the label definition is changed in the policy file) or on different
   2.282 +systems, the ssidref is re-calculated from the label each time a
   2.283 +domain is instantiated or re-instantiated.
   2.284  
   2.285 -This script will eventually move into the domain management and will
   2.286 -be called when the domain is instantiated. For now, the setlabel
   2.287 -script must be run on domains whenever the policy files change since
   2.288 -the mapping between label names and ssidrefs can change in this case.
   2.289 +Currently, the labels are not held in the hypervisor but only in
   2.290 +.map files in the /etc/xen/acm-security/policies subdirectories. Only
   2.291 +ssidrefs are known inside the hypervisr. This of course can change in
   2.292 +the future.
   2.293  
   2.294  
   2.295  4. Starting a labeled domain
   2.296  ============================
   2.297  
   2.298  Now, start the domain:
   2.299 -    #xm create -c homebanking.xm
   2.300 +
   2.301 +    #xm create homebanking.xm
   2.302 +    Using config file "homebanking.xm".
   2.303 +    Started domain fun
   2.304  
   2.305  
   2.306 -If you label another domain configuration as dom_Fun and try to start
   2.307 -it afterwards, its start will fail. Why?
   2.308 +[root@941e-4 VMconfigs]# xm list --label
   2.309  
   2.310 -Because the running homebanking domain has the chinese wall type
   2.311 -"cw_Sensitive". The new domain dom_Fun has the chinese wall label
   2.312 -"cw_Distrusted". This domain is not allowed to run simultaneously
   2.313 -because of the defined conflict set
   2.314 +Name         ID Mem(MiB) VCPUs State  Time(s)  Label
   2.315 +fun           1       64     1 -b----     5.9  dom_HomeBanking
   2.316 +Domain-0      0     1954     1 r-----  1321.4  dom_SystemManagement
   2.317 +
   2.318 +
   2.319 +
   2.320 +If you label another domain configuration as dom_Fun and if
   2.321 +you try to start it afterwards, this create will fail.
   2.322 +
   2.323 +Why? -- Because the running 'homebanking' domain has the chinese
   2.324 +wall type "cw_Sensitive". The new domain 'fun' has the chinese wall
   2.325 +label "cw_Distrusted". These domains are not allowed to run simultaneously
   2.326 +on the same system because of the defined conflict set
   2.327  
   2.328  			<conflictset name="Protection1">
   2.329  				<type>cw_Sensitive</type>
   2.330  				<type>cw_Distrusted</type>
   2.331  			</conflictset>
   2.332  
   2.333 -(in chwall_ste-security_policy.xml), which says that only one of the
   2.334 +(in client_v1-security_policy.xml), which says that only one of the
   2.335  types cw_Sensitive and cw_Distrusted can run at a time.
   2.336  
   2.337 -If you save or shutdown the HomeBanking domain, you will be able to
   2.338 -start the "Fun" domain. You can look into the Xen log to see if a
   2.339 +If you save or shutdown the 'homebanking' domain, you will be able to
   2.340 +start the 'fun' domain. You can look into the Xen log to see if a
   2.341  domain was denied to start because of the access control framework
   2.342  with the command 'xm dmesg'.
   2.343  
   2.344  It is important (and usually non-trivial) to define the labels in a
   2.345  way that the semantics of the labels are enforced and supported by the
   2.346 -types and the conflict sets.
   2.347 +types and the conflict sets. Usually, a workload abstraction seems
   2.348 +helpful on the hypervisor level.
   2.349  
   2.350  Note: While the chinese wall policy enforcement is complete, the type
   2.351 -enforcement is currently enforced in the Xen hypervisor
   2.352 +enforcement is currently enforced inside the Xen hypervisor
   2.353  only. Therefore, only point-to-point sharing with regard to the type
   2.354 -enforcement is currently controlled. We are working on enhancements to
   2.355 -Dom0 that enforce types also for network traffic that is routed
   2.356 -through Dom0 and on the enforcement of resource labeling when binding
   2.357 -resources to domains (e.g., enforcing types between domains and
   2.358 -hardware resources, such as disk partitions).
   2.359 +enforcement is currently controlled. Enforcing the STE policy while
   2.360 +sharing virtual resources is ongoing work and assumed to be complete
   2.361 +by year end as well as enforcing the STE policy for network traffic
   2.362 +routed through dom0.
   2.363  
   2.364  
   2.365 -4. Adding your own policies
   2.366 +5. Adding your own policies
   2.367  ===========================
   2.368  
   2.369 -Writing your own policy (e.g. "mypolicy") requires the following:
   2.370 -
   2.371 -a) the policy definition (types etc.) file
   2.372 -b) the label template definition (labels etc.) file
   2.373 +Writing your own policy (e.g. "mypolicy.chwall.test") requires the policy
   2.374 +definition (types etc.) and the label definitions. Any policy name
   2.375 +must have chwall, ste, or chwall_ste in its name. This is used by the
   2.376 +configuration tool to identify existing binary policy entries in the
   2.377 +boot configuration file (menu.lst, grub.con). This part should, of
   2.378 +course, be consistent with policy type that is defined.
   2.379  
   2.380 -If your policy name is "mypolicy", you need to create a
   2.381 -subdirectory mypolicy in /etc/xen/acm-security/policies.
   2.382 -
   2.383 -Then you create
   2.384 -/etc/xen/acm-security/policies/mypolicy/mypolicy-security_policy.xml and
   2.385 -/etc/xen/acm-security/policies/mypolicy/mypolicy-security_label_template.xml.
   2.386 +First, you create
   2.387 +/etc/xen/acm-security/policies/mypolicy/chwall/test-security_policy.xml.
   2.388  
   2.389  You need to keep to the schema as defined in
   2.390 -/etc/xen/acm-security/security_policy.xsd since the translation tool
   2.391 -xensec_xml2bin is written against this schema.
   2.392 -
   2.393 -If you keep to the security policy schema, then you can use all the
   2.394 -tools described above. Refer to install.txt to install it.
   2.395 +/etc/xen/acm-security/security_policy.xsd since the translation tools
   2.396 +are written against this schema.
   2.397  
   2.398  You can hand-edit the xml files to create your policy or you can use the
   2.399  xensec_gen utility.
   2.400  
   2.401  
   2.402 -5. Generating policy files using xensec_gen:
   2.403 +6. Generating policy files using xensec_gen:
   2.404  ============================================
   2.405  
   2.406  The xensec_gen utility starts a web-server that can be used to generate the
   2.407 @@ -290,25 +237,28 @@ to see the full list of options availabl
   2.408  Once the xensec_gen utility is running, point a browser at the host and port
   2.409  on which the utility is running (e.g. http://localhost:7777/).  You will be
   2.410  presented with a web page that allows you to create or modify the XML policy
   2.411 -files:
   2.412 +file:
   2.413  
   2.414 -  - The Security Policy section allows you to create or modify a policy
   2.415 -    definition file
   2.416 +  - The Security Policy types section allows you to create or modify
   2.417 +    the policy types and conflict set definitions
   2.418  
   2.419    - The Security Policy Labeling section allows you to create or modify a
   2.420 -    label template definition file
   2.421 +    label definitions
   2.422  
   2.423 -  Security Policy:
   2.424 -  ----------------
   2.425 -  The Security Policy section allows you to modify an existing policy definition
   2.426 -  file or create a new policy definition file.  To modify an existing policy
   2.427 -  definition, enter the full path to the existing file (the "Browse" button can
   2.428 -  be used to aid in this) in the Policy File entry field.  To create a new
   2.429 -  policy definition file leave the Policy File entry field blank.  At this point
   2.430 -  click the "Create" button to begin modifying or creating your policy definition.
   2.431 +The policy generation tool allows you to modify an existing policy
   2.432 +definition or create a new policy definition file. To modify an
   2.433 +existing policy definition, enter the full path to the existing file
   2.434 +(the "Browse" button can be used to aid in this) in the Policy File
   2.435 +entry field.  To create a new policy definition file leave the Policy
   2.436 +File entry field blank.  At this point click the "Create" button to
   2.437 +begin modifying or creating your policy definition.
   2.438  
   2.439 -  You will then be presented with a web page that will allow you to create either
   2.440 -  Simple Type Enforcement types or Chinese Wall types or both.
   2.441 +  Security Policy Types Section
   2.442 +  -----------------------------
   2.443 +
   2.444 +You will then be presented with a web page. The upper part of it will
   2.445 +allow you to create either Simple Type Enforcement types or Chinese
   2.446 +Wall types or both, as well as Chinese Wall conflict type sets.
   2.447  
   2.448    As an example:
   2.449      - To add a Simple Type Enforcement type:
   2.450 @@ -326,32 +276,13 @@ files:
   2.451    Wall Conflict Set will allow you to add Chinese Wall types from the list of
   2.452    defined Chinese Wall types.
   2.453  
   2.454 -  To create your policy definition file, click on the "Generate XML" button on
   2.455 -  the top of the page.  This will present you with a dialog box to save the
   2.456 -  generated XML file on your system.  The default name will be security_policy.xml
   2.457 -  which you should change to follow the policy file naming conventions based on
   2.458 -  the policy name that you choose to use.
   2.459 -
   2.460 -  To get a feel for the tool, you could use one of the example policy definition
   2.461 -  files from /etc/xen/acm-security/policies as input.
   2.462 -
   2.463 -
   2.464    Security Policy Labeling:
   2.465    -------------------------
   2.466 -  The Security Policy Labeling section allows you to modify an existing label
   2.467 -  template definition file or create a new label template definition file.  To
   2.468 -  modify an existing label template definition, enter the full path to the
   2.469 -  existing file (the "Browse" button can be used to aid in this) in the Policy
   2.470 -  Labeling File entry field.  Whether creating a new label template definition
   2.471 -  file or modifying an existing one, you will need to specify the policy
   2.472 -  definition file that is or will be associated with this label template
   2.473 -  definition file.  At this point click the "Create" button to begin modifying
   2.474 -  or creating your label template definition file.
   2.475  
   2.476 -  You will then be presented with a web page that will allow you to create labels
   2.477 -  for classes of virtual machines.  The input policy definition file will provide
   2.478 -  the available types (Simple Type Enforcement and/or Chinese Wall) that can be
   2.479 -  assigned to a virtual machine class.
   2.480 +  The security policy label section of the web page allows you to create labels
   2.481 +  for classes of virtual machines.  The input policy type definitions on the upper
   2.482 +  part of the web page will provide the available types (Simple Type Enforcement
   2.483 +  and/or Chinese Wall) that can be assigned to a virtual machine class.
   2.484  
   2.485    As an example:
   2.486      - To add a Virtual Machine class (the name entered will become the label
   2.487 @@ -372,11 +303,74 @@ files:
   2.488    bootstrap domain (or Dom0 domain).  By default, the first Virtual Machine class
   2.489    created will be associated as the bootstrap domain.
   2.490  
   2.491 -  To create your label template definition file, click on the "Generate XML" button
   2.492 +  To save your policy definition file, click on the "Generate XML" button
   2.493    on the top of the page.  This will present you with a dialog box to save the
   2.494    generated XML file on your system.  The default name will be
   2.495 -  security_label_template.xml which you should change to follow the policy file
   2.496 +  security_policy.xml which you should change to follow the policy file
   2.497    naming conventions based on the policy name that you choose to use.
   2.498  
   2.499 -  To get a feel for the tool, you could use one of the example policy definition
   2.500 -  and label template definition files from /etc/xen/acm-security/policies as input.
   2.501 +  To get a feel for the tool, you could use one of the example policy definitions
   2.502 +  files from /etc/xen/acm-security/policies/example as input.
   2.503 +
   2.504 +
   2.505 +7. Hypervisor - OS Security Interface
   2.506 +=====================================
   2.507 +
   2.508 +We currently provide 2 hypercalls through which user operating systems
   2.509 +can interact with the hypervisor Access Control Module. Examples of
   2.510 +using them are under "xen_root"/tools/security/python/xensec_tools:
   2.511 +
   2.512 +
   2.513 +I) acm_getdecision -i domainid -l labelname
   2.514 +   Call this example script without arguments to show its usage
   2.515 +   information.
   2.516 +
   2.517 +   This script enables a domain to retrieve an access control decision
   2.518 +   regarding the STE policy from the hypervisor. It will be used to
   2.519 +   control access to virtual/real resources in hosting domains.
   2.520 +
   2.521 +   The script can be provided with any combination of domain ids or
   2.522 +   labelnames. Before calling into the hypervisor, labels are translated
   2.523 +   into ssidrefs. The hypervisor then retrieves for any domain id
   2.524 +   paramter the ssidref before deciding access.
   2.525 +
   2.526 +   Example:
   2.527 +   #/etc/xen/acm-security/scripts/acm_getdecision -l dom_Fun
   2.528 +						 -l dom_SystemManagement
   2.529 +   PERMITTED
   2.530 +
   2.531 +   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -i 1
   2.532 +   PERMITTED
   2.533 +
   2.534 +   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l dom_Fun
   2.535 +   PERMITTED
   2.536 +
   2.537 +   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l no_label
   2.538 +   ACMError: Label 'nolabel' not found.
   2.539 +
   2.540 +   Now, assume domain 123454 does not exist:
   2.541 +   #/etc/xen/acm-security/scripts/acm_getdecision -i 123454 -l dom_Fun
   2.542 +   ACMError: Cannot determine decision (Invalid parameter).
   2.543 +
   2.544 +   Return values:
   2.545 +            * DENIED: access is denied based on the current hypervisor
   2.546 +                      policy
   2.547 +
   2.548 +            * PERMITTED: access is permitted based on the current
   2.549 +
   2.550 +            * Exception ACMError: one of the parameters was illegal,
   2.551 +                                  i.e. an unknown label or a
   2.552 +                                  non-existing domain id
   2.553 +
   2.554 +I) acm_getlabel -i domainid
   2.555 +   Retrieves the label of a runing domain. This function can be used
   2.556 +   by domains to determine their own label or (if authorized) the label
   2.557 +   other domains.
   2.558 +
   2.559 +   Example (result is broken up into different lines to simplify description):
   2.560 +   # /etc/xen/acm-security/scripts/acm_getlabel -i 0
   2.561 +  ('example.chwall.client_v1',         <--- policy describing labels etc.
   2.562 +   'dom_SystemManagement',             <--- label name of the domain
   2.563 +   'CHINESE WALL',                     <--- policy type
   2.564 +   65537)                              <--- hypervisor internal ssidref
   2.565 +
     3.1 --- a/tools/security/install.txt	Mon Apr 24 10:59:17 2006 +0100
     3.2 +++ b/tools/security/install.txt	Mon Apr 24 10:59:57 2006 +0100
     3.3 @@ -3,10 +3,11 @@
     3.4  #
     3.5  # Author:
     3.6  # Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
     3.7 +#               03/18/2006 update: new labeling
     3.8  #
     3.9  #
    3.10  # This file shows how to activate and install the access control
    3.11 -# framework.
    3.12 +# framework for Xen.
    3.13  ##
    3.14  
    3.15  
    3.16 @@ -20,43 +21,54 @@ Simple Type Enforcement policy. Some fil
    3.17  below to activate the Chinese Wall OR the Type Enforcement policy
    3.18  exclusively (chwall_ste --> {chwall, ste}).
    3.19  
    3.20 +0. build and install the xm man page. It includes the description of
    3.21 +   available management commands for the security policy for Xen and
    3.22 +   the labeling of domains. If not installed by default, you can make
    3.23 +   and install the xm man page as follows:
    3.24 +       # cd "xen_root"/doc
    3.25 +       # make install
    3.26 +   Then, use man xm to read it:
    3.27 +       # man xm
    3.28 +
    3.29  1. enable access control in Xen
    3.30         # cd "xen_root"
    3.31         # edit/xemacs/vi Config.mk
    3.32  
    3.33         change the lines:
    3.34         ACM_SECURITY ?= n
    3.35 -       ACM_DEFAULT_SECURITY_POLICY ?= ACM_NULL_POLICY
    3.36 -
    3.37         to:
    3.38         ACM_SECURITY ?= y
    3.39 +
    3.40 +       Now the hypervisor will boot into the policy that is specified
    3.41 +       in the grub configuration. If you would like to boot into a
    3.42 +       specific policy (even if you can't specify a boot policy but
    3.43 +       need to set the policy later using the 'xensec_tool
    3.44 +       loadpolicy'), then use the other config parameter to change
    3.45 +       from NULL to any other default policy, e.g.:
    3.46         ACM_DEFAULT_SECURITY_POLICY ?= ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
    3.47  
    3.48 -       # make all
    3.49 +       # make dist
    3.50         # ./install.sh
    3.51  
    3.52 -2. compile the policy from xml to a binary format that can be loaded
    3.53 -   into the hypervisor for enforcement
    3.54 +2. Build acm and policy tools and create boot-able policy:
    3.55         # cd tools/security
    3.56 -       # make
    3.57 +       # make install
    3.58  
    3.59 -       manual steps (alternative to make boot_install):
    3.60 -       # ./xensec_xml2bin -d policies/ chwall_ste
    3.61 -       # cp policies/chwall_ste/chwall_ste.bin /boot
    3.62 -       # edit /boot/grub/grub.conf
    3.63 -        add the follwoing line to your xen boot entry:
    3.64 -       "module /boot/chwall_ste.bin"
    3.65 +       For description of the following commands, please see the xm
    3.66 +       man page (docs/man1/xm.1). If it is not built, then you can
    3.67 +       create it manually: cd "xen_root"/docs; make; man man1/xm.1
    3.68  
    3.69 -       alternatively, you can try our automatic translation and
    3.70 -       installation of the policy:
    3.71 -       # make boot_install
    3.72 +       Step1: Building binary version of an example policy:
    3.73 +       # xm makepolicy example.chwall_ste.client_v1
    3.74 +       # xm cfgbootpolicy example.chwall_ste.client_v1
    3.75  
    3.76 -       [we try hard to do the right thing to the right boot entry but
    3.77 -        please verify boot entry in /boot/grub/grub.conf afterwards;
    3.78 -        your xen boot entry should have an additional module line
    3.79 -        specifying a chwall_ste.bin file with the correct directory
    3.80 -        (e.g. "/" or "/boot").]
    3.81 -
    3.82 +       Please verify boot entry in /boot/grub/grub.conf (or menu.lst):
    3.83 +        title Xen (2.6.16)
    3.84 +        root (hd0,0)
    3.85 +        kernel /xen.gz dom0_mem=2000000 console=vga
    3.86 +        module /vmlinuz-2.6.16-xen ro root=/dev/VolGroup00/LogVol00 rhgb
    3.87 +        module /initrd-2.6.165-xen-U.img
    3.88 +        module /example.chwall_ste.client_v1.bin
    3.89  
    3.90  3. reboot into the newly compiled hypervisor
    3.91  
    3.92 @@ -64,6 +76,12 @@ 3. reboot into the newly compiled hyperv
    3.93  	# xm dmesg should show an entry about the policy being loaded
    3.94              during the boot process
    3.95  
    3.96 -        # xensec_tool getpolicy
    3.97 -            should print the new chwall_ste binary policy representation
    3.98 +        # xm dumppolicy
    3.99 +            should print the new binary policy representation
   3.100 +            including the policy name example.chwall_ste.client_v1
   3.101  
   3.102 +	# xm list --label
   3.103 +	    should show security label names behind the running domains
   3.104 +
   3.105 +For more information about how to use the security-enabled Xen, see
   3.106 +the examples.txt file in this directory.
     4.1 --- a/tools/security/policy.txt	Mon Apr 24 10:59:17 2006 +0100
     4.2 +++ b/tools/security/policy.txt	Mon Apr 24 10:59:57 2006 +0100
     4.3 @@ -59,22 +59,34 @@ migrate). These controls decide based on
     4.4  configuration (see i. and ii.) if the operation proceeds of if the
     4.5  operation is aborted (denied).
     4.6  
     4.7 -
     4.8  In general, security policy instantiations in the Xen access control
     4.9 -framework are defined by two files:
    4.10 -
    4.11 -a) a single "policy-name"-security_policy.xml file that defines the
    4.12 -types known to the ACM and policy rules based on these types
    4.13 +framework are defined by XML policy files. Each security policy has
    4.14 +exactly one file including all the information the hypervisor needs to
    4.15 +enforce the policy.
    4.16  
    4.17 -b) a single "policy-name"-security_label_template.xml file that
    4.18 -defines labels based on known types
    4.19 +The name of a policy is unique and consists of a colon-separated list
    4.20 +of names, which can be translated into the location (subtree) where
    4.21 +this policy must be located. The last part of the name is the file
    4.22 +name pre-fix for the policy xml file. The preceding name parts are
    4.23 +translated into the local path relative to the global policy root
    4.24 +(/etc/xen/acm-security/policies) pointing to the policy xml file. For
    4.25 +example: example.chwall_ste.client_v1 denotes the policy file
    4.26 +example/chwall_ste/client_v1-security_policy.xml relative to the
    4.27 +global policy root directory.
    4.28  
    4.29 -Every security policy has its own sub-directory under
    4.30 -"Xen-root"/tools/security/policies in order to simplify their
    4.31 -management and the security policy tools. We will describe those files
    4.32 -for our example policy (Chinese Wall and Simple Type Enforcement) in
    4.33 -more detail as we go along. Eventually, we will move towards a system
    4.34 -installation where the policies will reside under /etc.
    4.35 +Every security policy has its own sub-directory under the global
    4.36 +policy root directory /etc/xen/acm-security/policies, which is
    4.37 +installed during the Xen installation or can be manually installed
    4.38 +(when switching from a "security disabled" Xen to a "security enabled"
    4.39 +Xen AFTER configuring security, see install.txt) by the command
    4.40 +sequence:
    4.41 +
    4.42 +   cd "Xen-root"/tools/security/policies; make install
    4.43 +
    4.44 +We will describe those files for our example policy (Chinese Wall and
    4.45 +Simple Type Enforcement) in more detail as we go along. Eventually, we
    4.46 +will move towards a system installation where the policies will reside
    4.47 +under /etc.
    4.48  
    4.49  
    4.50  CHINESE WALL
    4.51 @@ -117,9 +129,9 @@ constraints where necessary.
    4.52  Example of a Chinese Wall Policy Instantiation
    4.53  ----------------------------------------------
    4.54  
    4.55 -The file chwall-security_policy.xml defines the Chinese Wall types as
    4.56 -well as the conflict sets for our example policy (you find it in the
    4.57 -directory "xen_root"/tools/security/policies/chwall).
    4.58 +The file client_v1-security_policy.xml defines the Chinese Wall types
    4.59 +as well as the conflict sets for our example policy (you find it in
    4.60 +the directory "policy_root"/example/chwall).
    4.61  
    4.62  It defines four Chinese Wall types (prefixed with cw_) with the
    4.63  following meaning:
    4.64 @@ -168,11 +180,11 @@ policy.
    4.65  SIMPLE TYPE ENFORCEMENT
    4.66  =======================
    4.67  
    4.68 -The file ste-security_policy.xml defines the simple type enforcement
    4.69 -types for our example policy (you find it in the directory
    4.70 -"xen_root"/tools/security/policies/ste). The Simple Type Enforcement
    4.71 -policy defines which domains can share information with which other
    4.72 -domains. To this end, it controls
    4.73 +The file client_v1-security_policy.xml defines the simple type
    4.74 +enforcement types for our example policy (you find it in the directory
    4.75 +"policy_root"/example/ste). The Simple Type Enforcement policy defines
    4.76 +which domains can share information with which other domains. To this
    4.77 +end, it controls
    4.78  
    4.79  i) inter-domain communication channels (e.g., network traffic, events,
    4.80  and shared memory).
     5.1 --- a/tools/security/readme.txt	Mon Apr 24 10:59:17 2006 +0100
     5.2 +++ b/tools/security/readme.txt	Mon Apr 24 10:59:57 2006 +0100
     5.3 @@ -10,20 +10,25 @@
     5.4  # the access control policy and tools in Xen.
     5.5  ##
     5.6  
     5.7 -1. policy.txt:
     5.8 +1. 'xm' man page
     5.9 +
    5.10 +   describes the commands related to Xen management, including the
    5.11 +   commands to manage security policies and labels. Read the access
    5.12 +   control subcommand section of the xm manual first. If it is not
    5.13 +   built by default, check install.txt.
    5.14 +
    5.15 +2. policy.txt:
    5.16  
    5.17     describes the general reasoning and examples for access
    5.18     control policies in Xen
    5.19  
    5.20  
    5.21 -2. install.txt
    5.22 +3. install.txt
    5.23  
    5.24     describes the activation of the access control framework
    5.25     in Xen
    5.26  
    5.27 -3. example.txt
    5.28 +4. example.txt
    5.29  
    5.30     describes the available tools for managing security policies
    5.31     in Xen and the tools to label domains
    5.32 -
    5.33 -