It is recommended that the Notebook Source file is installed in your $HOME as this contains all the configuration files and source code required to produce the required modules. It also contains README and a simple Makefile for each section.

This section assumes the following:

The message filter modules have been removed before starting this exercise, however it is not mandatory.

SELinux is configured to use the modular-test policy in permissive mode initially to build the services. The modular-test policy is decribed in the Building the Base Policy Module section.

The loadable modules used to support these exercises are built using standard SELinux language statements and rules with customised x_contexts files to support the labeling of objects.

The test applications are written in 'C' and use the Xlib function library with Xdevice functions provided by the Xi library. There were a few problems encountered that are discussed in the Calling the XSELinux Functions section.

The source files required to build and manage the new x_contexts files and supporting loadable module are located in:

./notebook-source/x-windows/x-contexts-base-module

As the objective of the demonstration is to show how different entries in the x_contexts file affect the use of selections it was decided to build two x_contexts files based on those in the Reference Policy 20090730 build. To support the new entries created in these x_contexts files, required an additional loadable module (x_context_base.conf).

The x_contexts files are expanded to give each entry a unique label so that it could be detected in the audit log with audit2allow when in enforcing mode, a decision could then be made as to whether an allow or dontaudit rule would be added to the policy. Additional entries were also added just to experiment. A second copy of the file was made that had the poly_ keyword added to the property and selection entries to test polyinstantiation.

The only entry that caused problems during testing was the:

poly_property _XKB_RULES_NAMES .....

This entry had to have the poly_ keyword removed in the polyinstantiated file as it stopped various keys from working (up/down etc. keys) on the keyboard.

The new x_contexts files generated are called:

x_contexts-file-with-new-labels - This file is similar to that used by the reference policy. The select and paste policy uses the same method to manage the labeling as the reference policy - called derived labeling as the objects label is derived from an SELinux user name or a prefix (from the 'users_extra' configuration file), then use a type_transition to transition the object to the new label on creation. For example (using standard Refpolicy):

An x_contexts entry of:

event X11:MapNotifysystem_u:object_r:manage_xevent_t

and the ssh policy module (after expansion) having a type_transition statement generated by the build process of:

type_transition ssh_t manage_xevent_t : x_event ssh_manage_xevent_t;

will relabel any objects created from manage_xevent_t to ssh_manage_xevent_t.

x_contexts-file-with-new-polylabels - This is used to support polyinstantiated entries (note - the reference policy does not currently use polyinstantiated entries). With polyinstantiation enabled, the select and paste policy uses the type_member rule to enforce the selection to a specific domain (in this example the x_select_paste_t domain) as follows:

To support these new x_contexts file entries an additional policy module was built that defines a type for each entry and a corresponding allow rule. This module is called x_context_base.conf and must be loaded and active when the modular-test policy is loaded with either of the new x_contexts files. Failure to do this will probably result in the system hanging as it tries to load X-Windows with no defined type or allow rules for the new x_contexts file.

The source files required to build and manage the application and loadable module are located in:

./notebook-source/x-windows/x-select+paste

There are two simple X-Windows applications that select (X-select) and paste (X-paste) “Hello World” using Xlib selection functions. When they are loaded they show the application name and their context in the title bar as shown in Figure 1. Integrated with these applications are calls to the XSELinuxGet.. functions to return context information as the Xlib functions are executed.

The output from the applications can also be captured in a file by adding the capture file name as an argument:

X-select poly-demo.txt
# The output will be in poly-demo.txt, with some text also
# displayed on the screen.

When the two applications are built they are moved to /usr/local/bin and have the default label of unconfined_t. When they are both loaded in the unconfined_t domain, there are no enforced rules (i.e. there are no restrictions). If the x_select_paste.conf module is built and loaded, then when they are run as:

runcon -t x_select_paste_t X-select

and

runcon -t x_select_paste_t X-paste

Policy will be enforced as required depending on a boolean that when set to:

