xen/tools/security/example.txt

##
# example.txt <description to the xen access control architecture>
#
# Author:
# Reiner Sailer 08/15/2005 <sailer@watson.ibm.com>
#               04/07/2006 update to using labels instead of ssidref
#
#
# This file introduces into the tools to manage policies
# and to label domains and resources.
##

We will show how to install and use the example one of the client_v1
policies. Other policies work similarly. Feedback welcome!



1. Using xm tools to translate example.chwall_ste.client_v1 policy:
===================================================================

#xm makepolicy example.chwall_ste.client_v1

By default, the tool looks in directory /etc/xen/acm-security/policies
for a directory that matches the policy name
(here:example/chwall_ste/client_v1-security_policy.xml) to find the
policy files.  The '-d' option can be used to override the default
/etc/xen/acm-security/policies policy-root directory.

The default policy directory structure under /etc/xen/acm-security (and
the Xen security tool build directory - tools/security) looks like:

policies
|-- security_policy.xsd
|-- example
    |-- chwall
    |   |-- client_v1-security_policy.xml
    |
    |-- chwall_ste
    |   |-- client_v1-security_policy.xml
    |
    |-- ste
        |-- client_v1-security_policy.xml

The security_policy.xsd file contains the schema against which the
policy files must validate during translation.

The policy files, ending in -security_policy.xml, define the policies,
the types known to the policies, and the label definitions that group
types together and make them easier to use for users.

After executing the above 'xm makepolicy' command, you will find 2 new
files in the /etc/xen/acm-security/policies/example/chwall_ste
sub-directory:

  client_v1.map ... this file includes the mapping
    of names from the xml files into their binary code representation.

  client_v1.bin ... this is the binary policy file, the result of
    parsing the xml files and using the mapping to create a binary
    version that can be loaded into the hypervisor.



2. Loading and activating the policy:
=====================================

We assume that xen is already configured for security;
please refer to install.txt for instructions.

To activate the policy from the command line:

# xm loadpolicy example.chwall_ste.client_v1

See install.txt for how to install a policy at boot time. This the
recommended default. You can only load a policy if the currently
enforced policy is "DEFAULT", a minimal startup policy, or if the
currently enforced policy has the same name as the new one. Support
for dynamic policy changes at run-time are a current working item.


3. Labeling domains:
====================

a) Labeling Domain0:

The chwall_ste-security_label_template.xml file includes an attribute
"bootstrap", which is set to the label name that will be assigned to
Dom0 (this label will be mapped to ssidref 1/1, the default for Dom0).

b) Labeling User Domains (domains started from dom0 using xm commands):

We distinguish two kinds of labels: a) VM labels (for domains) and RES
Labels (for resources). We focus here on VM labels. Resource labels
will be supported later.

To list all available domain labels of a policy, use:
   #xm labels example.chwall_ste.client_v1

To list all available labels including resource labels (their support
is current work), use:

   #xm labels example.chwall_ste.client_v1 type=any

The policy parameter is optional. The currently enforced hypervisor
policy is used by default.

If you would like to assign the dom_HomeBanking label to one of your user domains,
look at the hypothetical domain configuration contained in /etc/xen/homebanking.xm:

    #------FOR HOME/ONLINE BANKING---------
    kernel = "/boot/vmlinuz-2.6.16-xen"
    ramdisk="/boot/U1_ramdisk.img"
    memory = 164
    name = "homebanking"
    vif=['']
    dhcp = "dhcp"
    #-------------------------

Now we label this domain (policy name is optional, see above):

    # xm addlabel homebanking.xm dom_HomeBanking example.chwall_ste.client_v1

The domain configuration should look now like:

    # cat homebanking.xm
    #------FOR HOME/ONLINE BANKING---------
    kernel = "/boot/vmlinuz-2.6.16-xen"
    ramdisk="/boot/U1_ramdisk.img"
    memory = 164
    name = "homebanking"
    vif=['']
    dhcp = "dhcp"
    access_control = ['policy=example.chwall_ste.client_v1, label=dom_HomeBanking']

