CHANGES
-------
This is a new version of SELinux targeted for submission to mainline
2.5.  It diverges from the old SELinux in several respects:

1) The networking hooks that were rejected for 2.5 have been dropped.
Some of the SELinux networking functionality has been temporarily
dropped because its current implementation depended on the rejected
networking security fields and hooks, but we plan to restore aspects
of this functionality in the future with the existing set of hooks
plus creative use of NetFilter.  At present, this version of SELinux
only implements the general socket layer hooks and Unix domain socket
hooks.

2) The old SELinux API and its implementation via sys_security has
been dropped, and a new API is under development.  The initial focus
for this new API is to support the base SELinux functionality for
processes and files, implemented via nodes in a /proc/pid/attr
directory (for process attributes) and the xattr API (for file
attributes).  A modified form of the security policy API is exported
via a new pseudo filesystem type (selinuxfs).  SELinux applications
will typically use the interface exported by libselinux rather than
directly accessing the /proc/pid/attr, xattr, or selinuxfs APIs.
See PORTING for a discussion of how the libselinux API differs from
the old libsecure API.

Equivalents for the SELinux extended calls for System V IPC and socket
IPC will be investigated in the future.  Please note that the API is
likely to undergo further changes in response to kernel developer
feedback once we submit it, so you should not view it as stable yet.

3) Support for using extended attributes for file security contexts
has been added, and an xattr handler has been implemented for ext[23]
(other handlers to follow in the future).  As with the API, the
specifics of the xattr handler are likely to change in response to
kernel developer feedback.  Caveat: We have encountered problems
booting unmodified 2.4 kernels after assigning extended attributes to
the root filesystem.

4) The initial policy load has been moved into userspace, and is
performed from an initrd (see the BUILDING AND INSTALLING
instructions below).  We will likely migrate to using initramfs in the
future for the initial policy.

5) Various code cleanups and simplifications have been performed.


CONTENTS
--------
After expanding the archives you downloaded, you should have a
linux-2.5 directory and a selinux-2.5 directory.  Or, if you
downloaded the SELinux kernel patch instead of the prepatched kernel
source tree, you should apply that patch to a 2.5 kernel source tree
to produce an equivalent tree.

The linux-2.5 directory contains the SELinux-patched 2.5 kernel.  The
SELinux module lives in linux-2.5/security/selinux.  The ext[23] xattr
handlers live in linux-2.5/fs/ext[23]/xattr_security.c.  The modified
proc code lives in linux-2.5/fs/proc/base.c.  If you look at the
SELinux kernel patch or diff the prepatched tree against a vanilla 2.5
kernel, you'll notice that there are a few other differences related
to early initialization of security modules, xattr-related security
hooks, process attribute security hooks, etc.  These changes will need
to be merged as well to support SELinux.

The selinux-2.5 directory contains SELinux userland components that
are compatible with the new version of the SELinux kernel code.  At
present, these userland components are:

1) checkpolicy
The checkpolicy program compiles the policy sources into a binary
representation that is loaded by the kernel security server.  It pulls
much of its code directly from the kernel security server sources,
using macros to permit building this code into a userspace
application.  Code cleanups and Linux "nativization" of the kernel
security server required corresponding updates to the checkpolicy
program sources, so the updated checkpolicy sources are available
here.  The binary policy representation has also changed from the
old SELinux, so you must use this checkpolicy program to compile your
policy for the new SELinux kernel.  

2) libselinux
This library provides a set of interfaces for security-aware
applications to get and set process and file security contexts and to
invoke the policy API.  It provides a layer of abstraction over the
/proc/pid/attr API, the xattr API, and the selinuxfs API for SELinux
applications.  It also handles memory allocation for security
contexts.  Since the file context functions are implemented via the
[gs]etxattr calls, you must also link with libattr if you are using
those functions.  The policy API calls assume that selinuxfs has
already been mounted on /selinux, e.g.
	mount -t selinuxfs none /selinux

See PORTING for a discussion how the libselinux API differs from the
old libsecure API.

3) setfiles
The setfiles utility assigns security labels to all files in the
filesystem based on a specification.  It has been changed to use
extended attributes by default, and uses libselinux to get and set the
file contexts and to check the validity of the contexts.  To build it,
you must have libattr-devel installed (you can obtain it from
acl.bestbits.at).  Prior to running setfiles to label your
filesystems, you must have built and booted the new SELinux kernel
(discussed further below).  If you already have a persistent label
mapping (from the old SELinux), the new SELinux kernel will continue
to use it for the initial boot.  After initially assigning extended
attributes to all files, you can then reboot your SELinux kernel to
get into a proper initial state and it will automatically begin using
the extended attributes.

4) load_policy
The load_policy utility can be used to load the policy configuration.
It has been changed to use libselinux to access the selinuxfs policy
API.

5) newrole
The newrole utility can be used to change the user's role.  It
has been changed to use libselinux.