setsebool -P poly-selection false

and the x_contexts-file-with-new-labels file is installed as the x_contexts file, then the derived policy rules will be enforced.

If the boolean is set to:

setsebool -P poly-selection true

and the x_contexts-file-with-new-polylabels file is installed as the x_contexts file, then the polyinstantiated policy rules will be enforced.

Using the non-polyinstantiated x_contexts file (with poly-selection = FALSE), resulted in selections being seen across all windows whether running in unconfined_t or x_select_paste_t domains.

Using the polyinstantiated x_contexts file (with poly-selection = TRUE), resulted in selections being restricted to windows running in their own domains (e.g. if running the X-select in the unconfined_t domain and X-paste in the x_select_paste_t domains, the selected text will not be pasted).

If the following multiple selection entries are added to the x_contexts file, then the non poly_ entry takes precedence. This means that polyinstantiation for selections will not work (even if a different label is used for each entry).

Therefore the overall conclusion is that for non-MLS policies, the only effective way to control selections is using polyinstatiation with the type_member rule.

The reason for stating non-MLS policy is that the MLS policy uses mlsconstrain rules to manage restrictions. Various constrain rules were used for non-MLS policy testing but no satisfactory result could be obtained - do you know different !!!

Notes:

When using polyinstantiation the poly_ keyword must be present in the x_contexts file and there must be a corresponding type_member rule in the policy.

When analysing the output from the XSELinux function calls between non-polyinstantiated (or derived) and polyinstantiated services when the X-select and X-paste applications are running (apart from their context information), the only major difference was that when calling the SELinuxListSelections function, the polyinstantiated service had an additional PRIMARY entry as follows:

The Reference Policy does not use polyinstantiation but supports isolation only with the MLS policy where mlsconstrain rules are enforced (see the mlsconstrain x_selection entries in the mls configuration file).

Various constrain rules were tried to limit selections with the non-polyinstantiated x_contexts file, but no satisfactory solution was found - any offers !!, therefore when using non-MLS policy, the only way to limit selections is via polyinstantiation. Some example constrain rules tried that had the following results:

The X-select, X-paste and X-setest applications call the object manager XSELinuxGet/Set.. functions to get and set contexts as required. To use these functions the standard Xlib GetReq, _XSend and _XReply functions need to be called to manage the request / response sequences. As there are 23 functions it was decided to build these into a separate 'C' module called XSELinuxOMFunctions.c that is supported by a header file called Xlib-selinux.h. that are located in the ./x-windows/x-common directory.

The header file is based on the XSELinux extension source header xselinux.h and has been expanded to support the Xlib GetReq macro and associated functions. The only point to note is that the SELinuxQueryVersion request header structure size had to be set to 4 instead of 6 as the client_major and client_minor entries were not used and caused errors when added.

The error handling caused much grief (as not an Xlib expert), and it will be seen that there are a number of flags to indicate certain error sequences. The source code has plenty of comments regarding these and if anyone has better methods let the author know.

To build and test the infrastructure to support modified x_contexts files for the X-Windows object manager, the following will be required:

The Base Module described in the Building the Base Policy Module section. This will install the base policy module and supporting files in the /etc/selinux/modular-test area.

Two modified x_contexts files. The Reference Policy sample has been modified to capture additional entries and for each entry allocate its own unique object label. There is one file to support the way the Reference Policy (build 20090730) supports these objects[1], and the other has the additional 'poly_' keyword added to support polyinstantiated property and selection entries.

Important note - These sample x_contexts files must not be used with the reference policy as they are incompatible and will cause the system to hang when X-Windows is being loaded

A loadable module (x_context_base.conf) that contains the policy type statements and allow rules of the newly defined x_contexts file entries described in bullet b). This will allow the X-Windows object manager to load the new x_contexts file without any errors.

Two simple X-Windows applications - X-select to automatically select some text (Hello World), and X-paste to paste the text onto the screen. These applications use the minimum Xlib functions possible, however they also contain calls to the SELinux X-Windows functions that are built into the object manager to retrieve context information as the applications execute.

