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