CHANGES
-------
This is a new version of SELinux that has been accepted into mainline Linux.
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 has been developed.  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.

3) The persistent label mapping has been dropped, and support for 
using extended attributes for file security contexts has been added, with 
xattr handlers presently implemented for ext[23].  Caveat: We have encountered
problems booting unmodified 2.4 kernels after assigning extended attributes 
to the root filesystem.  We have been able to boot 2.4 kernels patched with 
the EA patch from acl.bestbits.at.

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.


COMPONENTS
----------
You will need the following components:

1) Linux kernel with SELinux patch merged.

2) checkpolicy
The checkpolicy program compiles the policy sources into a binary
representation that is loaded by the kernel security server.  The
binary policy representation has changed from the old SELinux, so you
must use this checkpolicy program to compile your policy for the new
SELinux kernel.

3) 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.  It depends on libattr-devel for the xattr calls.  Since the
file context functions are implemented via the [gs]etxattr calls, you
must also link applications that use libselinux with libattr.  The
policy API calls assume that selinuxfs has already been mounted on
/selinux, e.g.
	mount -t selinuxfs none /selinux

The libselinux/utils subdirectory contains simple utilities that
permit experimentation with the process context API, the file context
API, and the policy API exported by libselinux.  

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

4) policycoreutils
This package contains the policy core utilities that are required for
basic operation of a SELinux system.  These utilities include
load_policy to load policies, setfiles to label filesystems, newrole
to switch roles, and run_init to run /etc/init.d scripts in the proper
context.  These utilities have been rewritten from the old SELinux to
use the libselinux interfaces.

5) policy
This package contains the SELinux example policy configuration along
with the Flask configuration information and the application
configuration files.  The policy has been adapted for changes from the
old SELinux.  See PORTING for a discussion of how the policy has
changed from the old SELinux.

6) patched daemons and utilities
Several packages have been patched for SELinux.  The SELinux patches
have been rewritten to use the libselinux interfaces (see PORTING).

There is a patch to glibc (glibc-secureexec.patch) to support secure
transitions for role/domain changes, but this change has now been
upstreamed (and is generalized for arbitrary Linux security modules).
Please verify that your glibc supports the AT_SECURE auxv entry.

Of the other SELinux patches, the most critical patches are the ones
for login (util-linux-selinux.patch), sshd (openssh-selinux.patch),
and crond (vixie-cron-selinux.patch).  These patches initialize the
user security context for user sessions and cron jobs.

The SELinux wrappers for programs that modify /etc/passwd and
/etc/shadow (in order to preserve their security contexts and to
ensure that uid 0 cannot arbitrarily change other users' information)
are being reimplemented as direct patches to various packages
(util-linux, shadow-utils, passwd, libuser, pam, pwdb, etc).

SELinux patches also exist for many common utilities to provide
support for manipulating process and file security contexts,
e.g. coreutils, findutils, logrotate, procps, psmisc.


KERNEL CONFIGURATION
--------------------
When you configure your SELinux-patched 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)
	NSA SELinux boot parameter (CONFIG_SECURITY_SELINUX_BOOTPARAM)

BUILDING AND INSTALLING
------------------------
1) Configure, build and install the SELinux-patched kernel, and
configure your boot manager so you can boot it.
	cd linux-2.6
	make menuconfig
	make 
	make modules_install
	make install

If you do not enable the NSA SELinux boot parameter option
(CONFIG_SECURITY_SELINUX_BOOTPARAM) in your kernel configuration, then
it is also recommended that you configure and build a separate kernel
that has the Ext[23] Security Labels options enabled but SELinux
disabled for use as a maintenance kernel.  This maintenance kernel can
be used to manipulate the file security labels without interference by
the SELinux module to perform emergency recovery.  If you did enable
the NSA SELinux boot parameter option, then you can simply boot with
"selinux=0" to disable the SELinux module at boot time to perform
emergency recovery.

You may want to configure and build a 2.4+EA kernel if you still want
to boot 2.4 kernels on your system, as unmodified 2.4 kernels will not
boot after you have assigned the SELinux EAs to the root filesystem.

2) Build and install the new SELinux packages (checkpolicy,
libselinux, policycoreutils, policy).

