## # example.txt # # Author: # Reiner Sailer 08/15/2005 # # # 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 cw_Sensitive cw_Distrusted (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.