Update README files.HEADmaster

2 files changed, 42 insertions, 1 deletions

diff --git a/README b/README
index 4d4e9e6..a249528 100644
--- a/README
+++ b/README
@@ -1 +1,4 @@
-SELinux Enhanced Selection Manager
+This repo is meant to be a catch-all for client-side applications and
+utilities supporting the X SELinux extension.
+
+See README.demo for information about the device relabeling demo.
diff --git a/README.demo b/README.demo
new file mode 100644
index 0000000..4c957da
--- /dev/null
+++ b/README.demo
@@ -0,0 +1,38 @@
+The input relabeling demonstration works by dynamically setting the context
+of the keyboard and mouse devices during an X session.  What this does is
+allow policy to be written to prevent input events from going anywhere but
+a selected X application or applications while the device is in a relabeled
+state.
+
+Keep in mind that in XSELinux, input devices are treated as SUBJECTS for
+purposes of input event generation.  This means that the input device security
+context needs permission to "send" events.  The events, in turn, are labeled
+using both the type of event (typically fixed as input_xevent or the like)
+and the destination window of the event.  The result is that the input device
+must be granted permission to "send" input events to any specific window, which
+is labeled off its owning process.
+
+Refer to the XSELinux comprehensive review paper, available on request, for
+the specifics.
+
+The policy/ subdirectory contains the security policy for the demo.  There are
+three pieces:
+1. The "xserver.patch" contains modifications that need to be made to the base
+   policy, which is too permissive in its current form.
+2. The "hapdemo" module contains three custom domains that are used to run
+   apps in different contexts, and three custom contexts used to label the
+   input device, with each device context only able to send events to the
+   corresponding domain's windows.
+3. The "local" module contains some local modifications to support the demo,
+   mostly just putting certain executables in execmem context.
+
+The demo/ subdirectory contains supporting scripts for the demo.  The xinitrc
+file is used with xinit/startx to set up the demo environment.  The cursoncon
+app runs a dialog box that does the device relabeling.  The eyes.sh runs apps
+under the demo domains.  Finaly, the xcowsaylogmon script monitors the log for
+AVC's.
+
+To get this stuff working you need XCB and xpyb (the XCB python binding),
+which may need to be installed from source.  Right now the only interface to
+the XSELinux X extension is via XCB, since no Xlib client-side support has
+been written for it.