If you downloaded the 'selinux-usr' archive, the 'build' script can be
run to build and install the new SELinux packages via rpm so that the
rpm database is properly updated and any other packages that depend on
the new SELinux packages can be built with rpm.  You can then skip
2a-d below, although you will want to customize the policy as
described in 2d prior to running 'build'.  To run the 'build' script,
do:
	cd selinux-usr
	su
	./build
You can then skip to step 3.

Individual instructions for building and installing each of the new
SELinux packages are below as steps 2a-2d.  These are not necessary if
you used the build script.  Both rpm-based and manual build
instructions are provided below.

2a) Build and install the checkpolicy policy compiler.
	rpmbuild -tb checkpolicy-*.tgz
	rpm -Uvh /usr/src/redhat/RPMS/i386/checkpolicy*.rpm

	-or-

	cd selinux-usr/checkpolicy
	make install

2b) Build and install libselinux.
	rpmbuild -tb libselinux-*.tgz
	rpm -Uvh /usr/src/redhat/RPMS/i386/libselinux*.rpm

	-or-

	cd selinux-usr/libselinux
	make install
	/sbin/ldconfig

2c) Build and install the policy core utilities.
	rpmbuild -tb policycoreutils-*.tgz
	rpm -Uvh /usr/src/redhat/RPMS/i386/policycoreutils*.rpm

	-or-
	
	cd selinux-usr/policycoreutils
	make install

2d) Customize your policy configuration, and then build and install the policy.
Customization of the policy includes:

- Edit policy/users for your users.  The policy/users file defines
each user recognized by the system security policy.  It specifies the
authorized roles for each user.  Be sure to authorize at least one
user for the system administrator roles (staff_r and sysadm_r).  Other
users can be limited to the ordinary user role (user_r).  Remove the
example users provided in the distributed users file (jadmin and
jdoe).  Leave the system_u user unmodified, and do NOT add an entry
for it to /etc/passwd.  Remove the user_u user if you do not want to
allow any login access to any user who is not explicitly listed in
policy/users; otherwise, all unlisted users will be mapped to user_u
(and limited to the user_r role).

- Move up any .te files from policy/domains/program/unused to
policy/domains/program for services and applications that you run on
your system.  Anything left in unused will not be included in the
built policy.

- Edit policy/file_contexts/types.fc and
policy/file_contexts/program/ssh.fc for your users (e.g. replace the
/home/jadmin entries with entries for your administrator accounts).
Also, you may need to customize the policy/file_contexts/program/*.fc
files for your particular filesystem layout.  This file contexts
configuration will be used in step 7 when you assign extended
attributes to the filesystem.

To build and install the policy:
	rpmbuild -tb policy-*.tgz
	rpm -Uvh /usr/src/redhat/RPMS/noarch/policy-*.rpm

	-or-
	
	cd selinux-usr/policy
	make install install-src		

3) Build and install the SELinux-patched daemons and utilities.
Note that the SELinux-patched utilities are now installed directly to
their standard locations rather than under /usr/local/selinux.  If you 
have a /usr/local/selinux directory from the old 2.4 SELinux, make sure 
that you do not include /usr/local/selinux/{bin,sbin} in your path when 
using the new SELinux, since the APIs are different.

You may need to upgrade your version of automake to build the
coreutils SRPM.  To do this, you can execute the following:
	cd selinux-usr/SRPMS
	rpmbuild --rebuild automake*.src.rpm
	rpm -Uvh /usr/src/redhat/RPMS/noarch/automake*.rpm

You can use the following command to build the binary RPMS for
the SELinux-patched daemon and utility packages:
	cd selinux-usr/SRPMS
	rpmbuild --define "WITH_SELINUX 1" --rebuild *.sel.src.rpm
Then install the binary RPMs as usual, e.g.
	rpm -Uvh --force /usr/src/redhat/RPMS/*/*.rpm

Of the patched packages, the most important ones are:
	util-linux (patched login program)
	openssh (patched ssh daemon)
	vixie-cron (patched cron daemon)	

The patched coreutils and procps packages are also helpful in allowing
you to conveniently get and set file and process security contexts.

Dan Walsh of Red Hat is maintaining a set of source and binary RPMs
available from ftp://people.redhat.com/dwalsh/SELinux/{srpms,rpms}

