diff options
Diffstat (limited to 'tools/security/example.txt')
| -rw-r--r-- | tools/security/example.txt | 376 |
1 files changed, 0 insertions, 376 deletions
diff --git a/tools/security/example.txt b/tools/security/example.txt deleted file mode 100644 index c9afe88714..0000000000 --- a/tools/security/example.txt +++ /dev/null @@ -1,376 +0,0 @@ -## -# example.txt <description to the xen access control architecture> -# -# Author: -# Reiner Sailer 08/15/2005 <sailer@watson.ibm.com> -# 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 - |