##
# policytools.txt
#      <description to the sHype/Xen policy management tools>
#
# Author:
# Reiner Sailer 08/31/2006 <sailer@watson.ibm.com>
#
#
##

This file describes the Xen-tools to create and maintain security
policies for the sHype/Xen access control module.

A security policy (e.g. "example.chwall_ste.test") is defined in
XML. Read in the user manual about the naming of policies. The policy
name is used by the Xen management tools to identify existing
policies. Creating the security policy means creating a policy
description in XML:
/etc/xen/acm-security/policies/example/chwall_ste/test-security_policy.xml.

The policy XML description must follow the XML schema definition in
/etc/xen/acm-security/policies/security_policy.xsd. The policy tools
are written against this schema; they will create and refine policies
that conform to this scheme.

Two tools are provided to help creating security policies:


1. xensec_ezpolicy: The starting point for writing security policies.
===================

This wxPython-based GUI tool is meant to create very quickly a
starting point for a workload protection security policy. Please start
the tool (xensec_ezpolicy) and press <CTRL-h> for usage explanations.
The Xen User guide explains its usage at an example in chapter
"sHype/Xen Access Control".

The output of the tool is a security policy that is fully operable. It
is sufficient to create policies that demonstrate how sHype/ACM works.

However, it defines only a basic set of security labels assuming that
Domain0 hosts and virtualizes all hardware (storage etc.). Use
xensec_gen to refine this policy and tailor it to your requirements.


2. xensec_gen: The tool to refine a basic security policy:
==============

The xensec_gen utility starts a web-server that can be used to
generate the XML policy files needed to create or maintain a
policy. It can be pre-loaded with a policy file created by
xensec_ezpolicy.

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 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 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. The Chinese Wall
Conflict Set allows you to add Chinese Wall types from the list of
defined Chinese Wall types.


  Security Policy Labels:
  -------------------------

The security policy label section of the web page allows you to create
labels for classes of virtual machines and resources.  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. Resource classes only
include simple type enforcement types; the Chinese Wall policy does
apply only to virtual machines.

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.

If you create a new policy, 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 or a policy created by the xensec_ezpolicy tool.