You will likely want a version of glibc that handles the AT_SECURE
auxv entry provided by the kernel so that domain transitions will
enable glibc secure mode.  Check your glibc to see if such support has
been added.  The change has been upstreamed and is available in
the Red Hat beta (severn / fedora core).

4) Create an initrd with load_policy, the binary policy file, and a
/linuxrc that will perform the initial policy load prior to mounting
the root filesystem.  For example, you might modify your mkinitrd
script in a similar manner to this patch for the RH9 mkinitrd script:

--- /sbin/mkinitrd-	2003-02-18 12:41:17.000000000 -0500
+++ /sbin/mkinitrd	2003-08-05 08:45:46.000000000 -0400
@@ -517,6 +517,12 @@
 inst /sbin/insmod.static "$MNTIMAGE/bin/insmod"
 ln -s /sbin/nash $MNTIMAGE/sbin/modprobe
 
+# Binary policy file and load_policy utility for loading it.
+mkdir -p $MNTIMAGE/selinux
+mkdir -p $MNTIMAGE/etc/security/selinux
+inst /etc/security/selinux/policy.15 "$MNTIMAGE/etc/security/selinux/policy.15"
+inst /usr/sbin/load_policy "$MNTIMAGE/bin/load_policy"
+
 for MODULE in $MODULES; do
     cp $verbose -a /lib/modules/$kernel/$MODULE $MNTIMAGE/lib
 done
@@ -570,6 +576,11 @@
     fi
 done
 
+echo "echo Loading policy" >> $RCFILE
+echo "mount -t selinuxfs none /selinux" >> $RCFILE
+echo "/bin/load_policy /etc/security/selinux/policy.15" >> $RCFILE
+echo "umount /selinux" >> $RCFILE
+
 echo "echo Mounting /proc filesystem" >> $RCFILE
 echo "mount -t proc /proc /proc" >> $RCFILE
 

5) 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

6) Boot the SELinux kernel.  Login as root with the sysadm_r role and
sysadm_t domain.

7) Assign extended attributes to your filesystems.
Caveat: We have encountered problems booting unmodified 2.4 kernels
after assigning extended attributes to the root filesystem.  We are
able to boot 2.4 kernels patched with the EA patch.
	cd /etc/security/selinux/src/policy
	make relabel

8) Reboot the SELinux kernel.  Login as root with the sysadm_r role
and sysadm_t domain.

9) If you have built and installed the patched utilities, then you
can run 'id -c' to see your security context and you can run 'ps -eZ'
to see the contexts of other processes.  If not, you can
run the getcon and getpidcon utilities to see your context or the
context of a particular process.  As mentioned above, a security
context has the syntax user:role:domain or user:role:type.

System processes should have the system_u user identity and the
system_r role.  Each system process with a different executable should
have its own separate domain.  If some system processes are running in
the initrc_t domain, then there are several possible reasons:
- The .te file for the program wasn't moved up from the
policy/domains/program/unused directory before building the policy.
- The pathname for the program in its .fc file (in the
 policy/file_contexts/program directory) doesn't match your system.
- A domain has not yet been defined for the program in the example policy.

You should either disable any system processes left in the initrc_t
domain (if you do not need them) or place them into a different
domain, possibly defining new domains if necessary.

Your user processes should have your user identity and the sysadm_r
role.  Your shell and most of its children will have the sysadm_t
domain.  Some of the processes that you run may be in different
domains because they require different privileges.

10) If you have built and installed the patched utilities, then you
can run 'ls -Z /'.  If not, you can run the getfilecon utility
to see a particular file context.  Initially, the system_u user
identity is used for all files at installation time.  When you create
new files after installation, they will be assigned the user identity
of the creating process.  The object_r role is used for all files,
because roles are not relevant for files.  Files with different
protection requirements will have different types, e.g. /boot has the
boot_t type and /etc has the etc_t type.  Some files in the 'ls'
output may show a (null) context which indicates that either
permission was not granted to obtain the context of the file or the
filesystem type does not provide an xattr handler.