You can see the access_control line that was added to the
configuration. This label will be translated into a local ssidref when
a domain is created or resumed (also after migration and
live-migration). The ssidref is a local security reference that is
used inside the hypervisor instead of the security label for
efficiency reasons. Since the same label can be mapped onto different
ssidrefs in different policy translations (e.g., if the position of
the label definition is changed in the policy file) or on different
systems, the ssidref is re-calculated from the label each time a
domain is instantiated or re-instantiated.

Currently, the labels are not held in the hypervisor but only in
.map files in the /etc/xen/acm-security/policies subdirectories. Only
ssidrefs are known inside the hypervisr. This of course can change in
the future.


4. Starting a labeled domain
============================

Now, start the domain:

    #xm create homebanking.xm
    Using config file "homebanking.xm".
    Started domain fun


[root@941e-4 VMconfigs]# xm list --label

Name         ID Mem(MiB) VCPUs State  Time(s)  Label
fun           1       64     1 -b----     5.9  dom_HomeBanking
Domain-0      0     1954     1 r-----  1321.4  dom_SystemManagement



If you label another domain configuration as dom_Fun and if
you try to start it afterwards, this create will fail.

Why? -- Because the running 'homebanking' domain has the chinese
wall type "cw_Sensitive". The new domain 'fun' has the chinese wall
label "cw_Distrusted". These domains are not allowed to run simultaneously
on the same system because of the defined conflict set

			<conflictset name="Protection1">
				<type>cw_Sensitive</type>
				<type>cw_Distrusted</type>
			</conflictset>

(in client_v1-security_policy.xml), which says that only one of the
types cw_Sensitive and cw_Distrusted can run at a time.

If you save or shutdown the 'homebanking' domain, you will be able to
start the 'fun' domain. You can look into the Xen log to see if a
domain was denied to start because of the access control framework
with the command 'xm dmesg'.

It is important (and usually non-trivial) to define the labels in a
way that the semantics of the labels are enforced and supported by the
types and the conflict sets. Usually, a workload abstraction seems
helpful on the hypervisor level.

Note: While the chinese wall policy enforcement is complete, the type
enforcement is currently enforced inside the Xen hypervisor
only. Therefore, only point-to-point sharing with regard to the type
enforcement is currently controlled. Enforcing the STE policy while
sharing virtual resources is ongoing work and assumed to be complete
by year end as well as enforcing the STE policy for network traffic
routed through dom0.


5. Adding your own policies
===========================

Writing your own policy (e.g. "mypolicy.chwall.test") requires the policy
definition (types etc.) and the label definitions. Any policy name
must have chwall, ste, or chwall_ste in its name. This is used by the
configuration tool to identify existing binary policy entries in the
boot configuration file (menu.lst, grub.con). This part should, of
course, be consistent with policy type that is defined.

First, you create
/etc/xen/acm-security/policies/mypolicy/chwall/test-security_policy.xml.

You need to keep to the schema as defined in
/etc/xen/acm-security/security_policy.xsd since the translation tools
are written against this schema.

You can hand-edit the xml files to create your policy or you can use the
xensec_gen utility.


6. Generating policy files using xensec_gen:
============================================

The xensec_gen utility starts a web-server that can be used to generate the
XML policy files needed to create a policy.

By default, xensec_gen runs as a daemon and listens on port 7777 for HTTP
requests.  The xensec_gen command supports command line options to change the
listen port, run in the foreground, and a few others.  Type 'xensec_gen -h'
to see the full list of options available.