6) utils
This directory contains trivial utilities to permit experimentation
with the process context API, the file context API, and the policy API
exported by libselinux.  The file utilities also depend on libattr. 

7) policy
This directory contains a fork of the example policy, pruned down to
just the core components and updated for changes in the new SELinux,
e.g. selinuxfs labeling and allow rules, permissions for getting
and setting process attributes via /proc/pid/attr, etc.  See PORTING
for a discussion of how the policy has changed from the old SELinux.

8) patches
This directory contains the SELinux patches for the daemons and utilities
updated to use the libselinux API.  Porting of these patches is still in 
progress, so only a subset of the SELinux patches are here presently.
The most critical patches are the ones for login (util-linux), sshd,
and crond.  These patches initialize the user security context for
user sessions and cron jobs.

9) SRPMS
This directory contains SRPMS for the patched daemons and utilities,
including the SELinux patches above.


KERNEL CONFIGURATION
--------------------
When you configure your patched linux-2.5 kernel, you should note the
following items:

Under Filesystems, be sure to enable the Ext[23] extended attributes and
Ext[23] Security Labels options (CONFIG_EXT[23]_FS_XATTR,
CONFIG_EXT[23]_FS_SECURITY).  

Under Pseudo Filesystems, be sure to enable the /dev/pts
Extended Attributes and /dev/pts Security Labels options 
(CONFIG_DEVPTS_FS_XATTR, CONFIG_DEVPTS_FS_SECURITY).

Under Security, be sure to enable all of the following options:
	Enable different security models (CONFIG_SECURITY)
	Socket and Networking Security Hooks (CONFIG_SECURITY_NETWORK)
	Capabilities Support (CONFIG_SECURITY_CAPABILITIES)
	NSA SELinux Support (CONFIG_SECURITY_SELINUX)
	NSA SELinux Development Support (CONFIG_SECURITY_SELINUX_DEVELOP)


BUILDING AND INSTALLING
------------------------
0) Obtain the libattr-devel package from acl.bestbits.at and install it.
This is required to build the new setfiles program.  You will also likely 
want the libattr and attr packages in order to use their getfattr and
setfattr utilities to get and set the attributes of individual files. 

1) Configure, build and install the patched linux-2.5 kernel, and
configure your boot manager so you can boot it.

2) Build and install libselinux, checkpolicy, setfiles, load_policy, etc.
	cd selinux-2.5
	make install

3) Edit policy/users for your users, and then build and install the policy.
	cd selinux-2.5/policy
	make install-src install

4) Build and install the SELinux-patched daemons and utilities.
You can either merge the patches from the patches subdirectory
into the base packages that you are using, or just use the SRPMS
from the SRPMS subdirectory.

5) Copy the daemon and utility configuration files from the appconfig
subdirectory into /etc/security.

6) Create an initrd with load_policy, the binary policy file, and a
/linuxrc that will perform the initial policy load.  For example, you
might modify your mkinitrd script to include something like the
following:
  mkdir -p $MNTIMAGE/selinux
  mkdir -p $MNTIMAGE/etc/security/selinux
  cp /etc/security/selinux/policy.14 "$MNTIMAGE/etc/security/selinux/policy.14"
  cp /usr/local/selinux/bin/load_policy "$MNTIMAGE/bin/load_policy"

  echo "echo Loading policy" >> $RCFILE
  echo "mount -t selinuxfs none /selinux" >> $RCFILE
  echo "/bin/load_policy /etc/security/selinux/policy.14" >> $RCFILE

7) Create the /selinux mountpoint directory (i.e. mkdir /selinux) and
update your /etc/fstab to mount selinuxfs, e.g. add an entry like:
	none /selinux selinuxfs defaults 0 0

8) Boot the SELinux kernel.  If you have a persistent label mapping
from an old SELinux kernel, the new kernel will use it.  Login as root
with the sysadm_r role and sysadm_t domain.

9) Assign extended attributes to your filesystems.
Caveat: We have encountered problems booting unmodified 2.4 kernels
after assigning extended attributes to the root filesystem.
	cd selinux-2.5/policy
	make relabel

10) Reboot the SELinux kernel.  The SELinux kernel will start using the
extended attributes and ignore any persistent label mapping.

11) It may be necessary to relabel your filesystems again, as some
files may have been created during the prior shutdown and lack any
extended attribute value (defaulting to the default file security
context).  
	cd selinux-2.5/policy
	make relabel


EXPERIMENTING WITH THE NEW API
------------------------------
1) You can run getfattr and setfattr to directly get and set
individual file attributes, e.g.:
	getfattr -n security.selinux /etc/shadow
	setfattr -n security.selinux -v system_u:object_r:shadow_t /etc/shadow
These utilities are directly implemented via getxattr and setxattr.

However, it is preferable to run the getfilecon and setfilecon
utilities from the utils directory, e.g.:
	getfilecon /etc/shadow
	setfilecon system_u:object_r:shadow_t /etc/shadow