11) If the NSA SELinux Development Support option was enabled in the
kernel configuration, then SELinux is built with development support.
With this option, SELinux starts in permissive mode by default,
logging permission failures but not enforcing them.  You can use
permissive mode in order to determine what additional permissions are
needed for your particular system and can then revise your policy
configuration accordingly.  You can subseqently run 'echo 1 >
/selinux/enforce' program to switch into enforcing mode.  Once in
enforcing mode, you can only switch back to permissive mode with 'echo
0 > /selinux/enforce' if authorized by the policy (in the example
policy, only the sysadm_r role can do this).  

Once you are satisfied that your policy configuration is sufficient
for your system, you should either specify "enforcing=1" on the kernel
command line to start in enforcing mode at boot time, or you should
rebuild the kernel without this option so that it is always in
enforcing mode.  The first option leaves open the possibility of
switching back to permissive mode by an administrator, while the
latter option provides stricter security.  If you choose the latter
option, be sure to keep a kernel that is built with the Development
Support option available for emergency recovery (e.g. if you make an
error in your policy configuration that renders your system
unuseable).

You may find the contributed policy/newrules.pl script useful in
generating additional 'allow' rules from the log messages for your
policy, but the generated rules should be carefully reviewed to ensure
that they are consistent with your security goals.  You may find it
desirable to define new domains and/or types rather than simply
granting the permission for an existing domain and/or type in order to
preserve existing security guarantees.  You may also find that certain
permission denials require other kinds of policy changes, e.g. changes
to the RBAC or constraints configurations.  You may also find that
certain permission denials are not fatal to the application and you
may not want to grant these permissions due to your security goals.
In that case, you may wish to simply suppress logging of the denial
via an 'dontaudit' rule.

12) If you subsequently reboot with a non-SELinux kernel (or with
"selinux=0"), be sure to run setfiles again before booting SELinux to
reset your file security contexts properly.

13) (optional) Install the Tresys policy analysis and management tools.
	cd setools
	make install

14) (optional) Install the MITRE slat tool.
	Read slat/README.


EXPERIMENTING WITH THE NEW API
------------------------------
1) Getting and setting process contexts

You can run the getcon utility to display the current security
context.  You can run the getpidcon utility to display the security
context of a particular process.

The patched coreutils package provides an enhanced form of the id
utility that displays the current security context.  The patched
procps and psmisc packages provide enhanced forms of the standard
process utilities that support options for displaying contexts of
other processes.

The execcon utility 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

The patched coreutils package adds a runcon utility that is a superset
of execcon; runcon also allows individual specification of particular
fields of the context, e.g. runcon -t sysadm_t bash.

The newrole and run_init utilities use the same mechanism to support
secure role transitions and execution of init scripts in the proper
context, e.g.:
	newrole -r sysadm_r
	run_init /etc/init.d/sshd restart

2) Getting and setting file contexts

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, 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 provides an example of how to create a directory
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

The patched coreutils package provides enhanced forms of the standard
file utilities that support options for preserving the security
context of files or for creating new files with a specified security
context.  It also adds a chcon utility that is a more general form of
setfilecon modeled after chmod/chown.

3) Getting and setting policy information

selinuxfs exports the security policy API via a set of nodes under
/selinux.  libselinux provides API calls that internally read and
write these nodes.  The /selinux nodes are:

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. 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.
libselinux provides a security_load_policy API call to access this
node.  The load_policy utility opens and mmaps a binary policy file
and then invokes this API call.

c) 'context' can be written to check the validity of a security
context.  libselinux provides a security_check_context API call to
access this node.  The setfiles utility invokes this API call to check
contexts in the file contexts specification, and the newrole utility
invokes this API call to check the new context.  Several other
libselinux functions also invoke this API call to validate contexts
before returning them.

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.  libselinux
provides a security_compute_av API call to access this node.  The
patched crond invokes this API call to check entrypoint permission.

e) 'create' can be written to request a labeling (transition) 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.  libselinux provides a security_compute_create API call to
access this node.

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.
libselinux provides a security_compute_relabel API call to access this
node.  The newrole utility and the patched login and sshd invoke this
API call to obtain the new tty/pty context.

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.
libselinux provides a security_compute_user API call to access this node.
The patched login, sshd, and crond invoke this API call to obtain the
set of authorized user contexts.

End