Once the xensec_gen utility is running, point a browser at the host and port
on which the utility is running (e.g. http://localhost:7777/).  You will be
presented with a web page that allows you to create or modify the XML policy
file:

  - The Security Policy types section allows you to create or modify
    the policy types and conflict set definitions

  - The Security Policy Labeling section allows you to create or modify a
    label definitions

The policy generation tool allows you to modify an existing policy
definition or create a new policy definition file. To modify an
existing policy definition, enter the full path to the existing file
(the "Browse" button can be used to aid in this) in the Policy File
entry field.  To create a new policy definition file leave the Policy
File entry field blank.  At this point click the "Create" button to
begin modifying or creating your policy definition.

  Security Policy Types Section
  -----------------------------

You will then be presented with a web page. The upper part of it will
allow you to create either Simple Type Enforcement types or Chinese
Wall types or both, as well as Chinese Wall conflict type sets.

  As an example:
    - To add a Simple Type Enforcement type:
      - Enter the name of a new type under the Simple Type Enforcement Types
        section in the entry field above the "New" button.
      - Click the "New" button and the type will be added to the list of defined
        Simple Type Enforcement types.
    - To remove a Simple Type Enforcement type:
      - Click on the type to be removed in the list of defined Simple Type
        Enforcement types.
      - Click the "Delete" button to remove the type.

  Follow the same process to add Chinese Wall types.  If you define Chinese Wall
  types you need to define at least one Chinese Wall Conflict Set.  The Chinese
  Wall Conflict Set will allow you to add Chinese Wall types from the list of
  defined Chinese Wall types.

  Security Policy Labeling:
  -------------------------

  The security policy label section of the web page allows you to create labels
  for classes of virtual machines.  The input policy type definitions on the upper
  part of the web page will provide the available types (Simple Type Enforcement
  and/or Chinese Wall) that can be assigned to a virtual machine class.

  As an example:
    - To add a Virtual Machine class (the name entered will become the label
      that will be used to identify the class):
      - Enter the name of a new class under the Virtual Machine Classes section
        in the entry field above the "New" button.
      - Click the "New" button and the class will be added to the table of defined
        Virtual Machine classes.
    - To remove a Virtual Machine class:
      - Click the "Delete" link associated with the class in the table of Virtual
        Machine classes.

  Once you have defined one or more Virtual Machine classes, you will be able to
  add any of the defined Simple Type Enforcement types or Chinese Wall types to a
  particular Virtual Machine.

  You must also define which Virtual Machine class is to be associated with the
  bootstrap domain (or Dom0 domain).  By default, the first Virtual Machine class
  created will be associated as the bootstrap domain.

  To save your policy definition file, click on the "Generate XML" button
  on the top of the page.  This will present you with a dialog box to save the
  generated XML file on your system.  The default name will be
  security_policy.xml which you should change to follow the policy file
  naming conventions based on the policy name that you choose to use.

  To get a feel for the tool, you could use one of the example policy definitions
  files from /etc/xen/acm-security/policies/example as input.


7. Hypervisor - OS Security Interface
=====================================

We currently provide 2 hypercalls through which user operating systems
can interact with the hypervisor Access Control Module. Examples of
using them are under "xen_root"/tools/security/python/xensec_tools:


I) acm_getdecision -i domainid -l labelname
   Call this example script without arguments to show its usage
   information.

   This script enables a domain to retrieve an access control decision
   regarding the STE policy from the hypervisor. It will be used to
   control access to virtual/real resources in hosting domains.

   The script can be provided with any combination of domain ids or
   labelnames. Before calling into the hypervisor, labels are translated
   into ssidrefs. The hypervisor then retrieves for any domain id
   paramter the ssidref before deciding access.

   Example:
   #/etc/xen/acm-security/scripts/acm_getdecision -l dom_Fun
						 -l dom_SystemManagement
   PERMITTED

   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -i 1
   PERMITTED

   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l dom_Fun
   PERMITTED

   #/etc/xen/acm-security/scripts/acm_getdecision -i 0 -l no_label
   ACMError: Label 'nolabel' not found.

   Now, assume domain 123454 does not exist:
   #/etc/xen/acm-security/scripts/acm_getdecision -i 123454 -l dom_Fun
   ACMError: Cannot determine decision (Invalid parameter).

   Return values:
            * DENIED: access is denied based on the current hypervisor
                      policy

            * PERMITTED: access is permitted based on the current

            * Exception ACMError: one of the parameters was illegal,
                                  i.e. an unknown label or a
                                  non-existing domain id

I) acm_getlabel -i domainid
   Retrieves the label of a runing domain. This function can be used
   by domains to determine their own label or (if authorized) the label
   other domains.

   Example (result is broken up into different lines to simplify description):
   # /etc/xen/acm-security/scripts/acm_getlabel -i 0
  ('example.chwall.client_v1',         <--- policy describing labels etc.
   'dom_SystemManagement',             <--- label name of the domain
   'CHINESE WALL',                     <--- policy type
   65537)                              <--- hypervisor internal ssidref