A loadable module (x_select_paste.conf) that contains the policy for enforcing the X-select and X-paste applications when running in the x_select_paste_t domain. This policy supports the polyinstantiated x_contexts file by setting a boolean (poly-selection) to TRUE and the the derived x_contexts file by setting the boolean to FALSE.

Build the new x_contexts files and a loadable module (x_context_base.conf). The files to are available in the source file and located in the ./notebook-source/x-windows/x-contexts-base-module directory.

Build the X-select, X-paste applications and their supporting loadable module for running in the x_select_paste_t domain.

Install the derived (non-polyinstantiated) x_contexts file and test using the X-select and X-paste applications in various scenarios using the unconfined_t and x_select_paste_t domains, recording the results.

Install the polyinstantiated x_contexts file and test using the X-select and X-paste applications in various scenarios using the unconfined_t and x_select_paste_t domains, recording the results.

Before building and installing these, ensure that the modular-test base module has been built, if it has proceed as follows:

Ensure you are logged on as root and SELinux is running in permissive mode (setenforce 0) to perform the build process. It is assumed that the files are built in the ./notebook-source/x-windows/x-contexts-base-module directory.

Optionally clear the log file so that they are clear for easier reading after the reboot:

> /var/log/audit/audit.log

Ensure that SELinux is configured to run in permissive mode with the modular-test policy enabled, then reboot the system to ensure X-windows loads the new x_contexts file entries.

reboot

The system should reload with no errors, however if the screen should remain blank then the chances are that the x_contexts file is incorrect and the repair disk will be required to replace the x_contexts file with the one produced in the Building the Base Policy Module section. Alternatively, reboot with a know good policy and check the modular-test policy x_contexts entries.

Run the setenforce 1 command and then check the audit log for USER_AVC errors (there should not be any errors).

Note that the x_contexts file currently loaded is the standard (non-poly) version.

Before building and installing these applications, ensure that the libraries and development packages have been installed.

The easiest way to build these applications is to use the notebook-source files (the X-select and X-paste code is in the ./notebook-source/x-windows/x-select+paste directory). The code to manage the XSELinux functions is quite long and also requires a header file (these are contained in the ./notebook-source/x-windows/x-common directory). The source files also contain a pre-compiled set of applications that only need to be copied to /usr/local/bin. However to build from scratch proceed as follows:

Ensure you are logged on as root and SELinux is running in permissive mode (setenforce 0) to perform the build process. It is assumed that the applications will be built in the ./notebook-source/x-windows/x-select+paste directory, but the XSELinux function call code will be in the ./notebook-source/x-windows/x-common directory as it is shared by the X-setest application as well.

In the ./notebook-source/x-windows/x-common directory, produce the header file with the following entries Xlib-selinux.h.

Copy the X-select and X-paste application binaries to /usr/local/bin as follows:

cp X-select /usr/local/bin
cp X-paste /usr/local/bin

The applications can be tested by calling them from separate virtual terminals, although they will only be running in the unconfined_t domain as shown in Figure 1 (until the policy module is built as described in the next section). Note that the x_contexts file loaded in the previous section is the standard (non-poly) version.

This loadable module is to enforce policy on the X-select and X-paste applications when they are run in the x_select_paste_t domain using the SELinux runcon commands as follows:

# Note the runcon commands would be run from different virtual
# terminals to activate and test the applications.
runcon -t x_select_paste_t X-select
runcon -t x_select_paste_t X-select

The policy has a poly-selection boolean that by default is set to FALSE and controls what policy rules are enforced depending on what verion of the x_contexts file is loaded (although note that the boolean does NOT control what file is loaded, that is a user copy function):

The system is now ready for testing various select / paste scenarios. Note that by default the poly-selection boolean is set to FALSE and the x_contexts-file-with-new-labels file has been installed as the /etc/selinux/modular-test/contexts/x_contexts file.

