|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-changelog] This patch updates the documentation and extends the 'xm' man page with
# HG changeset patch # User smh22@xxxxxxxxxxxxxxxxxxxx # Node ID c7b9b8a64755c0000677938a9ca6f0890a8ea33f # Parent 681a18bf049e320ddb11dde9cca08fa7bba4192e This patch updates the documentation and extends the 'xm' man page with the integrated access control management commands. The man page is a good place to start exploring these commands. Signed-off by: Reiner Sailer <sailer@xxxxxxxxxx> diff -r 681a18bf049e -r c7b9b8a64755 docs/man/xm.pod.1 --- a/docs/man/xm.pod.1 Mon Apr 24 10:59:17 2006 +0100 +++ b/docs/man/xm.pod.1 Mon Apr 24 10:59:57 2006 +0100 @@ -136,7 +136,7 @@ The I<--long> option prints out the comp The I<--long> option prints out the complete set of B<xm> subcommands, grouped by function. -=item B<list> I<[--long]> I<[domain-id, ...]> +=item B<list> I<[--long | --label]> I<[domain-id, ...]> Prints information about one or more domains. If no domains are specified it prints out information about all domains. @@ -212,6 +212,18 @@ Use at your own risk. Use at your own risk. =back + +B<LABEL OUTPUT> + +=over 4 + +If I<--label> is specified, the security labels are added to the +output of xm list and the lines are sorted by the labels (ignoring +case). The I<--long> option prints the labels by default and cannot be +combined with I<--label>. See the ACCESS CONTROL SUBCOMMAND section of +this man page for more information about labels. + +==back B<NOTES> @@ -775,6 +787,262 @@ Delete a vnet. =back +=head1 ACCESS CONTROL SUBCOMMANDS + +Access Control in Xen consists of two components: (i) The Access +Control Policy (ACP) defines security labels and access rules based on +these labels. (ii) The Access Control Module (ACM) makes access control +decisions by interpreting the policy when domains require to +communicate or to access resources. The Xen access control has +sufficient mechanisms in place to enforce the access decisions even +against maliciously acting user domains (mandatory access control). + +Access rights for domains in Xen are determined by the domain security +label only and not based on the domain Name or ID. The ACP specifies +security labels that can then be assigned to domains and +resources. Every domain must be assigned exactly one security label, +otherwise access control decisions could become indeterministic. ACPs +are distinguished by their name, which is a parameter to most of the +subcommands described below. Currently, the ACP specifies two ways to +interpret labels: + +(1) Simple Type Enforcement: Labels are interpreted to decide access +of domains to comunication means and virtual or physical +resources. Communication between domains as well as access to +resources are forbidden by default and can only take place if they are +explicitly allowed by the security policy. The proper assignment of +labels to domains controls the sharing of information (directly +through communication or indirectly through shared resources) between +domains. This interpretation allows to control the overt (intended) +communication channels in Xen. + +(2) Chinese Wall: Labels are interpreted to decide which domains can +co-exist (be run simultaneously) on the same system. This +interpretation allows to prevent direct covert (unintended) channels +and mitigates risks caused by imperfect core domain isolation +(trade-off between security and other system requirements). For a +short introduction to covert channels, please refer to +http://www.multicians.org/timing-chn.html. + +The following subcommands help you to manage security policies in Xen +and to assign security labels to domains. To enable access control +security in Xen, you must compile Xen with ACM support enabled as +described under "Configuring Security" below. There, you will find +also examples of each subcommand described here. + +=item B<makepolicy> I<policy> + +Compiles the XML source representation of the security I<policy>. It +creates a mapping (.map) as well as a binary (.bin) version of the +policy. The compiled policy can be loaded into Xen with the +B<loadpolicy> subcommand or can be configured to be loaded at boot +time with the B<cfgbootpolicy> subcommand. + +=over 4 + +I<policy> is a dot-separated list of names. The last part is the file +name pre-fix for the policy xml file. The preceding name parts are +translated into the local path pointing to the policy xml file +relative to the global policy root directory +(/etc/xen/acm-security/policies). For example, +example.chwall_ste.client_v1 denotes the policy file +example/chwall_ste/client_v1-security_policy.xml relative to the +global policy root directory. + +=back + +=item B<loadpolicy> I<policy> + +Loads the binary representation of the I<policy> into Xen. The binary +representation can be created with the B<makepolicy> subcommand. + +=item B<cfgbootpolicy> I<policy> [I<kernelversion>] + +Configures I<policy> as the boot policy for Xen. It copies the binary +policy representation into the /boot directory and adds a module line +specifying the binary policy to the /boot/grub/menu.lst file. If your +boot configuration includes multiple Xen boot titles, then use the +I<kernelversion> parameter to select the proper title. + +=item B<dumppolicy> + +Prints the current security policy state information of Xen. + +=item B<labels> [I<policy>] [I<type>=dom|res|any] + +Lists all labels of a I<type> (domain, resource, or both) that are +defined in the I<policy>. Unless specified, the default I<policy> is +the currently enforced access control policy. The default for I<type> +is 'dom'. The labels are arranged in alphabetical order. + +=item B<addlabel> I<configfile> I<label> [I<policy>] + +Adds the security label with name I<label> to a domain +I<configfile>. Unless specified, the default I<policy> is the +currently enforced access control policy. This subcommand also +verifies that the I<policy> definition supports the specified I<label> +name. + +B<CONFIGURING SECURITY> + +=over 4 + +In xen_source_dir/Config.mk set the following parameters: + + ACM_SECURITY ?= y + ACM_DEFAULT_SECURITY_POLICY ?= \ + ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY + +Then recompile and install xen and the security tools and then reboot: + + cd xen_source_dir/xen; make clean; make; cp xen.gz /boot; + cd xen_source_dir/tools/security; make install; + reboot into xen + +=back + +B<COMPILING A SECURITY POLICY> + +=over 4 + +This step creates client_v1.map and client_v1.bin files in +/etc/xen/acm-security/policies/example/chwall_ste. + + xm makepolicy example.chwall_ste.client_v1 + +=back + +B<LOADING A SECURITY POLICY> + +=over 4 + +This step activates client_v1.bin as new security policy in Xen. You +can use the dumppolicy subcommand before and afterwards to see the +change in the Xen policy state. + + xm loadpolicy example.chwall_ste.client_v1 + +=back + +B<CONFIGURING A BOOT SECURITY POLICY> + +=over 4 + +This configures the boot loader to load client_v1.bin at boot +time. During system start, the ACM configures Xen with this policy and +Xen enforces this policy from then on. + + xm cfgbootpolicy example.chwall_ste.client_v1 + +=back + +B<LISTING SECURITY LABELS> + +=over 4 + +This subcommand shows all labels that are defined and which can be +attached to domains. + + xm labels example.chwall_ste.client_v1 type=dom + +will print for our example policy: + + dom_BoincClient + dom_Fun + dom_HomeBanking + dom_NetworkDomain + dom_StorageDomain + dom_SystemManagement + +=back + +B<ATTACHING A SECURITY LABEL TO A DOMAIN> + +=over 4 + +This subcommand attaches a security label to a domain configuration +file, here a HomeBanking label. The example policy ensures that this +domain does not share information with other non-hombanking user +domains (i.e., domains labeled as dom_Fun or dom_Boinc) and that it +will not run simultaneously with domains labeled as dom_Fun. + +We assume that the specified myconfig.xm configuration file actually +instantiates a domain that runs workloads related to home-banking, +probably just a browser environment for online-banking. + + xm addlabel myconfig.xm dom_HomeBanking + +The very simple configuration file might now look as printed +below. The I<addlabel> subcommand added the B<access_control> entry at +the end of the file, consisting of a label name and the policy that +specifies this label name: + + kernel = "/boot/vmlinuz-2.6.16-xen" + ramdisk="/boot/U1_home_banking_ramdisk.img" + memory = 164 + name = "homebanking" + vif = [ '' ] + dhcp = "dhcp" + access_control = ['policy=example.chwall_ste.client_v1, + label=dom_HomeBanking'] + +Security labels must be assigned to domain configurations because +these labels are essential for making access control decisions as +early as during the configuration phase of a newly instantiated +domain. Consequently, a security-enabled Xen hypervisor will only +start domains that have a security label configured and whose security +label is consistent with the currently enforced policy. Otherwise, +starting the domain will fail with the error condition "operation not +permitted". + +=back + +B<STARTING AND LISTING LABELED DOMAINS> + +=over 4 + + xm create myconfig.xm + + xm list --label + + Name ID ... Time(s) Label + homebanking 23 ... 4.4 dom_HomeBanking + Domain-0 0 ... 2658.8 dom_SystemManagement + +=back + +B<POLICY REPRESENTATIONS> + +=over 4 + +We distinguish three representations of the Xen access control policy: +the I<source XML> version, its I<binary> counterpart, and a I<mapping> +representation that enables the tools to deterministically translate +back and forth between label names of the XML policy and label +identifiers of the binary policy. All three versions must be kept +consistent to achieve predictable security guarantees. + +The XML version is the version that users are supposed to create or +change, either by manually editing the XML file or by using the Xen +policy generation tool (B<xensec_gen>). After changing the XML file, +run the B<makepolicy> subcommand to ensure that these changes are +reflected in the other versions. Use, for example, the subcommand +B<cfgbootpolicy> to activate the changes during the next system +reboot. + +The binary version of the policy is derived from the XML policy by +tokenizing the specified labels and is used inside Xen only. It is +created with the B<makepolicy> subcommand. Essentially, the binary +version is much more compact than the XML version and is easier to +evaluate during access control decisions. + +The mapping version of the policy is created during the XML-to-binary +policy translation (B<makepolicy>) and is used by the Xen management +tools to translate between label names used as input to the tools and +their binary identifiers (ssidrefs) used inside Xen. + +=back + =head1 EXAMPLES =head1 SEE ALSO @@ -791,5 +1059,6 @@ Operating Systems Review, pages 261-267 Sean Dague <sean at dague dot net> Daniel Stekloff <dsteklof at us dot ibm dot com> + Reiner Sailer <sailer at us dot ibm dot com> =head1 BUGS diff -r 681a18bf049e -r c7b9b8a64755 tools/security/example.txt --- a/tools/security/example.txt Mon Apr 24 10:59:17 2006 +0100 +++ b/tools/security/example.txt Mon Apr 24 10:59:57 2006 +0100 @@ -3,119 +3,79 @@ # # Author: # Reiner Sailer 08/15/2005 <sailer@xxxxxxxxxxxxxx> +# 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 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 +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 (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. +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 -|-- 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 +|-- 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. - 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. + 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 to use the chwall_ste 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 (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). - +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: @@ -127,156 +87,143 @@ The chwall_ste-security_label_template.x "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. +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 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" +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 = 65 - name = "test34" - cpu = -1 # leave to Xen to pick - # Number of network interfaces. Default is 1. - nics=1 - dhcp="dhcp" + memory = 164 + name = "homebanking" + vif=[''] + 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" +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 = 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. + 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 -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 + + #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 chwall_ste-security_policy.xml), which says that only one of the +(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 +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. +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 in the Xen hypervisor +enforcement is currently enforced inside 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 +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") 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. +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 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. +/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. -5. Generating policy files using xensec_gen: +6. Generating policy files using xensec_gen: ============================================ The xensec_gen utility starts a web-server that can be used to generate the @@ -290,25 +237,28 @@ Once the xensec_gen utility is running, 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 +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 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. + 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: @@ -326,32 +276,13 @@ files: 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. + + 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 @@ -372,11 +303,74 @@ files: 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 + 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_label_template.xml which you should change to follow the policy file + 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 - and label template definition files from /etc/xen/acm-security/policies as input. + 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 + diff -r 681a18bf049e -r c7b9b8a64755 tools/security/install.txt --- a/tools/security/install.txt Mon Apr 24 10:59:17 2006 +0100 +++ b/tools/security/install.txt Mon Apr 24 10:59:57 2006 +0100 @@ -3,10 +3,11 @@ # # Author: # Reiner Sailer 08/15/2005 <sailer@xxxxxxxxxxxxxx> +# 03/18/2006 update: new labeling # # # This file shows how to activate and install the access control -# framework. +# framework for Xen. ## @@ -20,43 +21,54 @@ below to activate the Chinese Wall OR th below to activate the Chinese Wall OR the Type Enforcement policy exclusively (chwall_ste --> {chwall, ste}). +0. build and install the xm man page. It includes the description of + available management commands for the security policy for Xen and + the labeling of domains. If not installed by default, you can make + and install the xm man page as follows: + # cd "xen_root"/doc + # make install + Then, use man xm to read it: + # man xm + 1. enable access control in Xen # cd "xen_root" # edit/xemacs/vi Config.mk change the lines: ACM_SECURITY ?= n - ACM_DEFAULT_SECURITY_POLICY ?= ACM_NULL_POLICY - to: ACM_SECURITY ?= y + + Now the hypervisor will boot into the policy that is specified + in the grub configuration. If you would like to boot into a + specific policy (even if you can't specify a boot policy but + need to set the policy later using the 'xensec_tool + loadpolicy'), then use the other config parameter to change + from NULL to any other default policy, e.g.: ACM_DEFAULT_SECURITY_POLICY ?= ACM_CHINESE_WALL_AND_SIMPLE_TYPE_ENFORCEMENT_POLICY - # make all + # make dist # ./install.sh -2. compile the policy from xml to a binary format that can be loaded - into the hypervisor for enforcement +2. Build acm and policy tools and create boot-able policy: # cd tools/security - # make + # make install - manual steps (alternative to make boot_install): - # ./xensec_xml2bin -d policies/ chwall_ste - # cp policies/chwall_ste/chwall_ste.bin /boot - # edit /boot/grub/grub.conf - add the follwoing line to your xen boot entry: - "module /boot/chwall_ste.bin" + For description of the following commands, please see the xm + man page (docs/man1/xm.1). If it is not built, then you can + create it manually: cd "xen_root"/docs; make; man man1/xm.1 - alternatively, you can try our automatic translation and - installation of the policy: - # make boot_install + Step1: Building binary version of an example policy: + # xm makepolicy example.chwall_ste.client_v1 + # xm cfgbootpolicy example.chwall_ste.client_v1 - [we try hard to do the right thing to the right boot entry but - please verify boot entry in /boot/grub/grub.conf afterwards; - your xen boot entry should have an additional module line - specifying a chwall_ste.bin file with the correct directory - (e.g. "/" or "/boot").] - + Please verify boot entry in /boot/grub/grub.conf (or menu.lst): + title Xen (2.6.16) + root (hd0,0) + kernel /xen.gz dom0_mem=2000000 console=vga + module /vmlinuz-2.6.16-xen ro root=/dev/VolGroup00/LogVol00 rhgb + module /initrd-2.6.165-xen-U.img + module /example.chwall_ste.client_v1.bin 3. reboot into the newly compiled hypervisor @@ -64,6 +76,12 @@ 3. reboot into the newly compiled hyperv # xm dmesg should show an entry about the policy being loaded during the boot process - # xensec_tool getpolicy - should print the new chwall_ste binary policy representation + # xm dumppolicy + should print the new binary policy representation + including the policy name example.chwall_ste.client_v1 + # xm list --label + should show security label names behind the running domains + +For more information about how to use the security-enabled Xen, see +the examples.txt file in this directory. diff -r 681a18bf049e -r c7b9b8a64755 tools/security/policy.txt --- a/tools/security/policy.txt Mon Apr 24 10:59:17 2006 +0100 +++ b/tools/security/policy.txt Mon Apr 24 10:59:57 2006 +0100 @@ -59,22 +59,34 @@ configuration (see i. and ii.) if the op configuration (see i. and ii.) if the operation proceeds of if the operation is aborted (denied). - In general, security policy instantiations in the Xen access control -framework are defined by two files: - -a) a single "policy-name"-security_policy.xml file that defines the -types known to the ACM and policy rules based on these types - -b) a single "policy-name"-security_label_template.xml file that -defines labels based on known types - -Every security policy has its own sub-directory under -"Xen-root"/tools/security/policies in order to simplify their -management and the security policy tools. We will describe those files -for our example policy (Chinese Wall and Simple Type Enforcement) in -more detail as we go along. Eventually, we will move towards a system -installation where the policies will reside under /etc. +framework are defined by XML policy files. Each security policy has +exactly one file including all the information the hypervisor needs to +enforce the policy. + +The name of a policy is unique and consists of a colon-separated list +of names, which can be translated into the location (subtree) where +this policy must be located. The last part of the name is the file +name pre-fix for the policy xml file. The preceding name parts are +translated into the local path relative to the global policy root +(/etc/xen/acm-security/policies) pointing to the policy xml file. For +example: example.chwall_ste.client_v1 denotes the policy file +example/chwall_ste/client_v1-security_policy.xml relative to the +global policy root directory. + +Every security policy has its own sub-directory under the global +policy root directory /etc/xen/acm-security/policies, which is +installed during the Xen installation or can be manually installed +(when switching from a "security disabled" Xen to a "security enabled" +Xen AFTER configuring security, see install.txt) by the command +sequence: + + cd "Xen-root"/tools/security/policies; make install + +We will describe those files for our example policy (Chinese Wall and +Simple Type Enforcement) in more detail as we go along. Eventually, we +will move towards a system installation where the policies will reside +under /etc. CHINESE WALL @@ -117,9 +129,9 @@ Example of a Chinese Wall Policy Instant Example of a Chinese Wall Policy Instantiation ---------------------------------------------- -The file chwall-security_policy.xml defines the Chinese Wall types as -well as the conflict sets for our example policy (you find it in the -directory "xen_root"/tools/security/policies/chwall). +The file client_v1-security_policy.xml defines the Chinese Wall types +as well as the conflict sets for our example policy (you find it in +the directory "policy_root"/example/chwall). It defines four Chinese Wall types (prefixed with cw_) with the following meaning: @@ -168,11 +180,11 @@ SIMPLE TYPE ENFORCEMENT SIMPLE TYPE ENFORCEMENT ======================= -The file ste-security_policy.xml defines the simple type enforcement -types for our example policy (you find it in the directory -"xen_root"/tools/security/policies/ste). The Simple Type Enforcement -policy defines which domains can share information with which other -domains. To this end, it controls +The file client_v1-security_policy.xml defines the simple type +enforcement types for our example policy (you find it in the directory +"policy_root"/example/ste). The Simple Type Enforcement policy defines +which domains can share information with which other domains. To this +end, it controls i) inter-domain communication channels (e.g., network traffic, events, and shared memory). diff -r 681a18bf049e -r c7b9b8a64755 tools/security/readme.txt --- a/tools/security/readme.txt Mon Apr 24 10:59:17 2006 +0100 +++ b/tools/security/readme.txt Mon Apr 24 10:59:57 2006 +0100 @@ -10,20 +10,25 @@ # the access control policy and tools in Xen. ## -1. policy.txt: +1. 'xm' man page + + 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. + +2. policy.txt: describes the general reasoning and examples for access control policies in Xen -2. install.txt +3. install.txt describes the activation of the access control framework in Xen -3. example.txt +4. example.txt describes the available tools for managing security policies in Xen and the tools to label domains - - _______________________________________________ Xen-changelog mailing list Xen-changelog@xxxxxxxxxxxxxxxxxxx http://lists.xensource.com/xen-changelog
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |