ia64/xen-unstable

changeset 11919:16f1f8ac8902

[ACM] Documentation cleanup.

This patch eliminates redundant security tools information that was
integrated into the Xen user guide and the xm man page.

Signed-off by: Reiner Sailer <sailer@us.ibm.com>
author kfraser@localhost.localdomain
date Fri Oct 20 10:48:34 2006 +0100 (2006-10-20)
parents 6677b97612a2
children dde8c8038e17
files tools/security/example.txt tools/security/install.txt tools/security/policy.txt tools/security/policytools.txt tools/security/readme.txt
line diff
     1.1 --- a/tools/security/example.txt	Fri Oct 20 10:46:37 2006 +0100
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,376 +0,0 @@
     1.4 -##
     1.5 -# example.txt <description to the xen access control architecture>
     1.6 -#
     1.7 -# Author:
     1.8 -# Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
     1.9 -#               04/07/2006 update to using labels instead of ssidref
    1.10 -#
    1.11 -#
    1.12 -# This file introduces into the tools to manage policies
    1.13 -# and to label domains and resources.
    1.14 -##
    1.15 -
    1.16 -We will show how to install and use the example one of the client_v1
    1.17 -policies. Other policies work similarly. Feedback welcome!
    1.18 -
    1.19 -
    1.20 -
    1.21 -1. Using xm tools to translate example.chwall_ste.client_v1 policy:
    1.22 -===================================================================
    1.23 -
    1.24 -#xm makepolicy example.chwall_ste.client_v1
    1.25 -
    1.26 -By default, the tool looks in directory /etc/xen/acm-security/policies
    1.27 -for a directory that matches the policy name
    1.28 -(here:example/chwall_ste/client_v1-security_policy.xml) to find the
    1.29 -policy files.  The '-d' option can be used to override the default
    1.30 -/etc/xen/acm-security/policies policy-root directory.
    1.31 -
    1.32 -The default policy directory structure under /etc/xen/acm-security (and
    1.33 -the Xen security tool build directory - tools/security) looks like:
    1.34 -
    1.35 -policies
    1.36 -|-- security_policy.xsd
    1.37 -|-- example
    1.38 -    |-- chwall
    1.39 -    |   |-- client_v1-security_policy.xml
    1.40 -    |
    1.41 -    |-- chwall_ste
    1.42 -    |   |-- client_v1-security_policy.xml
    1.43 -    |
    1.44 -    |-- ste
    1.45 -        |-- client_v1-security_policy.xml
    1.46 -
    1.47 -The security_policy.xsd file contains the schema against which the
    1.48 -policy files must validate during translation.
    1.49 -
    1.50 -The policy files, ending in -security_policy.xml, define the policies,
    1.51 -the types known to the policies, and the label definitions that group
    1.52 -types together and make them easier to use for users.
    1.53 -
    1.54 -After executing the above 'xm makepolicy' command, you will find 2 new
    1.55 -files in the /etc/xen/acm-security/policies/example/chwall_ste
    1.56 -sub-directory:
    1.57 -
    1.58 -  client_v1.map ... this file includes the mapping
    1.59 -    of names from the xml files into their binary code representation.
    1.60 -
    1.61 -  client_v1.bin ... this is the binary policy file, the result of
    1.62 -    parsing the xml files and using the mapping to create a binary
    1.63 -    version that can be loaded into the hypervisor.
    1.64 -
    1.65 -
    1.66 -
    1.67 -2. Loading and activating the policy:
    1.68 -=====================================
    1.69 -
    1.70 -We assume that xen is already configured for security;
    1.71 -please refer to install.txt for instructions.
    1.72 -
    1.73 -To activate the policy from the command line:
    1.74 -
    1.75 -# xm loadpolicy example.chwall_ste.client_v1
    1.76 -
    1.77 -See install.txt for how to install a policy at boot time. This the
    1.78 -recommended default. You can only load a policy if the currently
    1.79 -enforced policy is "DEFAULT", a minimal startup policy, or if the
    1.80 -currently enforced policy has the same name as the new one. Support
    1.81 -for dynamic policy changes at run-time are a current working item.
    1.82 -
    1.83 -
    1.84 -3. Labeling domains:
    1.85 -====================
    1.86 -
    1.87 -a) Labeling Domain0:
    1.88 -
    1.89 -The chwall_ste-security_label_template.xml file includes an attribute
    1.90 -"bootstrap", which is set to the label name that will be assigned to
    1.91 -Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).
    1.92 -
    1.93 -b) Labeling User Domains (domains started from dom0 using xm commands):
    1.94 -
    1.95 -We distinguish two kinds of labels: a) VM labels (for domains) and RES
    1.96 -Labels (for resources). We focus here on VM labels. Resource labels
    1.97 -will be supported later.
    1.98 -
    1.99 -To list all available domain labels of a policy, use:
   1.100 -   #xm labels example.chwall_ste.client_v1
   1.101 -
   1.102 -To list all available labels including resource labels (their support
   1.103 -is current work), use:
   1.104 -
   1.105 -   #xm labels example.chwall_ste.client_v1 type=any
   1.106 -
   1.107 -The policy parameter is optional. The currently enforced hypervisor
   1.108 -policy is used by default.
   1.109 -
   1.110 -If you would like to assign the dom_HomeBanking label to one of your user domains,
   1.111 -look at the hypothetical domain configuration contained in /etc/xen/homebanking.xm:
   1.112 -
   1.113 -    #------FOR HOME/ONLINE BANKING---------
   1.114 -    kernel = "/boot/vmlinuz-2.6.16-xen"
   1.115 -    ramdisk="/boot/U1_ramdisk.img"
   1.116 -    memory = 164
   1.117 -    name = "homebanking"
   1.118 -    vif=['']
   1.119 -    dhcp = "dhcp"
   1.120 -    #-------------------------
   1.121 -
   1.122 -Now we label this domain (policy name is optional, see above):
   1.123 -
   1.124 -    # xm addlabel homebanking.xm dom_HomeBanking example.chwall_ste.client_v1
   1.125 -
   1.126 -The domain configuration should look now like:
   1.127 -
   1.128 -    # cat homebanking.xm
   1.129 -    #------FOR HOME/ONLINE BANKING---------
   1.130 -    kernel = "/boot/vmlinuz-2.6.16-xen"
   1.131 -    ramdisk="/boot/U1_ramdisk.img"
   1.132 -    memory = 164
   1.133 -    name = "homebanking"
   1.134 -    vif=['']
   1.135 -    dhcp = "dhcp"
   1.136 -    access_control = ['policy=example.chwall_ste.client_v1, label=dom_HomeBanking']
   1.137 -
   1.138 -You can see the access_control line that was added to the
   1.139 -configuration. This label will be translated into a local ssidref when
   1.140 -a domain is created or resumed (also after migration and
   1.141 -live-migration). The ssidref is a local security reference that is
   1.142 -used inside the hypervisor instead of the security label for
   1.143 -efficiency reasons. Since the same label can be mapped onto different
   1.144 -ssidrefs in different policy translations (e.g., if the position of
   1.145 -the label definition is changed in the policy file) or on different
   1.146 -systems, the ssidref is re-calculated from the label each time a
   1.147 -domain is instantiated or re-instantiated.
   1.148 -
   1.149 -Currently, the labels are not held in the hypervisor but only in
   1.150 -.map files in the /etc/xen/acm-security/policies subdirectories. Only
   1.151 -ssidrefs are known inside the hypervisr. This of course can change in
   1.152 -the future.
   1.153 -
   1.154 -
   1.155 -4. Starting a labeled domain
   1.156 -============================
   1.157 -
   1.158 -Now, start the domain:
   1.159 -
   1.160 -    #xm create homebanking.xm
   1.161 -    Using config file "homebanking.xm".
   1.162 -    Started domain fun
   1.163 -
   1.164 -
   1.165 -[root@941e-4 VMconfigs]# xm list --label
   1.166 -
   1.167 -Name         ID Mem(MiB) VCPUs State  Time(s)  Label
   1.168 -fun           1       64     1 -b----     5.9  dom_HomeBanking
   1.169 -Domain-0      0     1954     1 r-----  1321.4  dom_SystemManagement
   1.170 -
   1.171 -
   1.172 -
   1.173 -If you label another domain configuration as dom_Fun and if
   1.174 -you try to start it afterwards, this create will fail.
   1.175 -
   1.176 -Why? -- Because the running 'homebanking' domain has the chinese
   1.177 -wall type "cw_Sensitive". The new domain 'fun' has the chinese wall
   1.178 -label "cw_Distrusted". These domains are not allowed to run simultaneously
   1.179 -on the same system because of the defined conflict set
   1.180 -
   1.181 -			<conflictset name="Protection1">
   1.182 -				<type>cw_Sensitive</type>
   1.183 -				<type>cw_Distrusted</type>
   1.184 -			</conflictset>
   1.185 -
   1.186 -(in client_v1-security_policy.xml), which says that only one of the
   1.187 -types cw_Sensitive and cw_Distrusted can run at a time.
   1.188 -
   1.189 -If you save or shutdown the 'homebanking' domain, you will be able to
   1.190 -start the 'fun' domain. You can look into the Xen log to see if a
   1.191 -domain was denied to start because of the access control framework
   1.192 -with the command 'xm dmesg'.
   1.193 -
   1.194 -It is important (and usually non-trivial) to define the labels in a
   1.195 -way that the semantics of the labels are enforced and supported by the
   1.196 -types and the conflict sets. Usually, a workload abstraction seems
   1.197 -helpful on the hypervisor level.
   1.198 -
   1.199 -Note: While the chinese wall policy enforcement is complete, the type
   1.200 -enforcement is currently enforced inside the Xen hypervisor
   1.201 -only. Therefore, only point-to-point sharing with regard to the type
   1.202 -enforcement is currently controlled. Enforcing the STE policy while
   1.203 -sharing virtual resources is ongoing work and assumed to be complete
   1.204 -by year end as well as enforcing the STE policy for network traffic
   1.205 -routed through dom0.
   1.206 -
   1.207 -
   1.208 -5. Adding your own policies
   1.209 -===========================
   1.210 -
   1.211 -Writing your own policy (e.g. "mypolicy.chwall.test") requires the policy
   1.212 -definition (types etc.) and the label definitions. Any policy name
   1.213 -must have chwall, ste, or chwall_ste in its name. This is used by the
   1.214 -configuration tool to identify existing binary policy entries in the
   1.215 -boot configuration file (menu.lst, grub.con). This part should, of
   1.216 -course, be consistent with policy type that is defined.
   1.217 -
   1.218 -First, you create
   1.219 -/etc/xen/acm-security/policies/mypolicy/chwall/test-security_policy.xml.
   1.220 -
   1.221 -You need to keep to the schema as defined in
   1.222 -/etc/xen/acm-security/security_policy.xsd since the translation tools
   1.223 -are written against this schema.
   1.224 -
   1.225 -You can hand-edit the xml files to create your policy or you can use the
   1.226 -xensec_gen utility.
   1.227 -
   1.228 -
   1.229 -6. Generating policy files using xensec_gen:
   1.230 -============================================
   1.231 -
   1.232 -The xensec_gen utility starts a web-server that can be used to generate the
   1.233 -XML policy files needed to create a policy.
   1.234 -
   1.235 -By default, xensec_gen runs as a daemon and listens on port 7777 for HTTP
   1.236 -requests.  The xensec_gen command supports command line options to change the
   1.237 -listen port, run in the foreground, and a few others.  Type 'xensec_gen -h'
   1.238 -to see the full list of options available.
   1.239 -
   1.240 -Once the xensec_gen utility is running, point a browser at the host and port
   1.241 -on which the utility is running (e.g. http://localhost:7777/).  You will be
   1.242 -presented with a web page that allows you to create or modify the XML policy
   1.243 -file:
   1.244 -
   1.245 -  - The Security Policy types section allows you to create or modify
   1.246 -    the policy types and conflict set definitions
   1.247 -
   1.248 -  - The Security Policy Labeling section allows you to create or modify a
   1.249 -    label definitions
   1.250 -
   1.251 -The policy generation tool allows you to modify an existing policy
   1.252 -definition or create a new policy definition file. To modify an
   1.253 -existing policy definition, enter the full path to the existing file
   1.254 -(the "Browse" button can be used to aid in this) in the Policy File
   1.255 -entry field.  To create a new policy definition file leave the Policy
   1.256 -File entry field blank.  At this point click the "Create" button to
   1.257 -begin modifying or creating your policy definition.
   1.258 -
   1.259 -  Security Policy Types Section
   1.260 -  -----------------------------
   1.261 -
   1.262 -You will then be presented with a web page. The upper part of it will
   1.263 -allow you to create either Simple Type Enforcement types or Chinese
   1.264 -Wall types or both, as well as Chinese Wall conflict type sets.
   1.265 -
   1.266 -  As an example:
   1.267 -    - To add a Simple Type Enforcement type:
   1.268 -      - Enter the name of a new type under the Simple Type Enforcement Types
   1.269 -        section in the entry field above the "New" button.
   1.270 -      - Click the "New" button and the type will be added to the list of defined
   1.271 -        Simple Type Enforcement types.
   1.272 -    - To remove a Simple Type Enforcement type:
   1.273 -      - Click on the type to be removed in the list of defined Simple Type
   1.274 -        Enforcement types.
   1.275 -      - Click the "Delete" button to remove the type.
   1.276 -
   1.277 -  Follow the same process to add Chinese Wall types.  If you define Chinese Wall
   1.278 -  types you need to define at least one Chinese Wall Conflict Set.  The Chinese
   1.279 -  Wall Conflict Set will allow you to add Chinese Wall types from the list of
   1.280 -  defined Chinese Wall types.
   1.281 -
   1.282 -  Security Policy Labeling:
   1.283 -  -------------------------
   1.284 -
   1.285 -  The security policy label section of the web page allows you to create labels
   1.286 -  for classes of virtual machines.  The input policy type definitions on the upper
   1.287 -  part of the web page will provide the available types (Simple Type Enforcement
   1.288 -  and/or Chinese Wall) that can be assigned to a virtual machine class.
   1.289 -
   1.290 -  As an example:
   1.291 -    - To add a Virtual Machine class (the name entered will become the label
   1.292 -      that will be used to identify the class):
   1.293 -      - Enter the name of a new class under the Virtual Machine Classes section
   1.294 -        in the entry field above the "New" button.
   1.295 -      - Click the "New" button and the class will be added to the table of defined
   1.296 -        Virtual Machine classes.
   1.297 -    - To remove a Virtual Machine class:
   1.298 -      - Click the "Delete" link associated with the class in the table of Virtual
   1.299 -        Machine classes.
   1.300 -
   1.301 -  Once you have defined one or more Virtual Machine classes, you will be able to
   1.302 -  add any of the defined Simple Type Enforcement types or Chinese Wall types to a
   1.303 -  particular Virtual Machine.
   1.304 -
   1.305 -  You must also define which Virtual Machine class is to be associated with the
   1.306 -  bootstrap domain (or Dom0 domain).  By default, the first Virtual Machine class
   1.307 -  created will be associated as the bootstrap domain.
   1.308 -
   1.309 -  To save your policy definition file, click on the "Generate XML" button
   1.310 -  on the top of the page.  This will present you with a dialog box to save the
   1.311 -  generated XML file on your system.  The default name will be
   1.312 -  security_policy.xml which you should change to follow the policy file
   1.313 -  naming conventions based on the policy name that you choose to use.
   1.314 -
   1.315 -  To get a feel for the tool, you could use one of the example policy definitions
   1.316 -  files from /etc/xen/acm-security/policies/example as input.
   1.317 -
   1.318 -
   1.319 -7. Hypervisor - OS Security Interface
   1.320 -=====================================
   1.321 -
   1.322 -We currently provide 2 hypercalls through which user operating systems
   1.323 -can interact with the hypervisor Access Control Module. Examples of
   1.324 -using them are under "xen_root"/tools/security/python/xensec_tools:
   1.325 -
   1.326 -
   1.327 -I) acm_getdecision -i domainid -l labelname
   1.328 -   Call this example script without arguments to show its usage
   1.329 -   information.
   1.330 -
   1.331 -   This script enables a domain to retrieve an access control decision
   1.332 -   regarding the STE policy from the hypervisor. It will be used to
   1.333 -   control access to virtual/real resources in hosting domains.
   1.334 -
   1.335 -   The script can be provided with any combination of domain ids or
   1.336 -   labelnames. Before calling into the hypervisor, labels are translated
   1.337 -   into ssidrefs. The hypervisor then retrieves for any domain id
   1.338 -   paramter the ssidref before deciding access.
   1.339 -
   1.340 -   Example:
   1.341 -   #/etc/xen/acm-security/scripts/acm_getdecision -l dom_Fun
   1.342 -						 -l dom_SystemManagement
   1.343 -   PERMITTED
   1.344 -
   1.345 -   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -i 1
   1.346 -   PERMITTED
   1.347 -
   1.348 -   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l dom_Fun
   1.349 -   PERMITTED
   1.350 -
   1.351 -   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l no_label
   1.352 -   ACMError: Label 'nolabel' not found.
   1.353 -
   1.354 -   Now, assume domain 123454 does not exist:
   1.355 -   #/etc/xen/acm-security/scripts/acm_getdecision -i 123454 -l dom_Fun
   1.356 -   ACMError: Cannot determine decision (Invalid parameter).
   1.357 -
   1.358 -   Return values:
   1.359 -            * DENIED: access is denied based on the current hypervisor
   1.360 -                      policy
   1.361 -
   1.362 -            * PERMITTED: access is permitted based on the current
   1.363 -
   1.364 -            * Exception ACMError: one of the parameters was illegal,
   1.365 -                                  i.e. an unknown label or a
   1.366 -                                  non-existing domain id
   1.367 -
   1.368 -I) acm_getlabel -i domainid
   1.369 -   Retrieves the label of a runing domain. This function can be used
   1.370 -   by domains to determine their own label or (if authorized) the label
   1.371 -   other domains.
   1.372 -
   1.373 -   Example (result is broken up into different lines to simplify description):
   1.374 -   # /etc/xen/acm-security/scripts/acm_getlabel -i 0
   1.375 -  ('example.chwall.client_v1',         <--- policy describing labels etc.
   1.376 -   'dom_SystemManagement',             <--- label name of the domain
   1.377 -   'CHINESE WALL',                     <--- policy type
   1.378 -   65537)                              <--- hypervisor internal ssidref
   1.379 -
     2.1 --- a/tools/security/install.txt	Fri Oct 20 10:46:37 2006 +0100
     2.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.3 @@ -1,87 +0,0 @@
     2.4 -##
     2.5 -# install.txt <description to the xen access control architecture>
     2.6 -#
     2.7 -# Author:
     2.8 -# Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
     2.9 -#               03/18/2006 update: new labeling
    2.10 -#
    2.11 -#
    2.12 -# This file shows how to activate and install the access control
    2.13 -# framework for Xen.
    2.14 -##
    2.15 -
    2.16 -
    2.17 -INSTALLING A SECURITY POLICY IN XEN
    2.18 -===================================
    2.19 -
    2.20 -By default, the access control architecture is disabled in Xen. To
    2.21 -enable the access control architecture in Xen follow the steps below.
    2.22 -This description assumes that you want to install the Chinese Wall and
    2.23 -Simple Type Enforcement policy. Some file names need to be replaced
    2.24 -below to activate the Chinese Wall OR the Type Enforcement policy
    2.25 -exclusively (chwall_ste --> {chwall, ste}).
    2.26 -
    2.27 -0. build and install the xm man page. It includes the description of
    2.28 -   available management commands for the security policy for Xen and
    2.29 -   the labeling of domains. If not installed by default, you can make
    2.30 -   and install the xm man page as follows:
    2.31 -       # cd "xen_root"/doc
    2.32 -       # make install
    2.33 -   Then, use man xm to read it:
    2.34 -       # man xm
    2.35 -
    2.36 -1. enable access control in Xen
    2.37 -       # cd "xen_root"
    2.38 -       # edit/xemacs/vi Config.mk
    2.39 -
    2.40 -       change the lines:
    2.41 -       ACM_SECURITY ?= n
    2.42 -       to:
    2.43 -       ACM_SECURITY ?= y
    2.44 -
    2.45 -       Now the hypervisor will boot into the policy that is specified
    2.46 -       in the grub configuration. If you would like to boot into a
    2.47 -       specific policy (even if you can't specify a boot policy but
    2.48 -       need to set the policy later using the 'xensec_tool
    2.49 -       loadpolicy'), then use the other config parameter to change
    2.50 -       from NULL to any other default policy, e.g.:
    2.51 -       ACM_DEFAULT_SECURITY_POLICY ?= ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY
    2.52 -
    2.53 -       # make dist
    2.54 -       # ./install.sh
    2.55 -
    2.56 -2. Build acm and policy tools and create boot-able policy:
    2.57 -       # cd tools/security
    2.58 -       # make install
    2.59 -
    2.60 -       For description of the following commands, please see the xm
    2.61 -       man page (docs/man1/xm.1). If it is not built, then you can
    2.62 -       create it manually: cd "xen_root"/docs; make; man man1/xm.1
    2.63 -
    2.64 -       Step1: Building binary version of an example policy:
    2.65 -       # xm makepolicy example.chwall_ste.client_v1
    2.66 -       # xm cfgbootpolicy example.chwall_ste.client_v1
    2.67 -
    2.68 -       Please verify boot entry in /boot/grub/grub.conf (or menu.lst):
    2.69 -        title Xen (2.6.16)
    2.70 -        root (hd0,0)
    2.71 -        kernel /xen.gz dom0_mem=2000000 console=vga
    2.72 -        module /vmlinuz-2.6.16-xen ro root=/dev/VolGroup00/LogVol00 rhgb
    2.73 -        module /initrd-2.6.165-xen-U.img
    2.74 -        module /example.chwall_ste.client_v1.bin
    2.75 -
    2.76 -3. reboot into the newly compiled hypervisor
    2.77 -
    2.78 -        after boot
    2.79 -	# xm dmesg should show an entry about the policy being loaded
    2.80 -            during the boot process
    2.81 -
    2.82 -        # xm dumppolicy
    2.83 -            should print the new binary policy representation
    2.84 -            including the policy name example.chwall_ste.client_v1
    2.85 -
    2.86 -	# xm list --label
    2.87 -	    should show security label names behind the running domains
    2.88 -
    2.89 -For more information about how to use the security-enabled Xen, see
    2.90 -the examples.txt file in this directory.
     3.1 --- a/tools/security/policy.txt	Fri Oct 20 10:46:37 2006 +0100
     3.2 +++ b/tools/security/policy.txt	Fri Oct 20 10:48:34 2006 +0100
     3.3 @@ -1,131 +1,13 @@
     3.4  ##
     3.5 -# policy.txt <description to the Xen access control architecture>
     3.6 +# policy.txt <description to the sHype/Xen access control architecture>
     3.7  #
     3.8  # Author:
     3.9 -# Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
    3.10 +# Reiner Sailer 08/30/2006 <sailer@watson.ibm.com>
    3.11  #
    3.12  #
    3.13 -# This file gives an overview of the security policies currently
    3.14 -# provided and also gives some reasoning about how to assign
    3.15 -# labels to domains.
    3.16 +# This file gives an overview of the example security policies.
    3.17  ##
    3.18  
    3.19 -Xen access control policies
    3.20 -
    3.21 -
    3.22 -General explanation of supported security policies:
    3.23 -=====================================================
    3.24 -
    3.25 -We have implemented the mandatory access control architecture of our
    3.26 -hypervisor security architecture (sHype) for the Xen hypervisor. It
    3.27 -controls communication (in Xen: event channels, grant tables) between
    3.28 -Virtual Machines (from here on called domains) and through this the
    3.29 -virtual block devices, networking, and shared memory are implemented
    3.30 -on top of these communication means. While we have implemented the
    3.31 -described policies and access control architecture for other
    3.32 -hypervisor systems, we will describe below specifically its
    3.33 -implementation and use in the Xen hypervisor. The policy enforcement
    3.34 -is called mandatory regarding user domains since the policy it is
    3.35 -given by the security administration and enforced independently of the
    3.36 -user domains by the Xen hypervisor in cooperation with the domain
    3.37 -management.
    3.38 -
    3.39 -The access control architecture consists of three parts:
    3.40 -
    3.41 -i) The access control policy determines the "command set" of the ACM
    3.42 -and the hooks with which they can be configured to constrain the
    3.43 -sharing of virtual resources. The current access control architecture
    3.44 -implemented for Xen supports two policies: Chinese Wall and Simple
    3.45 -Type Enforcement, which we describe in turn below.
    3.46 -
    3.47 -
    3.48 -ii) The actually enforced policy instantiation uses the policy
    3.49 -language (i) to configure the Xen access control in a way that suits
    3.50 -the specific application (home desktop environment, company desktop,
    3.51 -Web server system, etc.). We have defined an exemplary policy
    3.52 -instantiation for Chinese Wall (chwall policy) and Simple Type
    3.53 -Enforcement (ste policy) for a desktop system. We offer these policies
    3.54 -in combination since they are controlling orthogonal events.
    3.55 -
    3.56 -
    3.57 -iii) The access control module (ACM) and related hooks are part of the
    3.58 -core hypervisor and their controls cannot be bypassed by domains. The
    3.59 -ACM and hooks are the active security components. We refer to
    3.60 -publications that describe how access control is enforced in the Xen
    3.61 -hypervisor using the ACM (access decision) and the hooks (decision
    3.62 -enforcement) inserted into the setup of event channels and grant
    3.63 -tables, and into domain operations (create, destroy, save, restore,
    3.64 -migrate). These controls decide based on the active policy
    3.65 -configuration (see i. and ii.) if the operation proceeds of if the
    3.66 -operation is aborted (denied).
    3.67 -
    3.68 -In general, security policy instantiations in the Xen access control
    3.69 -framework are defined by XML policy files. Each security policy has
    3.70 -exactly one file including all the information the hypervisor needs to
    3.71 -enforce the policy.
    3.72 -
    3.73 -The name of a policy is unique and consists of a colon-separated list
    3.74 -of names, which can be translated into the location (subtree) where
    3.75 -this policy must be located. The last part of the name is the file
    3.76 -name pre-fix for the policy xml file. The preceding name parts are
    3.77 -translated into the local path relative to the global policy root
    3.78 -(/etc/xen/acm-security/policies) pointing to the policy xml file. For
    3.79 -example: example.chwall_ste.client_v1 denotes the policy file
    3.80 -example/chwall_ste/client_v1-security_policy.xml relative to the
    3.81 -global policy root directory.
    3.82 -
    3.83 -Every security policy has its own sub-directory under the global
    3.84 -policy root directory /etc/xen/acm-security/policies, which is
    3.85 -installed during the Xen installation or can be manually installed
    3.86 -(when switching from a "security disabled" Xen to a "security enabled"
    3.87 -Xen AFTER configuring security, see install.txt) by the command
    3.88 -sequence:
    3.89 -
    3.90 -   cd "Xen-root"/tools/security/policies; make install
    3.91 -
    3.92 -We will describe those files for our example policy (Chinese Wall and
    3.93 -Simple Type Enforcement) in more detail as we go along. Eventually, we
    3.94 -will move towards a system installation where the policies will reside
    3.95 -under /etc.
    3.96 -
    3.97 -
    3.98 -CHINESE WALL
    3.99 -============
   3.100 -
   3.101 -The Chinese Wall policy enables the user to define "which workloads
   3.102 -(domain payloads) cannot run on a single physical system at the same
   3.103 -time". Why would we want to prevent workloads from running at the same
   3.104 -time on the same system? This supports requirements that can (but
   3.105 -don't have to) be rooted in the measure of trust into the isolation of
   3.106 -different domains that share the same hardware. Since the access
   3.107 -control architecture aims at high performance and non-intrusive
   3.108 -implementation, it currently does not address covert (timing) channels
   3.109 -and aims at medium assurance. Users can apply the Chinese Wall policy
   3.110 -to guarantee an air-gap between very sensitive payloads both regarding
   3.111 -covert information channels and regarding resource starvation.
   3.112 -
   3.113 -To enable the CW control, each domain is labeled with a set of Chinese
   3.114 -Wall types and CW Conflict Sets are defined which include those CW
   3.115 -types that cannot run simultaneously on the same hardware. This
   3.116 -interpretation of conflict sets is the only policy rule for the Chines
   3.117 -Wall policy.
   3.118 -
   3.119 -This is enforced by controlling the start of domains according to
   3.120 -their assigned CW worload types. Domains with Chinese Wall types that
   3.121 -appear in a common conflict set are running mutually exclusive on a
   3.122 -platform, i.e., once a domain with one of the cw-types of a conflict
   3.123 -set is running, no domain with another cw-type of the same conflict
   3.124 -set can start until the first domain is destroyed, paused, or migrated
   3.125 -away from the physical system (this assumes that such a partition can
   3.126 -no longer be observed). The idea is to assign cw-types according to
   3.127 -the type of payload that a domain runs and to use the Chinese Wall
   3.128 -policy to ensure that payload types can be differentiated by the
   3.129 -hypervisor and can be prevented from being executed on the same system
   3.130 -at the same time. Using the flexible CW policy maintains system
   3.131 -consolidation and workload-balancing while introducing guaranteed
   3.132 -constraints where necessary.
   3.133 -
   3.134 -
   3.135  Example of a Chinese Wall Policy Instantiation
   3.136  ----------------------------------------------
   3.137  
   3.138 @@ -233,13 +115,12 @@ Currently in Xen, Dom0 controls all hard
   3.139  with all domains during their setup, and intercepts all communication
   3.140  between domains. Consequently, Dom0 needs to be assigned all types
   3.141  used and must be completely trusted to maintain the separation of
   3.142 -informatio ncoming from domains with different STE types. Thus a
   3.143 +information coming from domains with different STE types. Thus a
   3.144  refactoring of Dom0 is recommended for stronger confinement
   3.145  guarantees.
   3.146  
   3.147  Domain --> RESOURCES Access
   3.148  '''''''''''''''''''''''''''
   3.149 -(current work)
   3.150  
   3.151  We define for each resource that we want to distinguish a separate STE
   3.152  type. Each STE type is assigned to the respective resource and to
   3.153 @@ -266,8 +147,7 @@ maximum security benefit from sHype.
   3.154  
   3.155  Example of a Simple Type Enforcement Policy Instantiation
   3.156  ---------------------------------------------------------
   3.157 -
   3.158 -We define the following types:
   3.159 +The example policies define the following types:
   3.160  
   3.161  * ste_SystemManagement identifies workloads (and domains that runs
   3.162  them) that must share information to accomplish the management of the
   3.163 @@ -384,19 +264,18 @@ Xen components and these components use 
   3.164  co-operatively enforce the policy. In the storage domain example, we
   3.165  have three components that co-operate:
   3.166  
   3.167 -1. The ACM module inside the hypervisor enforces: communication between
   3.168 -user domains and the storage domain (only domains including types
   3.169 -ste_PersonalFinances or ste_InternetInsecure can communicate with the
   3.170 -storage domain and request access to logical resource). This confines
   3.171 -the sharing to the types assigned to the storage domain.
   3.172 +1. The ACM module inside the hypervisor enforces: communication
   3.173 +between user domains and the storage domain (only domains including
   3.174 +types ste_PersonalFinances or ste_InternetInsecure can communicate
   3.175 +with the storage domain and request access to logical resource). This
   3.176 +confines the sharing to the types assigned to the storage domain.
   3.177  
   3.178 -2. The domain management will enforce (work in progress): assignment of
   3.179 -real resources (hda) to domains (storage domain) that share a
   3.180 -type with the resource.
   3.181 +2. The domain management enforces: assignment of real resources (hda)
   3.182 +to domains (storage domain) that share a type with the resource.
   3.183  
   3.184 -3. If the storage domain serves multiple STE types (as in our example),
   3.185 -it enforces (work in progress): that domains can access (mount)
   3.186 -logical resources only if they share an STE type with the respective
   3.187 +3. If the storage domain serves multiple STE types (as in our
   3.188 +example), it enforces: that domains can access (mount) logical
   3.189 +resources only if they share an STE type with the respective
   3.190  resource. In our example, domains with the STE type
   3.191  ste_PersonalFinances can request access (mount) to logical resource
   3.192  hda1 from the storage domain.
   3.193 @@ -406,8 +285,8 @@ see the minimal set of types assigned to
   3.194  drive hda for serving logical disk partitions exclusively to
   3.195  dom_HomeBanking and dom_Fun.
   3.196  
   3.197 -Similary, network domains can confine access to the network or
   3.198 -network communication between user domains.
   3.199 +Similary, network domains can confine access to the network or network
   3.200 +communication between user domains.
   3.201  
   3.202  As a result, device domains (e.g., storage domain, network domain)
   3.203  must be simple and small to ensure their correct co-operation in the
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/tools/security/policytools.txt	Fri Oct 20 10:48:34 2006 +0100
     4.3 @@ -0,0 +1,148 @@
     4.4 +##
     4.5 +# policytools.txt
     4.6 +#      <description to the sHype/Xen policy management tools>
     4.7 +#
     4.8 +# Author:
     4.9 +# Reiner Sailer 08/31/2006 <sailer@watson.ibm.com>
    4.10 +#
    4.11 +#
    4.12 +##
    4.13 +
    4.14 +This file describes the Xen-tools to create and maintain security
    4.15 +policies for the sHype/Xen access control module.
    4.16 +
    4.17 +A security policy (e.g. "example.chwall_ste.test") is defined in
    4.18 +XML. Read in the user manual about the naming of policies. The policy
    4.19 +name is used by the Xen management tools to identify existing
    4.20 +policies. Creating the security policy means creating a policy
    4.21 +description in XML:
    4.22 +/etc/xen/acm-security/policies/example/chwall_ste/test-security_policy.xml.
    4.23 +
    4.24 +The policy XML description must follow the XML schema definition in
    4.25 +/etc/xen/acm-security/policies/security_policy.xsd. The policy tools
    4.26 +are written against this schema; they will create and refine policies
    4.27 +that conform to this scheme.
    4.28 +
    4.29 +Two tools are provided to help creating security policies:
    4.30 +
    4.31 +
    4.32 +1. xensec_ezpolicy: The starting point for writing security policies.
    4.33 +===================
    4.34 +
    4.35 +This wxPython-based GUI tool is meant to create very quickly a
    4.36 +starting point for a workload protection security policy. Please start
    4.37 +the tool (xensec_ezpolicy) and press <CTRL-h> for usage explanations.
    4.38 +The Xen User guide explains its usage at an example in chapter
    4.39 +"sHype/Xen Access Control".
    4.40 +
    4.41 +The output of the tool is a security policy that is fully operable. It
    4.42 +is sufficient to create policies that demonstrate how sHype/ACM works.
    4.43 +
    4.44 +However, it defines only a basic set of security labels assuming that
    4.45 +Domain0 hosts and virtualizes all hardware (storage etc.). Use
    4.46 +xensec_gen to refine this policy and tailor it to your requirements.
    4.47 +
    4.48 +
    4.49 +2. xensec_gen: The tool to refine a basic security policy:
    4.50 +==============
    4.51 +
    4.52 +The xensec_gen utility starts a web-server that can be used to
    4.53 +generate the XML policy files needed to create or maintain a
    4.54 +policy. It can be pre-loaded with a policy file created by
    4.55 +xensec_ezpolicy.
    4.56 +
    4.57 +By default, xensec_gen runs as a daemon and listens on port 7777 for
    4.58 +HTTP requests.  The xensec_gen command supports command line options
    4.59 +to change the listen port, run in the foreground, and a few others.
    4.60 +Type 'xensec_gen -h' to see the full list of options available.
    4.61 +
    4.62 +Once the xensec_gen utility is running, point a browser at the host
    4.63 +and port on which the utility is running (e.g. http://localhost:7777).
    4.64 +You will be presented with a web page that allows you to create or
    4.65 +modify the XML policy file:
    4.66 +
    4.67 +  - The Security Policy types section allows you to create or modify
    4.68 +the policy types and conflict set definitions
    4.69 +
    4.70 +  - The Security Policy Labeling section allows you to create or
    4.71 +modify label definitions
    4.72 +
    4.73 +The policy generation tool allows you to modify an existing policy
    4.74 +definition or create a new policy definition file. To modify an
    4.75 +existing policy definition, enter the full path to the existing file
    4.76 +(the "Browse" button can be used to aid in this) in the Policy File
    4.77 +entry field.  To create a new policy definition file leave the Policy
    4.78 +File entry field blank.  At this point click the "Create" button to
    4.79 +begin modifying or creating your policy definition.
    4.80 +
    4.81 +  Security Policy Types Section
    4.82 +  -----------------------------
    4.83 +
    4.84 +You will then be presented with a web page. The upper part of it will
    4.85 +allow you to create either Simple Type Enforcement types or Chinese
    4.86 +Wall types or both, as well as Chinese Wall conflict sets.
    4.87 +
    4.88 +As an example, to add a Simple Type Enforcement type:
    4.89 +
    4.90 +- Enter the name of a new type under the Simple Type Enforcement Types
    4.91 +section in the entry field above the "New" button.
    4.92 +
    4.93 +- Click the "New" button and the type will be added to the list of
    4.94 +defined Simple Type Enforcement types.
    4.95 +
    4.96 +To remove a Simple Type Enforcement type:
    4.97 +
    4.98 +- Click on the type to be removed in the list of defined Simple Type
    4.99 +Enforcement types.
   4.100 +
   4.101 +- Click the "Delete" button to remove the type.
   4.102 +
   4.103 +Follow the same process to add Chinese Wall types. The Chinese Wall
   4.104 +Conflict Set allows you to add Chinese Wall types from the list of
   4.105 +defined Chinese Wall types.
   4.106 +
   4.107 +
   4.108 +  Security Policy Labels:
   4.109 +  -------------------------
   4.110 +
   4.111 +The security policy label section of the web page allows you to create
   4.112 +labels for classes of virtual machines and resources.  The input
   4.113 +policy type definitions on the upper part of the web page will provide
   4.114 +the available types (Simple Type Enforcement and/or Chinese Wall) that
   4.115 +can be assigned to a virtual machine class. Resource classes only
   4.116 +include simple type enforcement types; the Chinese Wall policy does
   4.117 +apply only to virtual machines.
   4.118 +
   4.119 +As an example, to add a Virtual Machine class (the name entered will
   4.120 +become the label that will be used to identify the class):
   4.121 +
   4.122 +- Enter the name of a new class under the Virtual Machine Classes
   4.123 +section in the entry field above the "New" button.
   4.124 +
   4.125 +- Click the "New" button and the class will be added to the table of
   4.126 +defined Virtual Machine classes.
   4.127 +
   4.128 +To remove a Virtual Machine class:
   4.129 +
   4.130 +- Click the "Delete" link associated with the class in the table of
   4.131 +Virtual Machine classes.
   4.132 +
   4.133 +Once you have defined one or more Virtual Machine classes, you will
   4.134 +be able to add any of the defined Simple Type Enforcement types or
   4.135 +Chinese Wall types to a particular Virtual Machine.
   4.136 +
   4.137 +If you create a new policy, you must also define which Virtual Machine
   4.138 +class is to be associated with the bootstrap domain (or Dom0 domain).
   4.139 +By default, the first Virtual Machine class created will be associated
   4.140 +as the bootstrap domain.
   4.141 +
   4.142 +To save your policy definition file, click on the "Generate XML"
   4.143 +button on the top of the page.  This will present you with a dialog
   4.144 +box to save the generated XML file on your system.  The default name
   4.145 +will be security_policy.xml which you should change to follow the
   4.146 +policy file naming conventions based on the policy name that you
   4.147 +choose to use.
   4.148 +
   4.149 +To get a feel for the tool, you could use one of the example policy
   4.150 +definitions files from /etc/xen/acm-security/policies/example as
   4.151 +input or a policy created by the xensec_ezpolicy tool.
     5.1 --- a/tools/security/readme.txt	Fri Oct 20 10:46:37 2006 +0100
     5.2 +++ b/tools/security/readme.txt	Fri Oct 20 10:48:34 2006 +0100
     5.3 @@ -1,34 +1,33 @@
     5.4  
     5.5  ##
     5.6 -# readme.txt <description to the xen access control architecture>
     5.7 +# readme.txt <description to the sHype/Xen access control architecture>
     5.8  #
     5.9  # Author:
    5.10 -# Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
    5.11 +# Reiner Sailer 08/30/2006 <sailer@watson.ibm.com>
    5.12  #
    5.13  #
    5.14  # This file is a toc for information regarding
    5.15  # the access control policy and tools in Xen.
    5.16  ##
    5.17  
    5.18 -1. 'xm' man page
    5.19 +1. Xen User Guide
    5.20 +
    5.21 +   describes how to configure, install, and deploy the sHype Access
    5.22 +   Control Module in Xen. See chapter "sHype/Xen Access Control".
    5.23 +
    5.24 +2. 'xm' man page
    5.25  
    5.26     describes the commands related to Xen management, including the
    5.27     commands to manage security policies and labels. Read the access
    5.28 -   control subcommand section of the xm manual first. If it is not
    5.29 -   built by default, check install.txt.
    5.30 +   control subcommand section of the xm manual first.
    5.31  
    5.32 -2. policy.txt:
    5.33 +3. policy.txt
    5.34  
    5.35 -   describes the general reasoning and examples for access
    5.36 -   control policies in Xen
    5.37 +   describes examples for access control policies in Xen. First read
    5.38 +   the policy description in the Xen User Guide.
    5.39  
    5.40  
    5.41 -3. install.txt
    5.42 -
    5.43 -   describes the activation of the access control framework
    5.44 -   in Xen
    5.45 +4. policytools.txt
    5.46  
    5.47 -4. example.txt
    5.48 -
    5.49 -   describes the available tools for managing security policies
    5.50 -   in Xen and the tools to label domains
    5.51 +   describes the available tools for creating and managing security
    5.52 +   policies in Xen.