Ensure the correct x_contexts file is installed. This can be done by checking that there are no poly_ entries in the /etc/selinux/modular-test/contexts/x_contexts file. If the file is not correct, then copy the correct version over by:

If the X-select and X-paste applications were not built as described in the Building the X-select and X-paste Applications section, then the executables can be copied from the ./notebook-source/x-windows/x_select+paste directory to the /usr/local/bin directory. They should default to unconfined_t that can be checked as follows:

Open two virtual terminal sessions so that the applications can be run. A third can be opened for monitoring the audit log for errors.

Run setenforce 1 for enforcing mode.

Test 1:

The X-select and X-paste applications are called directly, one in each terminal session and will therefore run under the unconfined_t domain:

Terminal 1: X-paste
Terminal 2: X-select

The results can be seen in Figure 1 where "Hello World" is displayed on Terminal 1 (note that if any text has been selected by another window, then that text will probably be displayed instead of "Hello World").

There is other information displayed that shows the various context information using the SELinuxGet.. functions that can be examined if required.

As can be seen the selected text can be pasted from both the unconfined_t and x_select_paste_t domains. This means that using standard reference policy type x_contexts file entries for selections, separation cannot be achieved (although note that the MLS version of reference policy may do - need to check one day).

If the policy is analysed, it will be seen that even though a type transition has been defined for the primary_xselection_t object:

# audit2allow never indicated that an allow rule was needed
# like this (that would be required if a new instance was created)
allow x_select_paste_t user_ primary_xselection_t : x_selection { read ... };

Ensure the correct x_contexts file is installed. This can be done by checking that there are poly_ entries in the /etc/selinux/modular-test/contexts/x_contexts file. If the file is not correct, then copy the correct version over by:

If the X-select and X-paste applications were not built as described in the Building the X-select and X-paste Applications section, then the executables can be copied from the ./notebook-source/x-windows/x_select+paste directory to the /usr/local/bin directory. They should default to unconfined_t that can be checked as follows:

Open two virtual terminal sessions so that the applications can be run. A third can be opened for monitoring the audit log for errors.

Run setenforce 1 for enforcing mode.

Test 1:

The X-select and X-paste applications are called directly, one in each terminal session and will therefore run under the unconfined_t domain:

Terminal 1: X-paste
Terminal 2: X-select

The results can be seen in Figure 4 where "Hello World" is displayed on Terminal 1 (note that if any text has been selected by another window, then that text will probably be displayed instead of "Hello World").

There is other information displayed that shows the various context information using the SELinuxGet.. functions that can be examined if required.

The results can be seen in Figure 5 where "Hello World" is displayed on Terminal 1.

Test 3:

The applications are then loaded as follows:

Terminal 1: runcon -t x_select_paste_t X-paste
Terminal 2: X-select

As shown in Figure 6, the X-paste application does NOT receive "Hello World” as the selections are blocked by the polyinstantiation functionality.

Test 4:

With this test the poly-selection boolean is set to FALSE:

setsebool -P poly-selection false

The applications are then loaded as follows:

Terminal 1: runcon -t x_select_paste_t X-paste
Terminal 2: X-select

As shown in Figure 7, the X-paste application running on terminal 1 does not receive "Hello World" for the following reasons:

The selections are being detected by the X-paste application because the type_member rule has been disabled, therefore polyinstantiation is not being enforced by the policy (as to enforce polyinstantiation both the poly_ entries in the x_contexts file is required plus a supporting type_member rule (and of course any allow rules)).

The application name and context is not displayed in the X-Window title bar and the terminal screen shows two error returns when getting the property context entries as shown below (the resourceID: 39 is WM_NAME - see Xatom.h).

↑ Also known as 'derived type' because the objects are assigned labels that are derivied from a name based on the SELinux user or a prefix (e.g. from the 'users_extra' configuration file) and then uses a type_transition statement to transition the object to the new label on creation.