These utilities are implemented using the corresponding libselinux
functions, and encapsulate the use of xattr and the particular attribute
name.

The mkdircon utility from the utils subdirectory provides an
example of how to create a directory (or any kind of file) with a
specific security context if you do not want the default file labeling
behavior, e.g.:
	mkdircon system_u:object_r:shadow_t foo
This utility calls the setfscreatecon function in libselinux to set
the desired context prior to calling mkdir to create the directories.
Internally, setfscreatecon writes the desired context to
/proc/self/attr/fscreate.  Note that setting this attribute using a
shell command is ineffective, since the fscreate attribute is cleared
on execve for safety, reverting to the default file labeling behavior
upon initialization of each program.  Also, note that a process is
only permitted to set its own /proc/self/attr/fscreate value.
Permission to create a file with the security context is checked on
the file creation call, when the full context of the operation is
known (i.e. the kind of file, the parent directory, the filesystem).
Hence, a successful write to /proc/self/attr/fscreate does not
guarantee that the caller has the necessary permission for the
context.

2) You can run the getcon utility from the utils subdirectory to
display the current security context.  This utility calls the
corresponding libselinux function, which simply reads the context from
/proc/self/attr/current.  Writing to this node is not permitted in
SELinux, since processes are only permitted to change security
contexts on execve (when you can control the initialization of the
process in the new context and the inheritance of state in a
reasonable manner).  You can read the contexts of other processes
via their /proc/pid/attr/current nodes if permitted by the policy.
The getpidcon utility from the utils subdirectory demonstrates this.

The execcon utility from the utils subdirectory provides an
example of how to run a program in a particular security context if
you do not want the default process labeling behavior, e.g.:
	execcon root:sysadm_r:sysadm_t bash
This utility calls the setexeccon function in libselinux to set the
desired context prior to calling one of the exec calls.  Internally,
setexeccon writes the desired context to /proc/self/attr/exec.
Setting this attribute via a shell command is ineffective, since the
attribute is cleared on execve for safety.  A process can only set its
own /proc/self/attr/exec value.  Permission to run a program in the
security context is checked on the execve call, when the full context
of the operation is known (i.e. the executable program).  Hence, a
successful write to /proc/self/attr/exec does not guarantee that the
caller has the necessary permission for the context.

3) You can mount selinuxfs (mount -t selinuxfs none /selinux) to
access the policy API, and can then run load_policy or the utilities
in the utils directory.  The /selinux directory is described below,
along with discussion of utilities that access it via libselinux:

a) 'enforce' can be read or written to get or set the enforcing
status, e.g. 'echo -n 1 > /selinux/enforce' switches into enforcing
mode. Don't switch into enforcing mode unless you have addressed the
policy issues, particularly since we don't have a full userland
environment yet that uses the new APIs and the example policy is still
expecting that modified userland.  Note that the enforcing status can
only be changed if you built with the Development Support option
enabled; otherwise, SELinux is always in enforcing mode.

b) 'load' can be written to load a new policy configuration.  The
load_policy utility opens and mmaps a binary policy file and then
calls the security_load_policy function in libselinux to load the
policy (by writing it to this node).

c) 'context' can be written to check the validity of a security
context.  The setfiles utility calls the security_check_context
function in libselinux to check contexts in the specification by
writing them to this node and checking the return value.

d) 'access' can be written to request an access decision and can then
be read to obtain the decision.  On a write, the decision is computed
and saved in the open file private data, and will be returned
on subsequent reads by that process until the file is closed. 
Hence, different processes accessing this node will not
interfere with one another.  The compute_av utility calls the
security_compute_av function in libselinux to obtain access decisions
using this node, e.g.:
	compute_av root:user_r:user_t system_u:system_r:sshd_t process

e) 'create' can be written to request a labeling decision and can then
be read to obtain the decision.  As with /selinux/access, the decision
is saved in the open file private data for subsequent reads.
The compute_create utility calls the security_compute_create function 
in libselinux to obtain labeling decisions using this node, e.g.:
	compute_create root:user_r:user_t system_u:object_r:tmp_t file

f) 'relabel' can be written to request a relabeling decision and can
then be read to obtain the decision.  As with /selinux/access, the
decision is saved in the open file private data for subsequent reads.
The compute_relabel utility calls the security_compute_relabel function 
in libselinux to obtain labeling decisions using this node, e.g.:
	compute_relabel root:user_r:user_t system_u:object_r:tty_device_t chr_file

g) 'user' can be written to obtain the set of reachable user contexts
and can then be read to obtain the set.  As with /selinux/access, the
information is saved in the open file private data for subsequent reads.  
The compute_user utility calls the security_compute_user function in
libselinux to obtain user context sets using this node, e.g.:
	compute_user system_u:system_r:local_login_t root
	compute_user system_u:system_r:sshd_t root
