Skip to contentSkip to conversation

cleans up txt files in tools/security

PATCH New Reiner Sailer 1 participant 1 message Sep 1, 2006

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 cleans up txt files in tools/security

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

Thanks
Reiner

Signed-off by: Reiner Sailer <[email protected]>

---
 tools/security/example.txt     |  376 -----------------------------------------
 tools/security/install.txt     |   87 ---------
 tools/security/policy.txt      |  159 ++---------------
 tools/security/policytools.txt |  148 ++++++++++++++++
 tools/security/readme.txt      |   31 +--
 5 files changed, 182 insertions(+), 619 deletions(-)
tools/security/example.txt deleted +0 -376
Index: xen-unstable.hg-test/tools/security/example.txt
===================================================================
@@ -1,376 +0,0 @@
-##
-# example.txt <description to the xen access control architecture>
-#
-# Author:
-# Reiner Sailer 08/15/2005 <[email protected]>
-#               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
-
tools/security/install.txt deleted +0 -87

87 lines not on this page · raw message

tools/security/policy.txt +19 -140

198 lines not on this page · raw message

tools/security/policytools.txt new file +148 -0

148 lines not on this page · raw message

tools/security/readme.txt +15 -16
Index: xen-unstable.hg-test/tools/security/readme.txt
===================================================================
@@ -1,34 +1,33 @@
 
 ##
-# readme.txt <description to the xen access control architecture>
+# readme.txt <description to the sHype/Xen access control architecture>
 #
 # Author:
-# Reiner Sailer 08/15/2005 <[email protected]>
+# Reiner Sailer 08/30/2006 <[email protected]>
 #
 #
 # This file is a toc for information regarding
 # the access control policy and tools in Xen.
 ##
 
-1. 'xm' man page
+1. Xen User Guide
 
-   describes the commands related to Xen management, including the
-   commands to manage security policies and labels. Read the access
-   control subcommand section of the xm manual first. If it is not
-   built by default, check install.txt.
+   describes how to configure, install, and deploy the sHype Access
+   Control Module in Xen. See chapter "sHype/Xen Access Control".
 
-2. policy.txt:
+2. 'xm' man page
 
-   describes the general reasoning and examples for access
-   control policies in Xen
+   describes the commands related to Xen management, including the
+   commands to manage security policies and labels. Read the access
+   control subcommand section of the xm manual first.
 
+3. policy.txt
 
-3. install.txt
+   describes examples for access control policies in Xen. First read
+   the policy description in the Xen User Guide.
 
-   describes the activation of the access control framework
-   in Xen
 
-4. example.txt
+4. policytools.txt
 
-   describes the available tools for managing security policies
-   in Xen and the tools to label domains
+   describes the available tools for creating and managing security
+   policies in Xen.

_______________________________________________
Xen-devel mailing list
[email protected]
http://lists.xensource.com/xen-devel