xen/tools/security/example.txt

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

We will show how to install and use the example chwall_ste policy.
Other policies work similarly. Feedback welcome!



1. Using xensec_xml2bin to translate the chwall_ste policy:
===========================================================

#xensec_xml2bin chwall_ste

Successful execution should print:

    [root@laptopxn security]# xensec_xml2bin chwall_ste
    Validating label file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_label_template.xml...
    XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
    Validating policy file /etc/xen/acm-security/policies/chwall_ste/chwall_ste-security_policy.xml...
    XML Schema /etc/xen/acm-security/policies/security_policy.xsd valid.
    Creating ssid mappings ...
    Creating label mappings ...
    Max chwall labels:  7
    Max chwall-types:   4
    Max chwall-ssids:   5
    Max ste labels:     14
    Max ste-types:      6
    Max ste-ssids:      10

By default, the tool looks in directory /etc/xen/acm-security/policies
for a directory that matches the policy name (i.e. chwall_ste) to find
the label and policy files.
The '-d' option can be used to override the /etc/xen/acm-security/policies
directory, for example if running the tool in the Xen security tool build
directory.

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

policies
|-- security_policy.xsd
|-- chwall
|   |-- chwall-security_label_template.xml
|   `-- chwall-security_policy.xml
|-- chwall_ste
|   |-- chwall_ste-security_label_template.xml
|   `-- chwall_ste-security_policy.xml
|-- null
|   |-- null-security_label_template.xml
|   `-- null-security_policy.xml
`-- ste
    |-- ste-security_label_template.xml
    `-- ste-security_policy.xml

The security_policy.xsd file contains the schema against which both the
label-template and the policy files must validate during translation.

The files ending in -security_policy.xml define the policies and the
types known to the policies.

The files ending in -security_label_template.xml contain the label
definitions that group types together and make them easier to use for
users.

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

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

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



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

We assume that xen is already configured to use the chwall_ste policy;
please refer to install.txt for instructions.

To activate the policy from the command line (assuming that the
currently established policy is the minimal boot-policy that is
hard-coded into the hypervisor):

# xensec_tool loadpolicy /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin

To activate the policy at next reboot:

# cp /etc/xen/acm-security/policies/chwall_ste/chwall_ste.bin /boot

Add a module line to your /boot/grub/grub.conf Xen entry.
My boot entry with chwall_ste enabled looks like this:

    title Xen (2.6.12)
        root (hd0,5)
        kernel /boot/xen.gz dom0_mem=1200000 console=vga
        module /boot/vmlinuz-2.6.12-xen0 ro root=/dev/hda6 rhgb
        module /boot/initrd-2.6.12-xen0.img
        module /boot/chwall_ste.bin

This tells the grub boot-loader to load the binary policy, which
the hypervisor will recognize. The hypervisor will then establish
this binary policy during boot instead of the minimal policy that
is hardcoded as default.

If you have any trouble here, maks sure you have the access control
framework enabled (see: install.txt).



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:

Use the script tools/security/setlabel.sh to choose a label and to
assign labels to user domains.

To show available labels for the chwall_ste policy:

# /etc/xen/acm-security/scripts/setlabel.sh -l

lists all available labels. For the default chwall_ste it should print
the following:

    [root@laptopxn security]# /etc/xen/acm-security/scripts/setlabel.sh -l chwall_ste
    The following labels are available:
    dom_SystemManagement
    dom_HomeBanking
    dom_Fun
    dom_BoincClient
    dom_StorageDomain
    dom_NetworkDomain

You need to have compiled the policy beforehand so that a .map file
exists. Setlabel.sh uses the mapping file created throughout the
policy translation to translate a user-friendly label string into a
ssidref-number that is eventually used by the Xen hypervisor.

We distinguish two kinds of labels: a) VM labels (for domains) and RES
Labels (for resources). We are currently working on support for
resource labeling but will focus here on VM labels.

Setlabel.sh only prints VM labels (which we have prefixed with "dom_")
since only those are used at this time.

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

    #------HOMEBANKING---------
    kernel = "/boot/vmlinuz-2.6.12-xenU"
    ramdisk="/boot/U1_ramdisk.img"
    memory = 65
    name = "test34"
    cpu = -1   # leave to Xen to pick
    # Number of network interfaces. Default is 1.
    nics=1
    dhcp="dhcp"
    #-------------------------

Now we label this domain

[root@laptopxn security]# /etc/xen/acm-securit/scripts/setlabel.sh /etc/xen/homebanking.xm dom_HomeBanking chwall_ste
Mapped label 'dom_HomeBanking' to ssidref '0x00020002'.

The domain configuration my look now like:

    [root@laptopxn security]# cat homebanking.xm
    #------HOMEBANKING---------
    kernel = "/boot/vmlinuz-2.6.12-xenU"
    ramdisk="/boot/U1_ramdisk.img"
    memory = 65
    name = "test34"
    cpu = -1   # leave to Xen to pick
    # Number of network interfaces. Default is 1.
    nics=1
    dhcp="dhcp"
    #-------------------------
    #ACM_POLICY=chwall_ste-security_policy.xml
    #ACM_LABEL=dom_HomeBanking
    ssidref = 0x00020002

You can see 3 new entries, two of which are comments.  The only value
that the hypervisor cares about is the ssidref that will reference
those types assigned to this label. You can look them up in the
xml label-template file for the chwall_ste policy.

This script will eventually move into the domain management and will
be called when the domain is instantiated. For now, the setlabel
script must be run on domains whenever the policy files change since
the mapping between label names and ssidrefs can change in this case.


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

Now, start the domain:
    #xm create -c homebanking.xm


If you label another domain configuration as dom_Fun and try to start
it afterwards, its start will fail. Why?

Because the running homebanking domain has the chinese wall type
"cw_Sensitive". The new domain dom_Fun has the chinese wall label
"cw_Distrusted". This domain is not allowed to run simultaneously
because of the defined conflict set

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

(in chwall_ste-security_policy.xml), which says that only one of the
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.

Note: While the chinese wall policy enforcement is complete, the type
enforcement is currently enforced in the Xen hypervisor
only. Therefore, only point-to-point sharing with regard to the type
enforcement is currently controlled. We are working on enhancements to
Dom0 that enforce types also for network traffic that is routed
through Dom0 and on the enforcement of resource labeling when binding
resources to domains (e.g., enforcing types between domains and
hardware resources, such as disk partitions).


4. Adding your own policies
===========================

Writing your own policy (e.g. "mypolicy") requires the following:

a) the policy definition (types etc.) file
b) the label template definition (labels etc.) file

If your policy name is "mypolicy", you need to create a
subdirectory mypolicy in /etc/xen/acm-security/policies.

Then you create
/etc/xen/acm-security/policies/mypolicy/mypolicy-security_policy.xml and
/etc/xen/acm-security/policies/mypolicy/mypolicy-security_label_template.xml.

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

If you keep to the security policy schema, then you can use all the
tools described above. Refer to install.txt to install it.

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


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

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
files:

  - The Security Policy section allows you to create or modify a policy
    definition file

  - The Security Policy Labeling section allows you to create or modify a
    label template definition file

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

  You will then be presented with a web page that will allow you to create either
  Simple Type Enforcement types or Chinese Wall types or both.

  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.

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

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


  Security Policy Labeling:
  -------------------------
  The Security Policy Labeling section allows you to modify an existing label
  template definition file or create a new label template definition file.  To
  modify an existing label template definition, enter the full path to the
  existing file (the "Browse" button can be used to aid in this) in the Policy
  Labeling File entry field.  Whether creating a new label template definition
  file or modifying an existing one, you will need to specify the policy
  definition file that is or will be associated with this label template
  definition file.  At this point click the "Create" button to begin modifying
  or creating your label template definition file.

  You will then be presented with a web page that will allow you to create labels
  for classes of virtual machines.  The input policy definition file will provide
  the available types (Simple Type Enforcement and/or Chinese Wall) that can be
  assigned to a virtual machine class.

  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 create your label template definition file, click on the "Generate XML" button
  on the top of the page.  This will present you with a dialog box to save the
  generated XML file on your system.  The default name will be
  security_label_template.xml which you should change to follow the policy file
  naming conventions based on the policy name that you choose to use.

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