diff options
Diffstat (limited to 'docs/man/xm.pod.1')
-rw-r--r-- | docs/man/xm.pod.1 | 378 |
1 files changed, 0 insertions, 378 deletions
diff --git a/docs/man/xm.pod.1 b/docs/man/xm.pod.1 index a4525457cb..631408b436 100644 --- a/docs/man/xm.pod.1 +++ b/docs/man/xm.pod.1 @@ -1007,384 +1007,6 @@ 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 communication 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. - -=over 4 - -=item B<setpolicy> ACM I<policy> - -Makes the given ACM policy available to xend as a I<xend-managed policy>. -The policy is compiled and a mapping (.map) as well as a binary (.bin) -version of the policy is created. The policy is loaded and the system's -bootloader is prepared to boot the system with this policy the next time -it is started. - -=back - -=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 - -=over 4 - -=item B<resetpolicy> - -Reset the system's policy to the default state where the DEFAULT policy -is loaded and enforced. This operation may fail if for example guest VMs are -running and and one of them uses a different label than what Domain-0 -does. It is best to make sure that no guests are running before issuing -this command. - -=item B<getpolicy> [--dumpxml] - -Displays information about the current xend-managed policy, such as -name and type of the policy, the uuid xend has assigned to it on the -local system, the version of the XML representation and the status -of the policy, such as whether it is currently loaded into Xen or -whether the policy is automatically loaded during system boot. With -the I<--dumpxml> option, the XML representation of the policy is -displayed. - -=item B<dumppolicy> - -Prints the current security policy state information of Xen. - -=item B<labels> [I<policy>] [B<type=dom>|B<res>|B<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<label> B<dom> I<configfile> [I<policy>] - -=item B<addlabel> I<label> B<mgt> I<domain name> [I<policy type>:I<policy>] - -=item B<addlabel> I<label> B<res> I<resource> [I<policy>] - -=item B<addlabel> I<label> B<vif-idx> I<domain name> [I<policy type>:I<policy>] - - -Adds the security label with name I<label> to a domain -I<configfile> (dom), a Xend-managed domain (mgt), to the global resource label -file for the given I<resource> (res), or to a managed domain's virtual network -interface (vif) that is specified by its index. 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. - -The only I<policy type> that is currently supported is I<ACM>. - -=item B<rmlabel> B<dom> I<configfile> - -=item B<rmlabel> B<mgt> I<domain name> - -=item B<rmlabel> B<res> I<resource> - -=item B<rmlabel> B<vif-idx> I<domain name> - -Works the same as the B<addlabel> command (above), except that this -command will remove the label from the domain I<configfile> (dom), -a Xend-managed domain (mgt), the global resource label file (res), -or a managed domain's network interface (vif). - -=item B<getlabel> B<dom> I<configfile> - -=item B<getlabel> B<mgt> I<domain name> - -=item B<getlabel> B<res> I<resource> - -=item B<getlabel> B<vif-idx> I<domain name> - -Shows the label for a domain's configuration in the given I<configfile>, -a xend-managed domain (mgt), a resource, or a managed domain's network -interface (vif). - -=item B<resources> - -Lists all resources in the global resource label file. Each resource -is listed with its associated label and policy name. - -=item B<dry-run> I<configfile> - -Determines if the specified I<configfile> describes a domain with a valid -security configuration for type enforcement. The test shows the policy -decision made for each resource label against the domain label as well as -the overall decision. - -B<CONFIGURING SECURITY> - -=over 4 - -In xen_source_dir/Config.mk set the following parameter: - - XSM_ENABLE ?= y - ACM_SECURITY ?= y - -Then recompile and install xen and the security tools and then reboot: - - cd xen_source_dir; make clean; make install - reboot into Xen - -=back - -B<RESETTING THE SYSTEM'S SECURITY> - -=over 4 - -To set the system's security policy enforcement into its default state, -the follow command can be issued. Make sure that no guests are running -while doing this. - - xm resetpolicy - -After this command has successfully completed, the system's DEFAULT policy -is enforced. - -=back - -B<SETTING A SECURITY POLICY> - -=over 4 - -This step sets the system's policy and automatically loads it into Xen -for enforcement. - - xm setpolicy ACM example.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.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 - -The B<addlabel> subcommand can attach 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-homebanking 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 dom_HomeBanking dom myconfig.xm - -The very simple configuration file might now look as printed -below. The B<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<ATTACHING A SECURITY LABEL TO A XEND-MANAGED DOMAIN> - -=over 4 - -The addlabel subcommand supports labeling of domains that are managed -by xend. This includes domains that are currently running, such as for -example Domain-0, or those that are in a dormant state. -Depending on the state of the system, it is possible that the new label -is rejected. An example for a reason for the rejection of the relabeling -of a domain would be if a domain is currently allowed to -access its labeled resources but due to the new label would be prevented -from accessing one or more of them. - - xm addlabel dom_Fun mgt Domain-0 - -This changes the label of Domain-0 to dom_Fun under the condition that -this new label of Domain-0 would not prevent any other domain from -accessing its resources that are provided through Domain-0, such as for -example network or block device access. - -=back - -B<ATTACHING A SECURITY LABEL TO A RESOURCE> - -=over 4 - -The B<addlabel> subcommand can also be used to attach a security -label to a resource. Following the home banking example from above, -we can label a disk resource (e.g., a physical partition or a file) -to make it accessible to the home banking domain. The example policy -provides a resource label, res_LogicalDiskPartition1(hda1), that is -compatible with the HomeBanking domain label. - - xm addlabel "res_LogicalDiskPartition1(hda1)" res phy:hda6 - -After labeling this disk resource, it can be attached to the domain -by adding a line to the domain configuration file. The line below -attaches this disk to the domain at boot time. - - disk = [ 'phy:hda6,sda2,w' ] - -Alternatively, the resource can be attached after booting the domain -by using the B<block-attach> subcommand. - - xm block-attach homebanking phy:hda6 sda2 w - -Note that labeled resources cannot be used when security is turned -off. Any attempt to use labeled resources with security turned off -will result in a failure with a corresponding error message. The -solution is to enable security or, if security is no longer desired, -to remove the resource label using the B<rmlabel> subcommand. - -=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<LISTING LABELED RESOURCES> - -=over 4 - - xm resources - - phy:hda6 - type: ACM - policy: example.chwall_ste.client_v1 - label: res_LogicalDiskPartition1(hda1) - file:/xen/disk_image/disk.img - type: ACM - policy: example.chwall_ste.client_v1 - label: res_LogicalDiskPartition2(hda2) - -=back - -B<POLICY REPRESENTATIONS> - -=over 4 - -We distinguish three representations of the Xen access control policy: -the source XML version, its binary counterpart, and a 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<setpolicy> subcommand to ensure that the new policy is -available to xend. Use, for example, the subcommand -B<activatepolicy> 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<setpolicy> 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<setpolicy>) and is used by xend and the management -tools to translate between label names used as input to the tools and -their binary identifiers (ssidrefs) used inside Xen. - -=back - -=back - =head1 SEE ALSO B<xmdomain.cfg>(5), B<xentop>(1) |