diff options
| author |   klondike <klondike@xiscosoft.es> | 2010-11-12 18:32:11 +0100 |
|---|---|---|
| committer | klondike <klondike@xiscosoft.es> | 2010-11-12 18:32:11 +0100 |
| commit | 831364c55ba5ea0293176e330d6759c62004750f (patch) | |
| tree | 977d91d1427c9e5f3b77749b62f1c4d6fbbe31e9 | |
| parent | Adapting to new structure and fixing gentoo.org addresses (diff) | |
| download | hardened-docs-831364c55ba5ea0293176e330d6759c62004750f.tar.gz hardened-docs-831364c55ba5ea0293176e330d6759c62004750f.tar.bz2 hardened-docs-831364c55ba5ea0293176e330d6759c62004750f.zip | |
merging with CVS tree
52 files changed, 12105 insertions, 0 deletions
diff --git a/xml/capabilities.xml b/xml/capabilities.xml new file mode 100644 index 0000000..c6501e2 --- /dev/null +++ b/xml/capabilities.xml @@ -0,0 +1,518 @@ +<?xml version='1.0' encoding="utf-8"?> + + +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="/proj/en/hardened/capabilities.xml"> +<title>POSIX Capabilities</title> +<author title="Author"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Contributor"> + <mail link="tocharian@gentoo.org">Adam Mondl</mail> +</author> + +<abstract> +POSIX capabilities are a partitioning of the all powerful root privilege into a +set of distinct privileges +</abstract> + +<version>1.2</version> +<date>2005-01-22</date> + +<chapter> +<title>CAP_CHOWN</title> +<section> +<body> + +<pre caption="CAP_CHOWN"> + <i>CAP_CHOWN</i> + In a system with the [_POSIX_CHOWN_RESTRICTED] option defined, + this overrides the restriction of changing file ownership and + group ownership. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_DAC_OVERRIDE</title> +<section> +<body> + +<pre caption="CAP_DAC_OVERRIDE"> + <i>CAP_DAC_OVERRIDE</i> + Override all DAC access, including ACL execute access + if [_POSIX_ACL] is defined. + Excluding DAC access covered by CAP_LINUX_IMMUTABLE. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_DAC_READ_SEARCH</title> +<section> +<body> + +<pre caption="CAP_DAC_READ_SEARCH"> + <i>CAP_DAC_READ_SEARCH</i> + Overrides all DAC restrictions, regarding read and search on files + and directories, including ACL restrictions, if [_POSIX_ACL] is + defined. Excluding DAC access covered by CAP_LINUX_IMMUTABLE. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_FOWNER</title> +<section> +<body> + +<pre caption="CAP_FOWNER"> + <i>CAP_FOWNER</i> + Overrides all restrictions about allowed operations on files, where + file owner ID must be equal to the user ID, except where CAP_FSETID + is applicable. It doesn't override MAC and DAC restrictions. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_FSETID</title> +<section> +<body> + +<pre caption="CAP_FSETID"> + <i>CAP_FSETID</i> + Overrides the following restrictions, that the effective user ID shall + match the file owner ID, when setting the S_ISUID and S_ISGID bits on + that file; that the effective group ID (or one of the supplementary + group IDs) shall match the file owner ID when setting the S_ISGID bit + on that file; that the S_ISUID and S_ISGID bits are cleared on + successful return from chown(2) (not implemented). +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_FS_MASK</title> +<section> +<body> + +<pre caption="CAP_FS_MASK"> + <i>CAP_FS_MASK</i> + Used to decide between falling back on the old suser() or fsuser(). +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_KILL</title> +<section> +<body> + +<pre caption="CAP_KILL"> + <i>CAP_KILL</i> + Overrides the restriction, that the real or effective user ID of a process, + sending a signal, must match the real or effective user ID of the process, + receiving the signal. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SETGID</title> +<section> +<body> + +<pre caption="CAP_SETGID"> + <i>CAP_SETGID</i> + Allows setgid(2) manipulation; + Allows setgroups(2); + Allows forged gids on socket credentials passing. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SETUID</title> +<section> +<body> + +<pre caption="CAP_SETUID"> + <i>CAP_SETUID</i> + Allows set*uid(2) manipulation (including fsuid); + Allows forged pids on socket credentials passing. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SETPCAP</title> +<section> +<body> + +<pre caption="CAP_SETPCAP"> + <i>CAP_SETPCAP</i> + Transfer any capability in your permitted set to any pid, remove any capability in your permitted set from any pid. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_LINUX_IMMUTABLE</title> +<section> +<body> + +<pre caption="CAP_LINUX_IMMUTABLE"> + <i>CAP_LINUX_IMMUTABLE</i> + Allow modification of S_IMMUTABLE and S_APPEND file attributes. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_NET_BIND_SERVICE</title> +<section> +<body> + +<pre caption="CAP_NET_BIND_SERVICE"> + <i>CAP_NET_BIND_SERVICE</i> + Allows binding to TCP/UDP sockets below 1024; + Allows binding to ATM VCIs below 32. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_NET_BROADCAST</title> +<section> +<body> + +<pre caption="CAP_NET_BROADCAST"> + <i>CAP_NET_BROADCAST</i> + Allow broadcasting, listen to multicast. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_NET_ADMIN</title> +<section> +<body> + +<pre caption="CAP_NET_ADMIN"> + <i>CAP_NET_ADMIN</i> + Allow interface configuration; + Allow administration of IP firewall, masquerading and accounting; + Allow setting debug option on sockets; + Allow modification of routing tables; + Allow setting arbitrary process / process group ownership on sockets; + Allow binding to any address for transparent proxying; + Allow setting TOS (type of service); + Allow setting promiscuous mode; + Allow clearing driver statistics; + Allow multicasting; + Allow read/write of devicespecific registers; + Allow activation of ATM control sockets. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_NET_RAW</title> +<section> +<body> + +<pre caption="CAP_NET_RAW"> + <i>CAP_NET_RAW</i> + Allow use of RAW sockets; + Allow use of PACKET sockets. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_IPC_LOCK</title> +<section> +<body> + +<pre caption="CAP_IPC_LOCK"> + <i>CAP_IPC_LOCK</i> + Allow locking of shared memory segments; + Allow mlock and mlockall (which doesn't really have anything to do with IPC). +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_IPC_OWNER</title> +<section> +<body> + +<pre caption="CAP_IPC_OWNER"> + <i>CAP_IPC_OWNER</i> + Override IPC ownership checks. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_MODULE</title> +<section> +<body> + +<pre caption="CAP_SYS_MODULE"> + <i>CAP_SYS_MODULE</i> + Insert and remove kernel modules modify kernel without limit; + Modify cap_bset. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_RAWIO</title> +<section> +<body> + +<pre caption="CAP_SYS_RAWIO"> + <i>CAP_SYS_RAWIO</i> + Allow ioperm/iopl access; + Allow sending USB messages to any device via /proc/bus/usb. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_CHROOT</title> +<section> +<body> + +<pre caption="CAP_SYS_CHROOT"> + <i>CAP_SYS_CHROOT</i> + Allow use of chroot(). +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_PTRACE</title> +<section> +<body> + +<pre caption="CAP_SYS_PTRACE"> + <i>CAP_SYS_PTRACE</i> + Allow ptrace() of any process. +</pre> + +</body> +</section> +</chapter> + + +<chapter> +<title>CAP_SYS_PACCT</title> +<section> +<body> + +<pre caption="CAP_SYS_PACCT"> + <i>CAP_SYS_PACCT</i> + Allow configuration of process accounting. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_ADMIN</title> +<section> +<body> + +<pre caption="CAP_SYS_ADMIN"> + <i>CAP_SYS_ADMIN</i> + Allow configuration of the secure attention key; + Allow administration of the random device; + Allow examination and configuration of disk quotas; + Allow configuring the kernel's syslog (printk behaviour); + Allow setting the domainname; + Allow setting the hostname; + Allow calling bdflush(); + Allow mount() and umount(), setting up new smb connection; + Allow some autofs root ioctls; + Allow nfsservctl; Allow VM86_REQUEST_IRQ; + Allow to read/write pci config on alpha; Allow irix_prctl on mips (setstacksize); + Allow flushing all cache on m68k (sys_cacheflush); + Allow removing semaphores; Used instead of CAP_CHOWN to "chown" IPC message queues, semaphores and shared memory; + Allow locking/unlocking of shared memory segment; + Allow turning swap on/off; + Allow forged pids on socket credentials passing; + Allow setting readahead and flushing buffers on block devices; + Allow setting geometry in floppy driver; + Allow turning DMA on/off in xd driver; + Allow administration of md devices (mostly the above, but some extra ioctls); + Allow tuning the ide driver; + Allow access to the nvram device; + Allow administration of apm_bios, serial and bttv (TV) device; + Allow manufacturer commands in isdn CAPI support driver; + Allow reading nonstandardized portions of pci configuration space; + Allow DDI debug ioctl on sbpcd driver; + Allow setting up serial ports; + Allow sending raw qic117 commands; + Allow enabling/disabling tagged queuing on SCSI controllers and sending arbitrary SCSI commands; + Allow setting encryption key on loopback filesystem. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_BOOT</title> +<section> +<body> + +<pre caption="CAP_SYS_BOOT"> + <i>CAP_SYS_BOOT</i> + Allow use of reboot(). +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_NICE</title> +<section> +<body> + +<pre caption="CAP_SYS_NICE"> + <i>CAP_SYS_NICE</i> + Allow raising priority and setting priority on other (different UID) processes; + Allow use of FIFO and roundrobin (realtime) scheduling on own processes and setting + the scheduling algorithm used by another process. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_RESOURCE</title> +<section> +<body> + +<pre caption="CAP_SYS_RESOURCE"> + <i>CAP_SYS_RESOURCE</i> + Override resource limits. Set resource limits; + Override quota limits; + Override reserved space on ext2 filesystem; + Modify data journaling mode on ext3 filesystem + (uses journaling resources); NOTE: ext2 honors fsuid when checking for + resource overrides, so you can override using fsuid too; + Override size restrictions on IPC message queues; + Allow more than 64hz interrupts from the realtime clock; + Override max number of consoles on console allocation; + Override max number of keymaps. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_TIME</title> +<section> +<body> + +<pre caption="CAP_SYS_TIME"> + <i>CAP_SYS_TIME</i> + Allow manipulation of system clock; + Allow irix_stime on mips; + Allow setting the realtime clock. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_SYS_TTY_CONFIG</title> +<section> +<body> + +<pre caption="CAP_SYS_TTY_CONFIG"> + <i>CAP_SYS_TTY_CONFIG</i> + Allow configuration of tty devices; Allow vhangup() of tty. +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_MKNOD</title> +<section> +<body> + +<pre caption="CAP_MKNOD"> + <i>CAP_MKNOD</i> + Allow the privileged aspects of mknod(). +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>CAP_LEASE</title> +<section> +<body> + +<pre caption="CAP_LEASE"> + <i>CAP_LEASE</i> + Allow taking of leases on files. +</pre> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/docs/CVS/Entries b/xml/docs/CVS/Entries new file mode 100644 index 0000000..dd0e57a --- /dev/null +++ b/xml/docs/CVS/Entries @@ -0,0 +1,5 @@ +/devel-chroots-intro.xml/1.1/Tue Dec 19 08:42:53 2006// +/glossary.xml/1.2/Wed Sep 15 12:04:35 2004// +/index.xml/1.3/Fri Mar 16 10:40:45 2007// +/pax-howto.xml/1.2/Fri Sep 24 10:49:00 2004// +D diff --git a/xml/docs/CVS/Repository b/xml/docs/CVS/Repository new file mode 100644 index 0000000..1f0d30e --- /dev/null +++ b/xml/docs/CVS/Repository @@ -0,0 +1 @@ +gentoo/xml/htdocs/proj/en/hardened/docs diff --git a/xml/docs/CVS/Root b/xml/docs/CVS/Root new file mode 100644 index 0000000..da304d3 --- /dev/null +++ b/xml/docs/CVS/Root @@ -0,0 +1 @@ +:pserver:anonymous@anoncvs.gentoo.org/var/cvsroot diff --git a/xml/docs/devel-chroots-intro.xml b/xml/docs/devel-chroots-intro.xml new file mode 100644 index 0000000..8a97405 --- /dev/null +++ b/xml/docs/devel-chroots-intro.xml @@ -0,0 +1,488 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<!-- $Header $ --> + +<guide link="http://www.gentoo.org/proj/en/hardened/devel-chroots-intro.xml" lang="en"> + +<title>Developer Chroots Utility Guide</title> + +<author title="Author"> + <mail link="pappy@gentoo.org">Alexander Gabert</mail> +</author> + +<abstract> +This guide covers the installation, configuration and set up +of chroots using a tool developed for the Gentoo dev machines. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> +<license/> + +<version>1.0</version> +<date>2006-12-06</date> + +<chapter> +<title>Introduction</title> +<section> +<title>What is this all about?</title> +<body> + +<p> +The normal procedure for a developer setting up a chroot is +to fetch a stage, find a directory where to unpack it, unroll the stage, +make some modifications to basic files like <c>/etc/resolv.conf</c>, +<c>/etc/hosts</c> and others. +Then she or he is usually incorporating some kind of custom script +to start the chroot again once the machine gets rebooted +or she/he needs to reenter it for another reason. +More advanced scripts use screen sessions for making the chroot +command launching the chroot independent of the +currently connected user. +</p> + +<p> +However, lots of these scripts exist and people are using more +and more chroots on our development servers, +which is a very good thing in fact because it's relieving stress +off the main system and is making our production systems +more stable if development is done inside contained chroots. +</p> + +<p> +There has been a previous version of <c>devel-chroots</c>, +but the old version only had limited multiuser capabilities and +was rather bulky compared to the code in the script and the +configuration abilities of the different chroots. +</p> + +<p> +For this reason, the new version of <c>devel-chroots</c> has been +completely rewritten and is using a three-layered approach +of configuration data for setting up chroots and populating +the config files in these. +</p> + +<p> +Finishing this introduction, this guide is not meant to be exclusive +to Gentoo development machines and their maintainers and users, +the tool has been developed to be usable on any machine +where chroots should be set up in an automatic and configurable fashion. +</p> + +<p> +Your input is welcome and there is always room for improving +this little program as it aims at easing development and promotes +thorough regression and live testing by providing an easy way +of setting up a testbed, which a chroot basically is. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Installation</title> +<section> +<title>Ebuild installation</title> +<body> + +<p> +The utility can be emerged with the following shell command: +</p> + +<note> +If you want to emerge only the basic tool without the sample configuration, +activate the <c>"minimal"</c> USE-flag. +</note> + +<pre caption="Installation of devel-chroots"> +# <i>USE="-minimal" emerge -pv devel-chroots</i> + +These are the packages that would be merged, in order: + +Calculating dependencies... done! +[ebuild R ] dev-util/devel-chroots-2.0.0 USE="-minimal*" 0 kB + +Total size of downloads: 0 kB + +# <i>USE="-minimal" emerge -v devel-chroots</i> +</pre> + +<pre caption="Installation of devel-chroots without configuration files"> +# <i>USE="minimal" emerge -pv devel-chroots</i> + +These are the packages that would be merged, in order: + +Calculating dependencies... done! +[ebuild R ] dev-util/devel-chroots-2.0.0 USE="minimal" 0 kB + +Total size of downloads: 0 kB + +# <i>USE="minimal" emerge -v devel-chroots</i> +</pre> + +</body> +</section> + +<section> +<title>Fetching the source code</title> +<body> + +<p> +The source code for the project can be found in the following +anonymous <c>cvs</c> or <c>svn</c> location, along with viewcvs: +</p> + +<pre caption="fetching the project source code with anonymous cvs"> +/tmp/dc $ <i>cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo-projects</i> +</pre> + +<pre caption="fetching the project source code with anonymous svn"> +/tmp/dc $ <i>svn co http://anonsvn.gentoo.org/repositories/gentoo-projects</i> +</pre> + +<p> +Then dive into the +<c>gentoo-projects/devel-chroots/devel-chroots-2.0.0/</c> +directory to see the source code for the project. +</p> + +<p> +As you can see, it's just the same as the scripts +that are getting installed by the ebuild. +Which positively means that you can theoretically also use +these scripts without having an ebuild install them. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Configuration</title> +<section> +<title>General machine configuration</title> +<body> + +<p> +There is no standard location where a <c>stage3</c> +file may be located on the mirrors. +For this reason, it is highly advised to edit the +default configuration file and explicitly set the <c>STAGE_URL</c> variable. +</p> + +<pre caption="STAGE_URL in default configuration"> +$ <i>grep STAGE_URL /etc/devel-chroots/default/config</i> +STAGE_URL="$(echo ${GENTOO_MIRRORS} | awk '{ print $1; }')/${STAGE_PATH}/${STAGE_NAME}" +# STAGE_URL="http://ftp.belnet.be/mirror/rsync.gentoo.org/gentoo/releases/x86/2006.0/stages/stage3-x86-2006.0.tar.bz2" +</pre> + +<p> +As you can see, the default mechanism is to pick the first mirror, +add the stage path for a typical x86 stage and construct +the name for a current profile's stage. +However, this doesn't work for sparc for example, +because they are differentiating between sparc32 and sparc64. +The same holds true for hppa, where it's stages pertaining +to the 1.1 ABI and the 2.0 ABI of different types of machines. +</p> + +<p> +Also remember that users and specific chroots can always +override this variable, so it would be the best thing +to make sure it points to a reasonable default stable stage. +</p> + +<p> +As said, users wishing to enable a hardened toolchain chroot, +a linux32 chroot on an amd64 machine or a new bleeding edge stage +from one of their private mirrors can always override +this setting in their own <c>config</c>. +</p> + +<p> +Another important piece of the configuration is the global <c>make.conf</c>. +Basically, every single chroot contains a file +<c>/usr/local/chroot/conf.d/make.conf</c> +which is constructed from three possible <c>make.conf</c> files +residing in the configuration directory of <c>devel-chroots</c>: +</p> + +<p> +<c>/etc/devel-chroots/default/make.conf</c> is the main file for chroots. +</p> + +<p> +<c>/etc/devel-chroots/pappy/make.conf</c> is holding user specific addons. +</p> + +<p> +<c>/etc/devel-chroots/pappy/chroot001/make.conf</c> is a chroot specific file. +</p> + +<p> +These three files make up the final +<c>/usr/local/chroot/conf.d/make.conf</c> +which then can be sourced by the real <c>/etc/make.conf</c> of the chroot. +</p> + +</body> +</section> + +<section> +<title>User specific configuration</title> +<body> + +<p> +As noted in the previous section, each user can define her or his +own versions of <c>config</c> and <c>make.conf</c> in the +configuration directory <c>/etc/devel-chroots/username</c>. +This enables the highest possible versatility and flexibility. +For example, it is possible to allow a user define her or his own +debugging settings for +<c>FEATURES</c> and <c>USE</c> flags in <c>make.conf</c>. +</p> + +<p> +Another example is the custom setting of the screenrc: +</p> + +<pre caption="user specific screenrc for chroot screen sessions"> +$ <i>cat /etc/devel-chroots/pappy/screenrc</i> +backtick 1 5 0 /home/pappy/bin/mem.sh +backtick 2 1 0 /home/pappy/bin/cetclock.sh 'CET' '-0200' '-0100' + +hardstatus string '%{= kG}[%= %{= kw}%?%-Lw%?%{r}[%{W}%n*%f %t%?{%u}%?%{r}]%{w}%?%+Lw%?%?%= %{g}]%{W} %2`:%s %{g}%{.w}%H%{.c} [%l] %1`MB ram' +</pre> + +<p> +This makes it easy for users to include their own scripts +in screen sessions of chroots, +for example to measure disk usage or load of the system. +</p> + +<pre caption="Example: user specific CET date display on chroot screen"> +~ $ cat bin/cetclock.sh +#!/bin/bash + +# check for daylight saving time being currently active at this time +if [ "x$(perl -e '@timeData = localtime(time); print ${timeData}[-1];')y" == "x1y" ] +then + date --utc --date="$(date --utc '+%F %T') $2" "+$1 %H:%M" +else + date --utc --date="$(date --utc '+%F %T') $3" "+$1 %H:%M" +fi + +</pre> + +</body> +</section> + +<section> +<title>Chroot specific configuration</title> +<body> + +<p> +Last but not least, on some arches (notably amd64), +there is the possibility to install an x86 chroot using a special emulator +command, called <c>linux32</c>. + +Redefining the respective variables in the chroot-specific +<c>/etc/devel-chroots/pappy/chroot001/config</c> enables users to +set up those special chroots on amd64 test machines: +</p> + +<pre caption="chroot specific config for linux32 chroot on amd64"> +$ <i>cat /etc/devel-chroots/pappy/chroot001/config</i> +CHROOT_BINARY="linux32 /usr/bin/chroot" +STAGE_URL="http://ftp.belnet.be/mirror/rsync.gentoo.org/gentoo/releases/x86/2006.0/stages/stage3-x86-2006.0.tar.bz2" +</pre> + +<p> +These variables are learned by the script and will +be used for setting up the chroot. +Other chroots are not affected by this setting, however. +This makes it very easy for users to set up and maintain +different chroots for their needs on the same machine at a time. +</p> + +<p> +As you can see, in every case, +chroot-specific data is overwriting default and user-specific data. +Please do not change system-internal variables like +the maximum number of chroots for a user +and similar definitions inside a chroot-specific <c>config</c> file. +</p> + +</body> +</section> + +</chapter> + +<chapter> +<title>Startup and maintenance</title> +<section> +<title>Automatic startup</title> +<body> + +<p> +Automatic startup of the developer chroots is attained with an init script +that is conforming to the Gentoo standards. +</p> + +<pre caption="starting the devel-chroots init script"> +# /etc/init.d/devel-chroots status + * status: stopped + +# /etc/init.d/devel-chroots start + * Starting developer chroots for all users ... + * pappy: starting chroot001 in (/space/devel-chroots/pappy/chroot001) + * pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot001 + * pappy: chroot001: creating conf: make.conf + * pappy: starting chroot002 in (/space/devel-chroots/pappy/chroot002) + * pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot002 + * pappy: chroot002: creating conf: make.conf + * config file [/etc/devel-chroots/pappy/chroot002/make.conf] not existing, skipping + * no /etc/devel-chroots/pappy/chroot003 config dir + * no /etc/devel-chroots/pappy/chroot004 config dir + * no /etc/devel-chroots/pappy/chroot005 config dir + * no /etc/devel-chroots/pappy/chroot006 config dir + * no /etc/devel-chroots/pappy/chroot007 config dir + * no /etc/devel-chroots/pappy/chroot008 config dir + * launching detached screen session for pappy's chroots + * remember that you have to source /usr/local/chroot/conf.d/make.conf + * in the make.conf of created chroots for user-specific settings + * for multiuser mode, you need to set /usr/bin/screen to mode 4755 + * and also change the directory /var/run/screen to mode 0755 [ <ident>ok</ident> ] +</pre> + +<pre caption="restarting the chroots init script"> +# /etc/init.d/devel-chroots restart + * Stopping developer chroots for all users ... + * stopping chroot001 of user pappy (/space/devel-chroots/pappy/chroot001) + * pappy: terminating the following screen sessions: 8638 + * pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot001 + * stopping chroot002 of user pappy (/space/devel-chroots/pappy/chroot002) + * pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot002 + * no /etc/devel-chroots/pappy/chroot003 config dir + * no /etc/devel-chroots/pappy/chroot004 config dir + * no /etc/devel-chroots/pappy/chroot005 config dir + * no /etc/devel-chroots/pappy/chroot006 config dir + * no /etc/devel-chroots/pappy/chroot007 config dir + * no /etc/devel-chroots/pappy/chroot008 config dir [ <ident>ok</ident> ] + * Starting developer chroots for all users ... + * pappy: starting chroot001 in (/space/devel-chroots/pappy/chroot001) + * pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot001 + * pappy: chroot001: creating conf: make.conf + * pappy: starting chroot002 in (/space/devel-chroots/pappy/chroot002) + * pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot002 + * pappy: chroot002: creating conf: make.conf + * config file [/etc/devel-chroots/pappy/chroot002/make.conf] not existing, skipping + * no /etc/devel-chroots/pappy/chroot003 config dir + * no /etc/devel-chroots/pappy/chroot004 config dir + * no /etc/devel-chroots/pappy/chroot005 config dir + * no /etc/devel-chroots/pappy/chroot006 config dir + * no /etc/devel-chroots/pappy/chroot007 config dir + * no /etc/devel-chroots/pappy/chroot008 config dir + * launching detached screen session for pappy's chroots + * remember that you have to source /usr/local/chroot/conf.d/make.conf + * in the make.conf of created chroots for user-specific settings + * for multiuser mode, you need to set /usr/bin/screen to mode 4755 + * and also change the directory /var/run/screen to mode 0755 [ <ident>ok</ident> ] +</pre> + +<p> +As you can see, the init script is maybe generating +lots of considered unnecessary output, +however this is important for being able +to judge why a certain chroot has not been set up +and adds in easy understanding what is happening and what is not. +</p> + +<p> +For example, as you can see, a chroot for a given user is only started +if a configuration directory for that chroot could be found. +It can be empty, but it has to exist for the given chroot to be started. +</p> + +<p> +Please note that the usage of the init script should be left +up to the discretion of the system administrator. +</p> + +</body> +</section> + +<section> +<title>User management of chroots</title> +<body> + +<p> +Users should be issuing the following script for +starting and stopping their own chroots: +</p> + +<pre caption="user maintenance of chroots: stopping chroots"> +$ sudo /usr/sbin/devel-chroots stop pappy + * stopping chroot001 of user pappy (/space/devel-chroots/pappy/chroot001) + * pappy: terminating the following screen sessions: 9371 + * pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot001 + * stopping chroot002 of user pappy (/space/devel-chroots/pappy/chroot002) + * pappy: unmounting chroot filesystems: /space/devel-chroots/pappy/chroot002 +</pre> + +<pre caption="user maintenance of chroots: starting chroots"> +$ sudo /usr/sbin/devel-chroots start pappy + * pappy: starting chroot001 in (/space/devel-chroots/pappy/chroot001) + * pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot001 + * pappy: chroot001: creating conf: make.conf + * pappy: starting chroot002 in (/space/devel-chroots/pappy/chroot002) + * pappy: mounting chroot filesystems: /space/devel-chroots/pappy/chroot002 + * pappy: chroot002: creating conf: make.conf + * launching detached screen session for pappy's chroots +</pre> + +<p> +Please remember there is no restart command: +</p> + +<pre caption="illegal use of restart command for chroot"> +$ sudo /usr/sbin/devel-chroots restart pappy + * error: unknown mode: restart +</pre> + +</body> +</section> + +<section> +<title>Final notes</title> +<body> + +<p> +As noted in the init script, for users being able to reattach +to root screen sessions as a user and +use the <c>acladd</c> command to see who is working with them, +it is necessary to change screen and +the working directory of the screen session sockets. +</p> + +<p> +However, this is a cosmetic advantage, +because normally everybody is supposed to be root +on a development system and there is no security restrictions. +</p> + +<p> +But on the other hand, having a system of voluntarily +least priviledges used for reconnecting to screen sessions +as an authorized user never hurts, avoids mistakes and problems +and opens up room for cutting down the necessary priviledges +of scripts and users for having their work done! +</p> + +</body> +</section> +</chapter> +</guide> + diff --git a/xml/docs/glossary.xml b/xml/docs/glossary.xml new file mode 100644 index 0000000..2b21d0c --- /dev/null +++ b/xml/docs/glossary.xml @@ -0,0 +1,198 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="/proj/en/hardened/docs/glossary.xml"> + +<title>Introduction to Gentoo Hardened</title> +<author title="Author"> + <mail link="tseng@gentoo.org">Brandon Hale</mail> +</author> + +<abstract> +This document introduces the Gentoo Hardened project and covers +each of its subprojects in simple terms. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> +<license/> + +<version>1.1</version> +<date>August 07, 2004</date> + +<chapter> +<title>What is Gentoo Hardened?</title> +<section> +<body> + +<p> +Gentoo Hardened is a subproject that works to bring advanced +security features to Gentoo Linux. Hardened is not a single product +but rather a set of complimentary pieces of software intended to cover +many aspects of Linux security. The major components are ACL systems, +PIE/SSP and Intrusion Detection Systems. +</p> + +</body> +</section> +</chapter> + +<chapter id="acl"> +<title>ACL's (Access Control Lists)</title> +<section> +<body> + +<p> +ACL's give the systems administrator a more powerful tool to control access +to various system resources than was possible in traditional UNIX systems. +Such systems allow you to allow/disallow access to all aspects of a system to +users or groups of users, and to create powerful rulesets. +</p> + +<p> +ACL systems supported by Gentoo Hardened include Grsecurity, SELinux, RSBAC, and +Systrace. +</p> + +</body> +</section> +<section id="grsecurity"> +<title>Grsecurity</title> +<body> + +<p> +Grsecurity may be the most common ACL system, and is found in several of +Gentoo's patched kernel source trees. An advantage of Grsecurity is that +it includes more than just an ACL system. It also provides PaX, a kernel +patch that forces memory to be nonexecutable, thwarting common attacks. +It also adds some other hardening features, including more randomness in +memory allocation and TCP packets, and stricter enforcement of chroot. +</p> + +</body> +</section> +<section id="selinux"> +<title>SELinux</title> +<body> + +<p> +SELinux was written by the NSA and can enforce policies on all processes and +objects on a system. Many people, including the Hardened project, are so +confident in its ability to lock down a system that they have setup public +machines and challenge anyone to take down the box (given a root password!) +</p> + +</body> +</section> +<section id="rsbac"> +<title>RSBAC</title> +<body> + +<p> +RSBAC is an independent project driven by Amon Ott. It supports many different +security models which are implemented as modules. It can work together with PaX +and while the implementation and models are a bit different, it is often +compared to SELinux features wise. +</p> + +</body> +</section> +<section id="systrace"> +<title>Systrace</title> +<body> + +<p> +Systrace is a lightweight ACL system with an easy to use policy editor and a +gui for on-the-fly policy management. Additionally this allows applications +which require root capabilities to run without setuid and setgid flags. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>PIE/SSP</title> +<section> +<body> + +<p> +These two hardening features are added to binaries at compile time by GCC. +</p> + +</body> +</section> +<section id="et_dyn"> +<title>PIE/SSP</title> +<body> + +<p> +Another compile time feature to protect a programs space in memory from +exploitation. This feature tells the compiler to create a Position Independent +Executable, which can be used by a PaX (see below) enabled kernel to fully +randomize the executable's memory space. This protection method has no +noticable performance impact, and prevents exploits that are written to +target specific memory addresses. This can be enabled transparently via +hardened-gcc (See Below.) +</p> + +</body> +</section> +<section id="ssp"> +<title>SSP (Stack Smashing Protection)</title> +<body> + +<p> +Known commonly as ProPolice, this GCC patch is included by default in Gentoo, +but not enabled. This protects binaries from malicious code insertion into the +stack. Whenever a buffer (area in memory where a program accepts user input) is +created, ProPolice inserts a cryptographic "canary", and after each write to a +buffer verifies that the canary has not been overwritten. This nullifies a +common attack where a cracker inserts malicious code past the edge of a buffer +and the program blindly executes it. This feature is enabled via the compiler +flag "-fstack-protector" or transparently via hardened-gcc (See Below.) +</p> + +</body> +</section> +<section id="hardened-gcc"> +<title>Hardened GCC</title> +<body> + +<p> +When GCC is built with USE="hardened", modified spec files are installed that allow +for transparent PIE/SSP compiles. Since these options are enabled by the spec file +there is no reason to also add them to CFLAGS. In fact, in the case of PIE this can +even cause problems. +</p> + +</body> +</section> +</chapter> + +<chapter id="ids"> +<title>Instrusion Detection Systems</title> +<section> +<body> + +<p> +This class of programs monitor log files for suspicious activity and report +it to the administrator. +</p> + +</body> +</section> +<section id="prelude"> +<title>Prelude</title> +<body> + +<p> +Prelude is a hybrid intrusion detection system that tracks both network +intrusions and host intrusions with an lml (log monitoring lackey). +Integrating this on a large scale, adding support to certain apps, and adding +rules so that lml can monitor other projects like SELinux. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/docs/index.xml b/xml/docs/index.xml new file mode 100644 index 0000000..df5cdb5 --- /dev/null +++ b/xml/docs/index.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/docs/index.xml,v 1.3 2007/03/16 10:40:45 neysx Exp $ --> +<!DOCTYPE mainpage SYSTEM "/dtd/guide.dtd"> +<mainpage> + <title>Hardened Gentoo Documentation Resources</title> + <author title="Author"> + <mail link="tseng@gentoo.org">Brandon Hale</mail> + </author> +<version>1.0</version> +<date>August 7, 2004</date> + +<chapter> +<title>Hardened Gentoo Documentation Resources</title> + +<section> +<body> +<p> +The <b><uri link="glossary.xml">Hardened Gentoo Glossary</uri></b> breifly +explains the several technologies that make up Hardened Gentoo. +</p> +</body> +</section> + +<section> +<title>SELinux</title> +<body> + +<p> +SELinux is a system of mandatory access controls. SELinux can enforce the security +policy over all processes and objects in the system. The following documents will +help you to build a new SELinux-enabled system, or to convert an existing system, +and get up to speed with the basics of SELinux policies. +</p> + +<p> +The <b><uri link="../selinux/selinux-x86-install.xml">SELinux x86 Install Guide +</uri></b> provides a step-by-step explanation on how to install and configure +a new system using SELinux. +</p> + +<p> +The <b><uri link="../selinux/selinux-quickstart.xml">SELinux QuickStart Guide +</uri></b> includes instructions on converting your existing Gentoo install to +SELinux. +</p> + +<p> +The <b><uri link="../selinux/selinux-policy.xml">SELinux Policy Overview</uri></b> +covers the basics of working with SELinux policies. +</p> + +<p> +The <b><uri link="../selinux/selinux-faq.xml">SELinux FAQ</uri></b> answers many +frequently asked questions and has solutions for common pitfalls. +</p> + +</body> +</section> +<section> +<title>RSBAC</title> +<body> + +<p> +RSBAC is Mandatory Access Control security system based on the Role Compatibility +model. It can enforce access rules on your operating system. +</p> + +<p> +The <b><uri link="../rsbac/overview.xml">RSBAC Overview</uri></b> is a glossary +that establishes a basic understanding of RSBAC-related concepts. +</p> + +<p> +The <b><uri link="../rsbac/quickstart.xml">RSBAC Quickstart</uri></b> +covers converting an existing system to RSBAC. +</p> + +</body> +</section> + +<section> +<title>PaX</title> +<body> + +<p> +PaX is a combination of technologies that enable comprehensive memory protection +in Linux. The following docs cover both the PaX kernel and complementary userland +technologies. +</p> + +<p> +The <b><uri link="pax-howto.xml">PaX Howto</uri></b> helps to get a system +up and running with a PaX kernel and PIE/SSP userland. +</p> +</body> +</section> +</chapter> +</mainpage> diff --git a/xml/docs/pax-howto.xml b/xml/docs/pax-howto.xml new file mode 100644 index 0000000..413a04d --- /dev/null +++ b/xml/docs/pax-howto.xml @@ -0,0 +1,287 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/docs/pax-howto.xml,v 1.2 2004/09/24 10:49:00 tigger Exp $ --> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/docs/pax-howto.xml"> +<title>Hardened Gentoo PaX Quickstart</title> + +<author title="Author"> + <mail link="tseng@gentoo.org">Brandon Hale</mail> +</author> +<author title="Editor"> + <mail link="blackace@gentoo.org">Blackace</mail> +</author> + +<abstract> +A quickstart covering PaX and Hardened Gentoo. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> +<license/> + +<version>1.1</version> +<date>August 07, 2004</date> + +<chapter> +<title>What is Hardened Gentoo?</title> +<section> +<body> + +<p> +Hardened Gentoo is a project interested in the hardening of a Gentoo system. +Several different solutions are supported by us and there is a fair bit of +flexibility to create your own setup. At the heart of Hardened Gentoo is +<e>PaX</e>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>What is PaX?</title> +<section> +<body> + +<p> +PaX is a patch to the Linux kernel that provides hardening in two ways. +</p> + +<p> +The first, <e>ASLR</e> (Address Space Layout Randomization) provides a means to +randomize the addressing scheme of all data loaded into memory. When an +application is built as a <e>PIE</e> (Position Independent Executable), PaX is +able to also randomize the addresses of the application base in addition. +</p> + +<p> +The second protection provided by PaX is non-executable memory. This prevents a +common form of attack where executable code is inserted into memory by an +attacker. More information on PaX can be found throughout this guide, but the +homepage can be found at <uri>http://pax.grsecurity.net</uri>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>An Introduction to PIE and SSP</title> +<section> +<body> + +<p> +As mentioned above, PaX is complemented by PIE. This method of building +executables stores information needed to relocate parts of the executable in +memory, hence the name <e>Position Independent</e>. +</p> + +<p> +<e>SSP</e> (Stack Smashing Protector) is a second complementary technology we +introduce at executable build time. SSP was originally introduced by IBM under +the name <e>ProPolice</e>. It modifies the C compiler to insert initialization +code into functions that create a buffer in memory. +</p> + +<note> +In newer versions of SSP, it is possible to apply SSP to all functions, +adding protection to functions whose buffer would normally be below the size +limit for SSP. This is enabled via the CFLAG -fstack-protector-all. +</note> + +<p> +At run time, when a buffer is created, SSP adds a secret random value, the +canary, to the end of the buffer. When the function returns, SSP makes sure +that the canary is still intact. If an attacker were to perform a buffer +overflow, he would overwrite this value and trigger that stack smashing +handler. Currently this kills the target process. +</p> + +<p> +<uri link="http://www.trl.ibm.com/projects/security/ssp/">Further reading on +SSP.</uri> +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Building a PaX-enabled Kernel</title> +<section> +<body> + +<p> +Several Gentoo kernel trees are already patched with PaX. +</p> + +<p> +For 2.4 based machines, the recommended kernels are <c>hardened-sources</c> or +<c>grsec-sources</c>. For 2.6 machines, <c>hardened-dev-sources</c> are +recommended. +</p> + +<p> +Grab one of the recommended source trees, or apply the appropriate patch from +<uri>http://pax.grsecurity.net</uri> to your own tree and configure it as you +normally would for the target machine. +</p> + +<p> +In <c>Security Options -> PaX</c>, apply the options as shown below. +</p> + +<pre caption="Kernel configuration"> +[*] Enable various PaX features + +PaX Control -> + + [ ] Support soft mode + [*] Use legacy ELF header marking + [*] Use ELF program header marking + MAC system integration (none) ---> + +Non-executable page -> + + [*] Enforce non-executable pages + [*] Paging based non-executable pages + [*] Segmentation based non-executable pages + [*] Emulate trampolines + [*] Restrict mprotect() + [ ] Disallow ELF text relocations + +Address Space Layout Randomization -> + + [*] Address Space Layout Randomization + [*] Randomize kernel stack base + [*] Randomize user stack base + [*] Randomize mmap() base + [*] Randomize ET_EXEC base +</pre> + +<p> +Build this kernel as you normally would and install it to <path>/boot</path>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Building a PIE/SSP Enabled Userland</title> +<section> +<body> + +<p> +Hardened Gentoo has added support for transparent PIE/SSP building via GCC's +specfile. This means that any users upgrading an older Hardened install should +remove any LDFLAGS or CFLAGS used to trigger PIE/SSP. Also, the +<c>hardened-gcc</c> package is now deprecated and should be unmerged +(version 5.0 is a dummy package). To get the current GCC, add +<c>USE="hardened"</c> to <path>/etc/make.conf</path>. +</p> + +<p> +To maintain a consistant toolchain, first <c>emerge binutils gcc glibc</c>. +Next, rebuild the entire system with <c>emerge -e world</c>. All future packages +will be built with PIE/SSP. +</p> + +<warn> +Both PIE and SSP are known to cause issues with some packages. If you come +across a package that fails to compile, please file a bug report including a log +of the failed compile and the output of <c>emerge info</c> to +<uri>http://bugs.gentoo.org/</uri>. +</warn> + +</body> +</section> +</chapter> + +<chapter> +<title>When Things Misbehave (PaX Control)</title> +<section> +<body> + +<p> +Some legitimate applications will attempt to generate code at run time which is +executed out of memory. Naturally, PaX does not allow this and it will promptly +kill the offending application. +</p> + +<note> +The most notable of these applications are XFree, mplayer and multimedia tools +based on xine-lib. The easiest way around these problems are to disable PaX +protections. +</note> + +<p> +Luckily there is a utility to toggle protections on a per-executable basis, +<e>paxctl</e>. As with any other package in Gentoo, install paxctl with the +command <c>emerge paxctl</c>. Usage is show by <c>paxctl -h</c>. +</p> + +<note> +If you have an older version of binutils, you will need to use <e>chpax</e>, +which edits the old-style PaX markings. Usage of chpax is largely the same as +paxctl. This also requires legacy marking support built into your kernel. +</note> + +<pre caption="paxctl -h"> +usage: paxctl <options> <files> + +options: + -p: disable PAGEEXEC -P: enable PAGEEXEC + -e: disable EMUTRMAP -E: enable EMUTRMAP + -m: disable MPROTECT -M: enable MPROTECT + -r: disable RANDMMAP -R: enable RANDMMAP + -x: disable RANDEXEC -X: enable RANDEXEC + -s: disable SEGMEXEC -S: enable SEGMEXEC + + -v: view flags -z: restore default flags + -q: suppress error messages -Q: report flags in short format flags +</pre> + +<p> +The first option we will note is <c>-v</c>, which can display flags set on a +particular binary. +</p> + +<pre caption="paxctl -v"> +y0shi brandon # paxctl -v /usr/X11R6/bin/XFree86 +PaX control v0.2 +Copyright 2004 PaX Team <pageexec@freemail.hu> + +- PaX flags: -p-sM--x-eR- [/usr/X11R6/bin/XFree86] + PAGEEXEC is disabled + SEGMEXEC is disabled + MPROTECT is enabled + RANDEXEC is disabled + EMUTRAMP is disabled + RANDMMAP is enabled +</pre> + +<p> +This shows an XFree binary with all protections disabled. +</p> + +<p> +To set flags on a binary, the <c>-z</c> flag is useful as it restores the +default flags. +</p> + +<p> +To disable protections on XFree, run +<c>paxctl -zpeMRxs /usr/X11R6/bin/XFree86</c>. +</p> + +<p> +Play around with disabling/enabling protections to see what is the least needed +to run. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/etdyn.xml b/xml/etdyn.xml new file mode 100644 index 0000000..3afcbda --- /dev/null +++ b/xml/etdyn.xml @@ -0,0 +1,227 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="/proj/en/hardened/etdyn.xml"> + +<author title="Author"> + <mail link="pageexec@freemail.hu">The PaX Team</mail> +</author> +<author title="Contributor"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Contributor"> + <mail link="pappy@gentoo.org">Alexander Gabert</mail> +</author> +<author title="Editor"> + <mail link="zhen@gentoo.org">John Davis</mail> +</author> +<author title="Editor"> + <mail link="klasikahl@gentoo.org">Zack Gilburd</mail> +</author> +<abstract> +This guide contains documentation and examples on how to create dynamic ELF executables. +These guidelines are required to achieve full Address Space Layout Randomization. +</abstract> + +<version>1.1</version> +<date>5 Aug 2003</date> + +<chapter> + <title>Introduction</title> + <body> + <p>One of the features of PaX is Address Space Layout Randomization (ASLR) + that allows the kernel to randomize the addresses of various areas in + the task's address space. While most of ASLR requires no changes in + userland, randomizing the main executable's base address presents a + challenge as traditionally such ELF executables of the ET_EXEC kind + do not contain enough relocation information. Nevertheless, PaX provides + two ways to solve this problem: RANDEXEC and RANDMMAP. </p> + + <p>RANDEXEC works by mapping the ET_EXEC ELF file in a special way in memory + and requires no changes in userland (except for actually enabling it on + a given file, as this feature is disabled by default). The drawback of + this approach is that it is slow (the kernel compilation benchmark sees + a 3 times slow down for example) and prone to false positive detections + of so-called return-to-libc style attacks (which renders it unusable on + such executables). </p> + + <warn>Therefore this method mainly exists to prove a point + and is not intended for production use.</warn> + + <p>RANDMMAP on the other hand works on ELF files of the ET_DYN kind which is + normally used for dynamically linkable libraries. This approach has none + of the drawbacks that plague RANDEXEC because such ET_DYN ELF files have + enough relocation information and the dynamic linker has no problem with + relocating them (and there is no performance penalty at runtime), nor is + there a chance for false positive attack detections as none is done in the + first place. This means that protecting against the return-to-libc style + attack (in case the information about the randomization can leak to the + attacker) requires other approaches, which is not discussed here.</p> + + <p>It should be clear by now that the preferable way of randomizing the main + executable's base address is via RANDMMAP and not RANDEXEC. This in turn + means that we need a way to produce ET_DYN ELF executables instead of the + ET_EXEC kind. The following parts describe the process in detail and + hopefully provide enough information so that modifying existing packages + to produce ET_DYN ELF targets will not be a problem. Software authors + and/or package maintainers are encouraged to provide such make targets + themselves in the future.</p> + + </body> +</chapter> + +<chapter> + <title>How to produce ET_DYN ELF executables</title> + <body> + + <p>The following discussion assumes that the GNU toolchain (such as gcc and + ld) is used to produce the target file, other languages and tools should + follow the same principles however. The process has two main steps, first + compilation then linking, both of which need to be modified for producing + an ET_DYN ELF executable.</p> + + <p>Compilation has to be modified in order to produce position independent + code (PIC) which in turn allows the linker to not emit so-called text + relocations in the final ET_DYN ELF file. Although this step is not + strictly required (it does not affect the relocatability of the result), + it is useful as this allows for another security related hardening: PaX + normally makes it impossible to make an executable file mapping writable, + however for text relocations it has to make an exception. If there are + no such ET_DYN ELF files on a system, this exception can be removed and + then the only way to introduce new executable code into a task's address + space will be via file creation and mapping (which can be prevented by + other methods such as ACL systems). Producing PIC is very easy, one just + has to add the -fPIC switch to the compiler command line. This will not + get rid of all text relocations however as there are other sources of + (position dependent) code contributing to the final ET_DYN ELF file that + will lead us to the next step.</p> + + <p>Linking the main executable is governed by a special script called the + 'specs' file ('gcc -v' tells us what is used by default). Studying it in + detail is beyond our scope, but let's note the fact that there are more + object files linked into the result than one has specified on the linker + command line. These extra objects are necessary for implementing such + features as calling constructors/destructors or the low-level entry point + of the code (the main() C function is not the actual entry point of an ELF + executable). </p> + + <p>Linking an ET_DYN ELF file is initiated by specifying the -shared switch + on the gcc command line which in turn will affect what extra object files + go into the result. Since our actual goal is to produce the main executable + (vs. a shared library), we have to make sure that we link in all extra + objects normally expected by an ET_EXEC target and not necessarily those + specified by the specs file for libraries. Luckily there is only one extra + object we have to take care of: crt1.o (we will ignore profiling and not + care about gcrt1.o). It is no coincidence that crt1.o is not linked into + shared libraries as this object contains (among others) the low-level entry + point and startup code that invokes the C library startup code which in + turn calls main(). + <warn>Initiating the building of ET_DYN executables on Gentoo does not require us to put -shared in our CFLAGS or LDFLAGS</warn></p> + + <p>Making crt1.o position independent is easy, we just have to make use of the + GOT (in keeping with the tradition of the glibc naming convention for the + position independent version of the extra object files, we will call it + crt1S.o). There is one last issue to take care of: a dynamically linked + executable requires a special program header that specifies the dynamic + linker to be mapped into memory by the kernel on task creation. As we can + see it from the specs file, having the -shared switch on the linker command + line will omit the dynamic linker specification and would produce an + unusable ET_DYN ELF file. The solution is simple, we follow the approach + of glibc which is also an executable ET_DYN ELF file: the dynamic linker + is specified in an object file that contains the full path to the dynamic + linker in a specific ELF section that ld will recognize and convert into + the corresponding program header.</p> + + <p>The above method is demonstrated on a simple 'hello world' program that + is included with this document. The source code of the main executable + is in a.c, our PIC crt1 is in crt1S.S (it has to be written in assembly, + the code is directly derived from glibc 2.2) and finally interp.c defines + the dynamic linker (technically it could be put into crt1S.S as well to + reduce the number of extra files to a minimum). The makefile is very + simple as well, it compiles each source file into an object file and then + links them together. One important thing to note is the order of the + object files on the linker command line: crt1S.o must come first (that is, + before any object file of the application) and interp.o should follow it + directly as this will result in the interpreter program header getting + emitted before the PT_LOAD headers (which is the normal program header + ordering in ET_EXEC files, although it is not strictly necessary). Since + crt1S.o and interp.o are constant (they do not depend on the application + code) they can be compiled once and put into the same directory where + the other systemwide crt* files are.</p> + </body> +</chapter> + +<chapter> + <title>ET_DYN ELF executables (The Gentoo Way)</title> + <body> + + <p>On Gentoo this is accomplished by merging <i>hardened-gcc</i>: </p> + + <pre caption = "Emerging hardened-gcc"> +<c># emerge hardened-gcc</c> +</pre> + + <p><i>hardened-gcc</i> is an umbrella package for non-mainstream gcc modifications + The <i>hardened-gcc</i> packages was initially created by Alexander Gabert + for this special purpose we are serving here: rolling out the etdyn + specs file and interp.o together with the position independent + crt1S.o. But this package is not limited to that purpose. + It was designed to be the be used for any future changes to gentoo-hardened systems + regarding the improvement of gcc compiling binaries that are more secure + than the default product coming out when the vanilla gcc is used. And it can be used for ebuild packages to + "trigger" some alternative action once they "realize" that they are + getting built on a system equipped with a modified gcc for enforcing + gentoo hardened protection measures. Straight this means that when a + package is found to be breaking when used with the hardened-gcc changes, + the particular ebuild of that failing package can and will be modified + by our gentoo-hardened developers to put some "check" logic into it when + the hardened-gcc is found on the target system. </p> + + <p>As an example lets try the rebuilding our chpax binary as an ET_DYN + shared executable. We can use the file(1) command to determine if we + in fact we are building our executables as ET_EXEC or ET_DYN.</p> + + <p>The first example here we have chpax built as an ET_DYN and the second + one is chpax built as an ET_EXEC.</p> + + <pre caption = "Example files"> +<c># file /sbin/chpax</c> +/sbin/chpax: ELF 32-bit LSB shared object, Intel 80386, version 1 \ +(GNU/Linux), stripped +/sbin/chpax: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), for \ +GNU/Linux 2.0.0, dynamically linked (uses shared libs), stripped +</pre> + + </body> +</chapter> + + +<comment>To keep the bugs down for us we really dont want the +end user mucking with the specs -solar </comment> +<comment> + <p>We can further simplify the building of ET_DYN executables by modifying + a few sections of the default gcc specs file as demonstrated in the + specs.2.95.3 and specs.3.2.3 files (for the respective gcc versions). + To use the new specs file we can either replace the default one or pass + it on the gcc command line via the -specs switch (in the latter case we + could further trim down the new specs file and keep only the sections + that we changed: *cpp, *cc1, *endfile, *link and *startfile). From now + on invoking gcc as 'gcc -et_dyn' will produce an ET_DYN executable (the + same goes for g++).</p> + + <p>Readers interested in rebuilding entire distributions are encouraged to + take a look at the Adamantix (http://www.adamantix.org) and Hardened + Gentoo projects (http://www.gentoo.org/proj/en/hardened/).</p> +</comment> +<chapter> + <title>Credits</title> + <section> + <title>Works Cited</title> + <body> + <ul><li><uri link="http://pax.grsecurity.net">PaX Homepage</uri></li></ul> + <ul><li><uri link="http://pax.grsecurity.net/docs/index.html">PaX Documentation</uri></li></ul> + <ul><li>Collective Work. PaX - Gentoo Wiki.</li></ul> + </body> + </section> +</chapter> + +</guide> diff --git a/xml/gnu-stack.xml b/xml/gnu-stack.xml new file mode 100644 index 0000000..5d682ed --- /dev/null +++ b/xml/gnu-stack.xml @@ -0,0 +1,455 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/gnu-stack.xml" lang="en"> +<title>The GNU Stack Quickstart</title> + +<author title="Author"> + <mail link="vapier@gentoo.org">Mike Frysinger</mail> +</author> +<author title="Author"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Contributor"> + <mail link="pageexec@freemail.hu">The PaX team</mail> +</author> +<author title="Contributor"> + <mail link="kevquinn@gentoo.org">Kevin F. Quinn</mail> +</author> + +<abstract>Handbook for proper GNU Stack management in ELF systems</abstract> + +<!-- The content of this document is placed into the public domain, have fun --> + +<version>3</version> +<date>2010-09-29</date> + +<chapter> +<title>Introduction</title> +<section> +<body> + +<p> +With the rise of mainstream consumer machines with hardware stack protection +(e.g. the <uri link="http://en.wikipedia.org/wiki/NX_bit">NX bit</uri> on +amd64), we developers have to be doubly sure that our packages build with the +correct stack settings. Keep in mind that stack protection is an issue for all +architectures, not just x86 or amd64. +</p> + +<p> +The purpose of this document is to help package maintainers fix their packages +when they break. We will be focusing our attention on the GNU_STACK ELF +marking. ELF is simply a file format which all modern linux distros use. An +ELF can be an executable (say <path>/bin/ls</path>) or a library (say +<path>/lib/libncurses.so</path>). GNU_STACK is just an ELF program header +which tells the system how to control the stack when the ELF is loaded into +memory. +</p> + +<p> +Before getting started, you should read through the Wikipedia entry on the +<uri link="http://en.wikipedia.org/wiki/NX_bit">NX bit</uri>. You can skip it +of course if you're already familiar with the concept of executable versus +non-executable stacks. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Causes of executable stack markings</title> +<section> +<body> + +<p> +ELF files end up with executable stack markings in one of three ways: +</p> + +<ol> + <li>GCC generates code that uses executable stack</li> + <li>an object built from assembler source includes a marking indicating to + the linker that it needs an executable stack (the GNU-stack note set for + executable stack)</li> + <li>an object built from assembler source is missing the GNU-stack note; + a very common occurrence especially for code expected to work on + many platforms</li> +</ol> + +<p> +GCC generates code to be executed on the stack when it implements a +<uri link="http://gcc.gnu.org/onlinedocs/gccint/Trampolines.html">trampoline +for nested functions</uri>. To remove the need for an executable stack in +this case, it is necessary to rewrite the code another way. Sometimes this +is relatively easy, other times not. +</p> + +<p> +If an assembler source file includes a GNU-stack note that indicates it needs +an executable stack, presumably this is by design. Again, in order to remove +the need for an executable stack, the code probably needs to be rewritten. +</p> + +<p> +If an assembler source contains no GNU-stack note, the system by default +assumes that an executable stack may be required. However, usually if there's +no GNU-stack note, this is simply because the author didn't include one, +rather than the code actually needing an executable stack. +</p> + +<p> +In the first two cases above, the executable stack marking is correct, and +should only be removed by rewriting the code to eliminate the executable +stack requirement. Such rewriting has to be considered on a case-by-case +basis and is outside the scope of this document, at least for now. Here we +focus on the third case, where the upstream author has not indicated whether +the assembler object needs an executable stack; fixing this means adding the +GNU-stack note to the source to indicate an executable stack is not necessary. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Finding ELFs that ask for an executable stack</title> +<section> +<body> + +<p> +Before you can start fixing something, you have to make sure it's broken first, +right? For this reason, we've developed a suite of tools named <uri +link="/proj/en/hardened/pax-utils.xml">PaX Utilities</uri>. If you are not +familiar with these utilities, you should read the <uri +link="/proj/en/hardened/pax-utils.xml">PaX Utilities Guide</uri> now. Gentoo users +can simply do <c>emerge pax-utils</c>. Non-Gentoo users should be able to +find a copy of the source tarball in the <path>distfiles</path> on a <uri +link="/main/en/mirrors.xml">Gentoo Mirror</uri>. Once you have the PaX +Utilities setup on your system, we can start playing around with +<c>scanelf</c>. +</p> + +<p> +Let's see if your system has any ELFs that want an executable stack. +</p> + +<pre caption="Scan your system"> +$ <i>scanelf -lpqe</i> +RWX --- --- /usr/lib/opengl/xorg-x11/lib/libGL.so.1.2 +RWX --- --- /usr/lib/libcrypto.so.0.9.7 +RWX --- --- /usr/lib/libmp.so.3.1.7 +RWX --- --- /usr/lib/libSDL-1.2.so.0.7.2 +RWX --- --- /usr/lib/libsmpeg-0.4.so.0.1.3 +RWX --- --- /usr/lib/libImlib2.so.1.2.0 +RWX --- --- /usr/lib/libOSMesa.so.4.0 +RWX --- --- /usr/lib/libxvidcore.so.4.1 +RWX --- --- /usr/lib/libgmp.so.3.3.3 +RWX --- --- /usr/bin/mencoder +RWX --- --- /usr/bin/Xorg +RWX --- --- /usr/bin/mplayer +</pre> + +<p> +We really only need to look at the first column (which corresponds to the ELF +GNU_STACK markings). Most of the time, if we fix that field, all the others +fall into place. As we can see above, many files are marked with an +executable stack (<e>RWX</e>). We want to make sure all files are marked +with <e>RW-</e>. The large majority of the time this means the package was +compiled incorrectly, so not much will have to be done with patching up the +source code. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>What needs to be fixed</title> +<section> +<body> + +<p> +We now know what files need to be fixed, but what source files are causing +this breakage? The only way to find this out is to compile the package and +analyze the object files before they are combined into the final executable or +library. +</p> + +</body> +</section> + +<section> +<title>Fixing smpeg</title> +<body> + +<p> +So we first have to compile smpeg before we can analyze it. +</p> + +<pre caption="Compiling smpeg"> +$ <i>ebuild /usr/portage/media-libs/smpeg/smpeg-0.4.4-r6.ebuild clean unpack compile</i> +$ <i>cd /var/tmp/portage/smpeg-0.4.4-r6/work/smpeg-0.4.4/</i> +</pre> + +<p> +Now we need to look at each object file and see if it has a +<e>.note.GNU-stack</e> ELF section. Chances are, the object which is causing +us trouble lacks this section completely. In that case, the compiler will +assume that the ELF should not be restricted at all and mark it as <e>RWX</e>. +The <c>scanelf</c> utility will display output slightly different when +presented with an object that is missing the ELF section. The <b>!WX</b> +below means that "Oh no, the GNU-stack is missing and write/execute permissions +will be used by default!" +</p> + +<pre caption="Locate missing .note.GNU-stack sections"> +$ <i>scanelf -qeR .</i> +!WX --- --- ./video/mmxflags_asm.o +!WX --- --- ./video/mmxflags_asm.lo +!WX --- --- ./video/mmxidct_asm.o +!WX --- --- ./video/mmxidct_asm.lo +</pre> + +<p> +Sure enough, these objects lack the <e>.note.GNU-stack</e> ELF section and +they are linked into the final <path>libsmpeg.so</path> library. If we were +to patch the source files <path>video/mmxflags_asm.S</path> and +<path>video/mmxidct_asm.S</path> so that they contain <e>.note.GNU-stack</e>, +everything would be peachy. +</p> + +</body> +</section> + +<section> +<title>Check objects by hand</title> +<body> + +<p> +For fun, lets see how we could use the more common <c>readelf</c> utility +(which is part of the <e>binutils</e> package). +</p> + +<pre caption="Using readelf"> +<comment>This is what the output should look like, notice the .note.GNU-stack line</comment> + +$ <i>readelf -S plaympeg.o</i> +There are 12 section headers, starting at offset 0x256c: + +Section Headers: + [Nr] Name Type Addr Off Size ES Flg Lk Inf Al + [ 0] NULL 00000000 000000 000000 00 0 0 0 + [ 1] .text PROGBITS 00000000 000040 001ede 00 AX 0 0 16 + [ 2] .rel.text REL 00000000 0030c0 000728 08 10 1 4 + [ 3] .data PROGBITS 00000000 001f20 000000 00 WA 0 0 4 + [ 4] .bss NOBITS 00000000 001f20 000000 00 WA 0 0 4 + [ 5] .rodata.str1.4 PROGBITS 00000000 001f20 0003db 01 AMS 0 0 4 + [ 6] .rodata.str1.1 PROGBITS 00000000 0022fb 0001c9 01 AMS 0 0 1 + <i>[ 7] .note.GNU-stack PROGBITS 00000000 0024c4 000000 00 0 0 1</i> + [ 8] .comment PROGBITS 00000000 0024c4 00003e 00 0 0 1 + [ 9] .shstrtab STRTAB 00000000 002502 000067 00 0 0 1 + [10] .symtab SYMTAB 00000000 00274c 0005e0 10 11 9 4 + [11] .strtab STRTAB 00000000 002d2c 000394 00 0 0 1 +Key to Flags: + W (write), A (alloc), X (execute), M (merge), S (strings) + I (info), L (link order), G (group), x (unknown) + O (extra OS processing required) o (OS specific), p (processor specific) + + +<comment>Notice how there is no .note.GNU-stack section here</comment> + +$ <i>readelf -S video/mmxidct_asm.o</i> +There are 8 section headers, starting at offset 0x738: + +Section Headers: + [Nr] Name Type Addr Off Size ES Flg Lk Inf Al + [ 0] NULL 00000000 000000 000000 00 0 0 0 + [ 1] .text PROGBITS 00000000 000034 0005ee 00 AX 0 0 4 + [ 2] .rel.text REL 00000000 000a4c 0000f0 08 6 1 4 + [ 3] .data PROGBITS 00000000 000630 0000d8 00 WA 0 0 16 + [ 4] .bss NOBITS 00000000 000708 000000 00 WA 0 0 4 + [ 5] .shstrtab STRTAB 00000000 000708 000030 00 0 0 1 + [ 6] .symtab SYMTAB 00000000 000878 000120 10 7 17 4 + [ 7] .strtab STRTAB 00000000 000998 0000b1 00 0 0 1 +Key to Flags: + W (write), A (alloc), X (execute), M (merge), S (strings) + I (info), L (link order), G (group), x (unknown) + O (extra OS processing required) o (OS specific), p (processor specific) +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>How to fix the stack (in theory)</title> +<section> +<body> + +<p> +When you compile source code normally, gcc takes care of adding the GNU_STACK +markings so that the final object code is not marked with an executable +stack unless it actually needs it. However, if you compile assembly code, +gcc will not automatically add GNU_STACK markings. So, the most common source +of executable stacks in ELF binaries are packages which include raw assembly +code. Note that we're not talking about inline assembly code, but rather +files like <e>.S</e> which are written in pure assembler. +</p> + +<p> +We can either patch each source file written in assembler and send the fixes +upstream, or we can be lazy and simply force the package build system to +assemble the source files with the GNU as option <e>--noexecstack</e> (but +this is highly discouraged). +</p> + +<p> +The advantage to patching the code is that it's easy to do, it's portable, +and we can usually convince upstream to add it to their packages with little +fuss. The disadvantage to patching is that we may have to patch many many +files. +</p> + +<p> +The advantage to just using <e>--noexecstack</e> is that you can simply add it +to your ebuild and be done. The disadvantage is that the option isn't very +portable (it won't work with non-GNU systems, and it probably won't even +work with all GNU systems), and we can't really convince upstream to make this +change. Thus, the only people who see the benefit here is Gentoo users. You +gotta think big baby! +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>How to fix the stack (in practice)</title> + +<section> +<title>Patching</title> +<body> + +<p> +The great thing about patching is that you can copy and paste this stuff +everywhere. Just make sure the code will be preprocessed (e.g. the source +file is named with <e>.S</e> and not <e>.s</e>). Stick these code snippets +at the end of the source file, recompile, and do a jig. +</p> + +<pre caption="Stack markings for GNU as (arch-independent)"> +#if defined(__linux__) && defined(__ELF__) +.section .note.GNU-stack,"",%progbits +#endif +</pre> + +<pre caption="Stack markings for NASM/YASM (x86/amd64-only)"> +%ifidn __OUTPUT_FORMAT__,elf +section .note.GNU-stack noalloc noexec nowrite progbits +%endif +</pre> + +</body> +</section> + +<section> +<title>Compiling with --noexecstack</title> +<body> + +<p> +Often times you only need to add the following code in your ebuild. You must +first be sure that the code does not actually require an executable stack as +forcing this flag will break the package otherwise. +</p> + +<impo> +Please rethink patching before using this option. Patching source code +benefits a lot more people which is the goal of OSS. +</impo> + +<pre caption="Using --noexecstack"> +<comment># This line goes at the top of your ebuild</comment> +inherit flag-o-matic + +<comment># This line goes before CFLAGS is used (either by the ebuild or by econf/emake)</comment> +append-flags -Wa,--noexecstack +</pre> + +<p> +On the off chance that you cannot assemble the files, you can tell the linker +to disable execstack stack. +</p> + +<pre caption="Using -z noexecstack"> +<comment># This line goes at the top of your ebuild</comment> +inherit flag-o-matic + +<comment># This line goes before LDFLAGS is used (either by the ebuild or by econf/emake)</comment> +append-ldflags -Wl,-z,noexecstack +</pre> + +</body> +</section> + +<section> +<title>If all else fails ...</title> +<body> + +<p> +If all else fails, ask around on #gentoo-dev on the irc server +irc.freenode.net. Or send an e-mail to the <uri +link="http://www.gentoo.org/main/en/lists.xml">gentoo-dev mailing list</uri>. +If no one can seem to answer your question, give me a poke either on irc +(nickname SpanKY/vapier) or via <mail link="vapier@gentoo.org">e-mail</mail>. +</p> + +</body> +</section> + +</chapter> + +<chapter> +<title>Arch Status</title> +<section> +<body> + +<table> + <tr><th>Arch</th> <th>Status</th></tr> + <tr><ti>alpha</ti> <ti>gcc generates proper .note.GNU-stack, but final link results in exec stack</ti></tr> + <tr><ti>amd64</ti> <ti>fully supported</ti></tr> + <tr><ti>arm</ti> <ti>fully supported (gcc-4.1.x/glibc-2.5)</ti></tr> + <tr><ti>blackfin</ti> <ti>fully supported (gcc-4.3+)</ti></tr> + <tr><ti>hppa</ti> <ti>gcc-3.4.x does not generate .note.GNU-stack</ti></tr> + <tr><ti>ia64</ti> <ti>fully supported (gcc-3.4.4+)</ti></tr> + <tr><ti>m68k</ti> <ti>fully supported (gcc-3.4.x)</ti></tr> + <tr><ti>mips</ti> <ti>gcc-3.4.x does not generate .note.GNU-stack</ti></tr> + <tr><ti>ppc</ti> <ti>gcc generates proper .note.GNU-stack, but final link results in exec stack</ti></tr> + <tr><ti>ppc64</ti> <ti>gcc generates proper .note.GNU-stack, but final link results in exec stack</ti></tr> + <tr><ti>s390</ti> <ti>fully supported</ti></tr> + <tr><ti>s390x</ti> <ti>fully supported</ti></tr> + <tr><ti>sh</ti> <ti>fully supported (gcc-3.4.x/glibc-2.5)</ti></tr> + <tr><ti>sparc</ti> <ti>fully supported</ti></tr> + <tr><ti>x86</ti> <ti>fully supported</ti></tr> +</table> + +</body> +</section> +</chapter> + +<chapter> +<title>References</title> +<section> +<body> + +<ul> + <li>thanks to the <uri link="http://pax.grsecurity.net/">PaX team</uri> for holding my hand</li> + <li>Roland McGrath's <uri link="http://www.redhat.com/archives/fedora-devel-list/2003-November/msg00838.html">brain dump</uri></li> + <li><uri link="http://en.wikipedia.org/wiki/NX_bit">NX bit</uri> Wikipedia entry</li> +</ul> + +</body> +</section> +</chapter> + +</guide> diff --git a/xml/grsecurity.xml b/xml/grsecurity.xml new file mode 100644 index 0000000..53669d7 --- /dev/null +++ b/xml/grsecurity.xml @@ -0,0 +1,905 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="/proj/en/hardened/grsecurity.xml"> + +<title>Gentoo Grsecurity v2 Guide</title> + +<author title="Author"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Author"> + <mail link="swift@gentoo.org">Sven Vermeulen</mail> +</author> + +<abstract> +This document features the grsecurity 2.x security patches, supported kernel +configuration options and tools provided by the grsecurity project to lift your +system's security to higher standards. +</abstract> + +<version>1</version> +<date>2010-01-05</date> + +<chapter> +<title>About Grsecurity</title> +<section> +<title>The Grsecurity Project</title> +<body> + +<p> +The grsecurity project, hosted on <uri>http://www.grsecurity.org</uri>, provides +various patches to the Linux kernel which enhance your system's overall +security. The various features brought by grsecurity are discussed in the next +chapter; a comprehensive list is maintained on the <uri +link="http://www.grsecurity.org/features.php">grsecurity features page</uri> +itself. +</p> + +<p> +As grsecurity's features are mostly kernel-based, the majority of this document +explains the various kernel features and their respective sysctl operands (if +applicable). +</p> + +</body> +</section> +<section> +<title>Gentoo Hardened Integration</title> +<body> + +<p> +The <uri link="http://hardened.gentoo.org">Gentoo Hardened Project</uri> +maintains security-enhancement features for Gentoo, including but not limited to +grsecurity. +</p> + +</body> +</section> +<section> +<title>Kernel Configuration</title> +<body> + +<p> +Throughout this document we will talk about kernel configuration using the +kernel variables like <c>CONFIG_GRKERNSEC_PAX_NO_ACL_FLAGS</c>. These are the +variables that the kernel build process uses to determine if a certain feature +needs to be compiled. +</p> + +<p> +When you configure your kernel through <c>make menuconfig</c> or similar, you +receive a user interface through which you can select the various kernel +options. If you select the <e>Help</e> button at a certain kernel feature you +will see at the top that it lists such a kernel variable. +</p> + +<p> +You can therefore still configure your kernel as you like - with a bit of +thinking. And if you can't find a certain option, there's always the possibility +to edit <path>/usr/src/linux/.config</path> by hand :) +</p> + +<p> +Of course, to be able to select the various grsecurity kernel options, you must +enable grsecurity in your kernel: +</p> + +<pre caption="Activating grsecurity"> +CONFIG_GRKERNSEC=y +CONFIG_GRKERNSEC_CUSTOM=y +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>PaX</title> +<section> +<title>Fighting the Exploitation of Software Bugs</title> +<body> + +<p> +PaX introduces a couple of security mechanisms that make it harder for attackers +to exploit software bugs that involve memory corruption (so don't treat PaX as +if it protects against all possible software bugs). The <uri +link="http://pax.grsecurity.net/docs/pax.txt">PaX introduction document</uri> +talks about three possible exploit techniques: +</p> + +<ol> + <li>introduce/execute arbitrary code</li> + <li>execute existing code out of original program order</li> + <li>execute existing code in original program order with arbitrary data</li> +</ol> + +<p> +One prevention method disallows executable code to be stored in writable +memory. When we look at a process, it requires five memory regions: +</p> + +<ol> + <li> + a <e>data section</e> which contains the statically allocated and global + data + </li> + <li> + a <e>BSS region</e> (Block Started by Symbol) which contains information + about the zero-initialized data of the process + </li> + <li> + a <e>code region</e>, also called the <e>text segment</e>, which contains + the executable instructions + </li> + <li> + a <e>heap</e> which contains the dynamically allocated memory + </li> + <li> + a <e>stack</e> which contains the local variables + </li> +</ol> + +<p> +The first PaX prevention method, called <b>NOEXEC</b>, is meant to give control +over the runtime code generation. It marks memory pages that do not contain +executable code as non-executable. This means that the heap and the stack, +which only contain variable data and shouldn't contain executable +code, are marked as non-executable. Exploits that place code in these areas with +the intention of running it will fail. +</p> + +<p> +NOEXEC does more than this actually, interested readers should focus their +attention to the <uri link="http://pax.grsecurity.net/docs/noexec.txt">PaX +NOEXEC documentation</uri>. +</p> + +<p> +The second PaX prevention method, called <b>ASLR</b> (Address Space Layout +Randomization), randomize the addresses given to memory requests. Where +previously memory was assigned contiguously (which means exploits know where +the tasks' memory regions are situated) ASLR randomizes this allocation, +rendering techniques that rely on this information useless. +</p> + +<p> +More information about ASLR can be found <uri +link="http://pax.grsecurity.net/docs/aslr.txt">online</uri>. +</p> + +</body> +</section> +<section> +<title>Enabling PaX</title> +<body> + +<p> +The recommended kernel setting for PaX is: +</p> + +<pre caption="Recommended PaX Kernel Configuration"> +<comment># +# PaX Control +# +# CONFIG_GRKERNSEC_PAX_SOFTMODE is not set</comment> +CONFIG_GRKERNSEC_PAX_EI_PAX=y +CONFIG_GRKERNSEC_PAX_PT_PAX_FLAGS=y +CONFIG_GRKERNSEC_PAX_NO_ACL_FLAGS=y +<comment># CONFIG_GRKERNSEC_PAX_HAVE_ACL_FLAGS is not set +# CONFIG_GRKERNSEC_PAX_HOOK_ACL_FLAGS is not set + +# +# Address Space Protection +#</comment> +CONFIG_GRKERNSEC_PAX_NOEXEC=y +<comment># CONFIG_GRKERNSEC_PAX_PAGEEXEC is not set</comment> +CONFIG_GRKERNSEC_PAX_SEGMEXEC=y +CONFIG_GRKERNSEC_PAX_EMUTRAMP=y +CONFIG_GRKERNSEC_PAX_MPROTECT=y +<comment># CONFIG_GRKERNSEC_PAX_NOELFRELOCS is not set</comment> +CONFIG_GRKERNSEC_PAX_ASLR=y +CONFIG_GRKERNSEC_PAX_RANDKSTACK=y +CONFIG_GRKERNSEC_PAX_RANDUSTACK=y +CONFIG_GRKERNSEC_PAX_RANDMMAP=y +CONFIG_GRKERNSEC_PAX_RANDEXEC=y +<comment># CONFIG_GRKERNSEC_KMEM is not set +# CONFIG_GRKERNSEC_IO is not set</comment> +CONFIG_GRKERNSEC_PROC_MEMMAP=y +CONFIG_GRKERNSEC_HIDESYM=y +</pre> + +<p> +If you are running a non-x86 system you will observe that there is no +CONFIG_GRKERNSEC_PAX_NOEXEC. You should select CONFIG_GRKERNSEC_PAX_PAGEEXEC +instead as it is the only non-exec implementation around. +</p> + +</body> +</section> +<section> +<title>Controlling PaX</title> +<body> + +<p> +Not all Linux applications are happy with the PaX security restrictions. These +tools include xorg-x11, java, mplayer, xmms and others. If you plan on using +them you can elevate the protections for these applications using <c>chpax</c> +and <c>paxctl</c>. +</p> + +<pre caption="Installing the chpax and paxctl tools"> +# <i>emerge sys-apps/chpax</i> +# <i>emerge sys-apps/paxctl</i> +</pre> + +<p> +chpax provides an init script that handles most known application settings for +you: +</p> + +<pre caption="Adding the chpax init script to the default runlevel"> +# <i>rc-update add chpax default</i> +</pre> + +<p> +<c>pax-utils</c> is a small toolbox which contains useful applications to +administrate a PaX aware server. +</p> + +<pre caption="Installing pax-utils"> +# <i>emerge pax-utils</i> +</pre> + +<p> +Interesting tools include <c>scanelf</c> and <c>pspax</c>: +</p> + +<ul> + <li> + With <c>scanelf</c> you can scan over library and binary directories and + list the various permissions and ELF types that pertain to running an ideal + pax/grsec setup + </li> + <li> + With <c>pspax</c> you can display PaX flags/capabilities/xattr from the + kernel's perspective + </li> +</ul> + +</body> +</section> +<section> +<title>Verifying the PaX Settings</title> +<body> + +<p> +Peter Busser has written a regression test suite called <c>paxtest</c>. This +tool will check various cases of possible attack vectors and inform you of the +result. When you run it, it will leave a logfile called <path>paxtest.log</path> +in the current working directory. +</p> + +<pre caption="Installing and running paxtest"> +# <i>emerge paxtest</i> + +# <i>paxtest</i> +Executable anonymous mapping : Killed +Executable bss : Killed +Executable data : Killed +Executable heap : Killed +Executable stack : Killed +Executable anonymous mapping (mprotect) : Killed +Executable bss (mprotect) : Killed +Executable data (mprotect) : Killed +Executable heap (mprotect) : Killed +Executable stack (mprotect) : Killed +Executable shared library bss (mprotect) : Killed +Executable shared library data (mprotect): Killed +Writable text segments : Killed +Anonymous mapping randomisation test : 16 bits (guessed) +Heap randomisation test (ET_EXEC) : 13 bits (guessed) +Heap randomisation test (ET_DYN) : 25 bits (guessed) +Main executable randomisation (ET_EXEC) : 16 bits (guessed) +Main executable randomisation (ET_DYN) : 17 bits (guessed) +Shared library randomisation test : 16 bits (guessed) +Stack randomisation test (SEGMEXEC) : 23 bits (guessed) +Stack randomisation test (PAGEEXEC) : No randomisation +Return to function (strcpy) : Vulnerable +Return to function (memcpy) : Vulnerable +Return to function (strcpy, RANDEXEC) : Killed +Return to function (memcpy, RANDEXEC) : Killed +Executable shared library bss : Killed +Executable shared library data : Killed +</pre> + +<p> +In the above example run you notice that: +</p> + +<ul> + <li> + strcpy and memcpy are listed as <e>Vulnerable</e>. This is expected and + normal - it is simply showing the need for a technology such as ProPolice/SSP + </li> + <li> + there is no randomization for PAGEEXEC. This is normal since our recommended + x86 kernel configuration didn't activate the PAGEEXEC setting. However, on + arches that support a true NX (non-executable) bit (most of them do, + including x86_64), PAGEEXEC is the only method available for NOEXEC and + has no performance hit. + </li> +</ul> + +</body> +</section> +</chapter> + +<chapter> +<title>RBAC</title> +<section> +<title>Role Based Access Control</title> +<body> + +<p> +There are two basic types of access control mechanisms used to prevent +unauthorized access to files (or information in general): DAC (Discretionary +Access Control) and MAC (Mandatory Access Control). By default, Linux uses a DAC +mechanism: the creator of the file can define who has access to the file. A MAC +system however forces everyone to follow rules set by the administrator. +</p> + +<p> +The MAC implementation grsecurity supports is called Role Based Access +Control. RBAC associates <e>roles</e> with each user. Each role defines what +operations can be performed on certain objects. Given a well-written collection +of roles and operations your users will be restricted to perform only those +tasks that you tell them they can do. The default "deny-all" ensures you that a +user cannot perform an action you haven't thought of. +</p> + +</body> +</section> +<section> +<title>Configuring the Kernel</title> +<body> + +<p> +The recommended kernel setting for RBAC is: +</p> + +<pre caption="Recommended RBAC Kernel Configuration"> +<comment># +# Role Based Access Control Options +#</comment> +CONFIG_GRKERNSEC_ACL_HIDEKERN=y +CONFIG_GRKERNSEC_ACL_MAXTRIES=3 +CONFIG_GRKERNSEC_ACL_TIMEOUT=30 +</pre> + +</body> +</section> +<section> +<title>Working with gradm</title> +<body> + +<p> +<c>gradm</c> is a tool which allows you to administer and maintain a policy for +your system. With it, you can enable or disable the RBAC system, reload +the RBAC roles, change your role, set a password for admin mode, etc. +</p> + +<p> +When you install <c>gradm</c> a default policy will be installed in +<path>/etc/grsec/policy</path>: +</p> + +<pre caption="Installing gradm"> +# <i>emerge gradm</i> +</pre> + +<p> +By default, the RBAC policies are not activated. It is the sysadmin's job to +determine when the system should have an RBAC policy enforced and not Gentoo's. +Before activating the RBAC system you should set an admin password. +</p> + +<pre caption="Activating the RBAC system"> +# <i>gradm -P</i> +Setting up grsecurity RBAC password +Password: <comment>(Enter a well-chosen password)</comment> +Re-enter Password: <comment>(Enter the same password for confirmation)</comment> +Password written in /etc/grsec/pw +# <i>gradm -E</i> +</pre> + +<p> +To disable the RBAC system, run <c>gradm -D</c>. If you are not allowed to, you +first need to switch to the admin role: +</p> + +<pre caption="Disabling the RBAC system"> +# <i>gradm -a admin</i> +Password: <comment>(Enter your admin role password)</comment> +# <i>gradm -D</i> +</pre> + +<p> +If you want to leave the admin role, run <c>gradm -u admin</c>: +</p> + +<pre caption="Dropping the admin role"> +# <i>gradm -u admin</i> +</pre> + +</body> +</section> +<section> +<title>Generating a Policy</title> +<body> + +<p> +The RBAC system comes with a great feature called "learning mode". The learning +mode can generate an anticipatory least privilege policy for your system. This +allows for time and money savings by being able to rapidly deploy multiple +secure servers. +</p> + +<p> +To use the learning mode, activate it using <c>gradm</c>: +</p> + +<pre caption="Activating the RBAC learning mode"> +# <i>gradm -F -L /etc/grsec/learning.log</i> +</pre> + +<p> +Now use your system, do the things you would normally do. Try to avoid rsyncing, +running locate of any other heavy file i/o operation as this can really slow +down the processing time. +</p> + +<p> +When you believe you have used your system sufficiently to obtain a good policy, +let <c>gradm</c> process them and propose roles under +<path>/etc/grsec/learning.roles</path>: +</p> + +<pre caption="Processing learning mode logs"> +# <i>gradm -F -L /etc/grsec/learning.log -O /etc/grsec/learning.roles</i> +</pre> + +<p> +Audit the <path>/etc/grsec/learning.roles</path> and save it as +<path>/etc/grsec/policy</path> (mode 0600) when you are finished. +</p> + +<pre caption="Saving the policies"> +# <i>mv /etc/grsec/learning.roles /etc/grsec/policy</i> +# <i>chmod 0600 /etc/grsec/policy</i> +</pre> + +<p> +You will now be able to enable the RBAC system with your new learned policy. +</p> + +</body> +</section> +<section> +<title>Tweaking your Policy</title> +<body> + +<p> +An interesting feature of grsecurity 2.x is <e>Set Operation Support</e> for the +configuration file. Currently it supports unions, intersections and differences +of sets (of objects in this case). +</p> + +<pre caption="Example sets"> +define objset1 { +/root/blah rw +/root/blah2 r +/root/blah3 x +} + +define somename2 { +/root/test1 rw +/root/blah2 rw +/root/test3 h +} +</pre> + +<p> +Here is an example of its use, and the resulting objects that will be added to +your subject: +</p> + +<pre caption="& Example"> +subject /somebinary o +$objset1 & $somename2 +</pre> + +<p> +The above would expand to: +</p> + +<pre caption="Resulting subject settings"> +subject /somebinary o +/root/blah2 r +</pre> + +<p> +This is the result of the & operator which takes both sets and returns the +files that exist in both sets and the permission for those files that exist +in both sets. +</p> + +<pre caption="| Example"> +subject /somebinary o +$objset1 | $somename2 +</pre> + +<p> +This example would expand to: +</p> + +<pre caption="Resulting subject settings"> +subject /somebinary o +/root/blah rw +/root/blah2 rw +/root/blah3 x +/root/test1 rw +/root/test3 h +</pre> + +<p> +This is the result of the | operator which takes both sets and returns the +files that exist in either set. If a file exists in both sets, it is returned +as well and the mode contains the flags that exist in either set. +</p> + +<pre caption="- Example"> +subject /somebinary o +$objset1 - $somename2 +</pre> + +<p> +This example would expand to: +</p> + +<pre caption="Resulting subject settings"> +subject /somebinary o +/root/blah rw +/root/blah2 h +/root/blah3 x +</pre> + +<p> +This is the result of the - operator which takes both sets and returns the +files that exist in the set on the left but not in the match of the file in +set on the right. If a file exists on the left and a match is found on the +right (either the filenames are the same, or a parent directory exists in +the right set), the file is returned and the mode of the second set is +removed from the first set, and that file is returned. +</p> + +<p> +In some obscure pseudo-language you could see this as: +</p> + +<pre caption="Pseudo-language explanation"> +if ( (<i>$objset1</i> contained <i>/tmp/blah rw</i>) and + (<i>$objset2</i> contained <i>/tmp/blah r</i>) ) +then + <i>$objset1 - $objset2</i> would contain <i>/tmp/blah w</i> + +if ( (<i>$objset1</i> contained <i>/tmp/blah rw</i>) and + (<i>$objset2</i> contained <i>/ rwx</i>) ) +then + <i>$objset1 - $objset2</i> would contain <i>/tmp/blah h</i> +</pre> + +<p> +As for order of precedence (from highest to lowest): "-, & |". +</p> + +<p> +If you do not want to bother remembering precedence, parenthesis support +is also included, so you can do things like: +</p> + +<pre caption="Parenthesis example"> +(($set1 - $set2) | $set3) & $set4 +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>Filesystem Protection</title> +<section> +<title>Fighting Chroot and Filesystem Abuse</title> +<body> + +<p> +Grsecurity2 includes many patches that prohibits users from gaining unnecessary +knowledge about the system. This includes restrictions on <path>/proc</path> +usage, chrooting, linking, etc. +</p> + +</body> +</section> +<section> +<title>Kernel Configuration</title> +<body> + +<p> +We recommend the following grsecurity kernel configuration for filesystem +protection: +</p> + +<pre caption="Activating Filesystem Protection"> +<comment># +# Filesystem Protections +#</comment> +CONFIG_GRKERNSEC_PROC=y +<comment># CONFIG_GRKERNSEC_PROC_USER is not set</comment> +CONFIG_GRKERNSEC_PROC_USERGROUP=y +CONFIG_GRKERNSEC_PROC_GID=10 +CONFIG_GRKERNSEC_PROC_ADD=y +CONFIG_GRKERNSEC_LINK=y +CONFIG_GRKERNSEC_FIFO=y +CONFIG_GRKERNSEC_CHROOT=y +CONFIG_GRKERNSEC_CHROOT_MOUNT=y +CONFIG_GRKERNSEC_CHROOT_DOUBLE=y +CONFIG_GRKERNSEC_CHROOT_PIVOT=y +CONFIG_GRKERNSEC_CHROOT_CHDIR=y +CONFIG_GRKERNSEC_CHROOT_CHMOD=y +CONFIG_GRKERNSEC_CHROOT_FCHDIR=y +CONFIG_GRKERNSEC_CHROOT_MKNOD=y +CONFIG_GRKERNSEC_CHROOT_SHMAT=y +CONFIG_GRKERNSEC_CHROOT_UNIX=y +CONFIG_GRKERNSEC_CHROOT_FINDTASK=y +CONFIG_GRKERNSEC_CHROOT_NICE=y +CONFIG_GRKERNSEC_CHROOT_SYSCTL=y +CONFIG_GRKERNSEC_CHROOT_CAPS=y +</pre> + +</body> +</section> +<section> +<title>Triggering the Security Mechanism</title> +<body> + +<p> +When you're using a kernel compiled with the above (or similar) settings, you +will get the option to enable/disable many of the options through the +<path>/proc</path> filesystem or via <c>sysctl</c>. +</p> + +<p> +The example below shows an excerpt of a typical <path>/etc/sysctl.conf</path>: +</p> + +<pre caption="Example settings inside /etc/sysctl.conf"> +kernel.grsecurity.chroot_deny_sysctl = 1 +kernel.grsecurity.chroot_caps = 1 +kernel.grsecurity.chroot_execlog = 0 +kernel.grsecurity.chroot_restrict_nice = 1 +kernel.grsecurity.chroot_deny_mknod = 1 +kernel.grsecurity.chroot_deny_chmod = 1 +kernel.grsecurity.chroot_enforce_chdir = 1 +kernel.grsecurity.chroot_deny_pivot = 1 +kernel.grsecurity.chroot_deny_chroot = 1 +kernel.grsecurity.chroot_deny_fchdir = 1 +kernel.grsecurity.chroot_deny_mount = 1 +kernel.grsecurity.chroot_deny_unix = 1 +kernel.grsecurity.chroot_deny_shmat = 1 +</pre> + +<p> +You can enable or disable settings at will using the <c>sysctl</c> command: +</p> + +<pre caption="Enabling sysctl settings"> +<comment>(Toggling the exec_logging feature ON)</comment> +# <i>sysctl -w kernel.grsecurity.exec_logging = 1</i> +<comment>(Toggling the exec_logging feature OFF)</comment> +# <i>sysctl -w kernel.grsecurity.exec_logging = 0</i> +</pre> + +<p> +There is a very important sysctl setting pertaining to grsecurity, namely +<c>kernel.grsecurity.grsec_lock</c>. When set, you are not able to change any +setting anymore. +</p> + +<pre caption="Locking the sysctl interface"> +# <i>sysctl -w kernel.grsecurity.grsec_lock = 1</i> +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>Kernel Auditing</title> +<section> +<title>Extend your System's Logging Facilities</title> +<body> + +<p> +grsecurity adds extra functionality to the kernel pertaining the logging. With +grsecurity's <e>Kernel Auditing</e> the kernel informs you when applications are +started, devices (un)mounted, etc. +</p> + +</body> +</section> +<section> +<title>The various Kernel Audit Settings</title> +<body> + +<p> +The following kernel configuration section can be used to enable grsecurity's +Kernel Audit Settings: +</p> + +<pre caption="Activating Kernel Auditing"> +<comment># +# Kernel Auditing +# +# CONFIG_GRKERNSEC_AUDIT_GROUP is not set</comment> +CONFIG_GRKERNSEC_EXECLOG=y +CONFIG_GRKERNSEC_RESLOG=y +CONFIG_GRKERNSEC_CHROOT_EXECLOG=y +CONFIG_GRKERNSEC_AUDIT_CHDIR=y +CONFIG_GRKERNSEC_AUDIT_MOUNT=y +CONFIG_GRKERNSEC_AUDIT_IPC=y +CONFIG_GRKERNSEC_SIGNAL=y +CONFIG_GRKERNSEC_FORKFAIL=y +CONFIG_GRKERNSEC_TIME=y +CONFIG_GRKERNSEC_PROC_IPADDR=y +CONFIG_GRKERNSEC_AUDIT_TEXTREL=y +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>Process Restrictions</title> +<section> +<title>Executable Protection</title> +<body> + +<p> +With grsecurity you can restrict executables. Since most exploits work through +one or more running processes this protection can save your system's health. +</p> + +</body> +</section> +<section> +<title>Network Protection</title> +<body> + +<p> +Linux' TCP/IP stack is vulnerable to prediction-based attacks. grsecurity +includes randomization patches to counter these attacks. Apart from these you +can also enable socket restrictions, disallowing certain groups network access +alltogether. +</p> + +</body> +</section> +<section> +<title>Kernel Settings</title> +<body> + +<p> +The following kernel settings enable various executable and network protections: +</p> + +<pre caption="Kernel setting"> +<comment># +# Executable Protections +#</comment> +CONFIG_GRKERNSEC_EXECVE=y +CONFIG_GRKERNSEC_DMESG=y +CONFIG_GRKERNSEC_RANDPID=y +CONFIG_GRKERNSEC_TPE=y +CONFIG_GRKERNSEC_TPE_ALL=y +CONFIG_GRKERNSEC_TPE_GID=100 + +<comment># +# Network Protections +#</comment> +CONFIG_GRKERNSEC_RANDNET=y +CONFIG_GRKERNSEC_RANDISN=y +CONFIG_GRKERNSEC_RANDID=y +CONFIG_GRKERNSEC_RANDSRC=y +CONFIG_GRKERNSEC_RANDRPC=y +<comment># CONFIG_GRKERNSEC_SOCKET is not set</comment> +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>The Hardened Toolchain</title> +<section> +<body> + +<p> +Although it is outside the scope of this document we mention the use of the +hardened toolchain which completes the grsec/PaX model from userspace. As a +quickstart you can do: +</p> + +<pre caption="Using the hardened toolchain"> +# <i>cd /etc</i> +# <i>rm make.profile</i> +# <i>ln -s ../usr/portage/profiles/hardened/x86 make.profile</i> +# <i>emerge -e world</i> +</pre> + +<p> +If you don't want to use this profile, add these <c>hardened pic</c> USE flags to your +USE variable in <path>/etc/make.conf</path>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Resources</title> +<section> +<body> + +<ul> + <li><uri link="http://grsecurity.net/">Grsecurity Homepage</uri></li> + <li><uri link="http://forums.grsecurity.net/">Grsecurity Forums</uri></li> + <li> + <uri link="http://grsecurity.net/researchpaper.pdf">Increasing Performance + and Granularity in Role-Based Access Control Systems</uri> + + </li> + <li> + <uri link="http://www.gentoo.org/proj/en/hardened/capabilities.xml"> + Capability Names and Descriptions</uri> + </li> + <li> + <uri link="http://grsecurity.net/quickstart.pdf">Grsecurity Quick-Start + Guide</uri> (NEW .pdf) + </li> + + <li> + <uri link="http://www.gentoo.org/proj/en/hardened/pax-quickstart.xml">Using PaX with + Gentoo QuickStart</uri> (NEW) + </li> + <li> + <uri link="http://hardened.gentoo.org/grsecurity.xml">Grsecurity with + Gentoo 1.9.x MAC system</uri> (OLD) + </li> + <li> + <uri link="http://grsecurity.net/PaX-presentation_files/frame.htm">PaX: The + Guaranteed End of Arbitrary Code Execution</uri> + + </li> + <li> + <uri link="http://pax.grsecurity.net">PaX HomePage and Documentation</uri> + </li> + <li> + <uri link="http://www.gentoo.org/proj/en/infrastructure/tenshi">Tenshi</uri> + </li> +</ul> + + +</body> +</section> +</chapter> + +</guide> diff --git a/xml/hardened-toolchain.xml b/xml/hardened-toolchain.xml new file mode 100644 index 0000000..742a51f --- /dev/null +++ b/xml/hardened-toolchain.xml @@ -0,0 +1,444 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/hardened-toolchain.xml" lang="en" disclaimer="draft"> +<title>The Gentoo Hardened Toolchain</title> + +<author title="Author"> +<mail link="kevquinn@gentoo.org">Kevin F. Quinn</mail> +</author> + +<author title="Contributor"> +<mail link="solar@gentoo.org">Ned Ludd</mail> +</author> + +<author title="Contributor"> +<mail link="pageexec@freemail.hu">The PaX Team</mail> +</author> + +<abstract> +Technical description of, and rationale for, the Gentoo Hardened Toolchain modifications. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> +<license/> + +<version>1.0</version> +<date>2006-08-31</date> + + +<chapter id="introduction"> +<title>Introduction to the Gentoo Hardened toolchain</title> + +<section id="todo"> +<title>TODO</title> +<body> + +<ul> +<li>Binutils modifications for PaX</li> +<li>Comment on relationship to SELinux</li> +</ul> + +</body> +</section> + +<section id="overview"> +<title>Overview</title> +<body> + +<p> +The Gentoo Hardened project introduces a number of changes to the default behaviour of the toolchain (gcc, binutils, glibc/uclibc) intended to improve security. It supports other initiatives taken by the hardened project; most directly PaX and Grsecurity, but can also be applied to SELinux and RSBAC. This document describes each of the modifications made to the toolchain, showing what they achieve and how they relate to the Gentoo hardened strategy. +</p> + +</body> +</section> + +<section id="SSPintro"> +<title>Default addition of the Stack Smashing Protector (SSP)</title> +<body> + +<p> +First developed by Dr Hiroaki Etoh at IBM for the 3.x series of GCC (originally under the name ProPolice) and re-developed in a different way for the 4.x series by RedHat, the Stack Smashing Protector attempts to protect against stack buffer overflows. It causes the compiler to insert a check for stack buffer overflows before function returns. If an attempt is made to exploit a previously unfixed (and probably undiscovered) error that exposes a buffer overflow vulnerability, the application will be killed immediately. This reduces any potential exploit to a denial-of-service. +</p> + +<p> +Normally the compiler must be explicitly directed to switch on the stack protection via compiler options. The Gentoo hardened GCC switches on the stack protector by default unless explicitly requested not to. The chapter "<uri link="#SSP">The Stack Smashing Protector</uri>" describes the toolchain modifications to make this happen, and issues that may arise. +</p> + +</body> +</section> + +<section id="PIEintro"> +<title>Automatic generation of Position Independent Executables (PIEs)</title> +<body> + +<p> +Standard executables have a fixed base address, and they must be loaded to this address otherwise they will not execute correctly. Position Independent Executables can be loaded anywhere in memory much like shared libraries, allowing <uri link="/proj/en/hardened/pax-quickstart.xml">PaX</uri>'s Address Space Layout Randomisation (ASLR) to take effect. This is achieved by building the code to be position-independent, and linking them as ELF shared objects. +</p> + +<p> +In 2003 Hardened Gentoo introduced an approach referred to as '-y etdyn' which consisted of building all code with -fPIC, and modifying the link stage to provide an ET_DYN executable using a modified PIC version of crt1.o, and setting the interp header to cause the executable to be loaded by the loader from glibc. ET_DYN versions of the crt1.o object were created for x86, parisc, ppc and sparc. +</p> + +<p> +Further work was undertaken by RedHat, who implemented a '-pie' switch for the linker, and '-fPIE' to be used when compiling objects for linking into a Position Independent Executable. Building an object with -fPIE is slightly different from -fPIC; in particular not all symbols are vectored through the GOT which means pre-loaded shared libraries do not override these symbols in the executable, which is also the case for ET_EXEC executables. +</p> + +<p> +As the support for PIEs in the upstream toolchain matured, Hardened Gentoo switched to PIE, dropping the earlier "-y et_dyn" support. PIEs have several advantages, not least of which is that upstream have taken on the burden of support in gcc, glibc and binutils. +</p> + +<p> +The Gentoo hardened GCC automatically builds PIEs when building application code, unless explicitly requested not to (with a few built-in exceptions for cases where it is undesirable). The chapter "<uri link="#PIE">Position Independent Executables</uri> describes the toolchain modifications to make this happen, and issues that may arise. +</p> + +</body> +</section> + +<section id="RELROintro"> +<title>Default to marking read-only, sections that can be so marked after the loader is finished (RELRO)</title> +<body> + +<p> +There are several sections that need to be writable by the loader before the application starts, but do not need to be writable by the application itself later. Setting relro instructs the linker to record which sections this applies to, and the loader will mark them read-only before passing or returning execution control to the application. Typical sections affected include .ctors, .dtors, .jcr, .dynamic and .got, although the exact list varies according to arch. If <uri link="#NOWintro">BIND_NOW</uri> is also set then on some arches all of the GOT (i.e. including the PLT) can be set read-only in this way, preventing various attack methods that involve overwriting it. +</p> + +<p> +The Gentoo hardened GCC automatically sets the linker to set RELRO, unless explicitly requested not to. The chapter "<uri link="#RELRO">Read-Only Relocation tables</uri>" describes the toolchain modifications to make this happen. +</p> + +</body> +</section> + +<section id="NOWintro"> +<title>Default full binding at load-time (BIND_NOW)</title> +<body> + +<p> +To reduce the time between starting an application and actually being able to use it, most software is built with "lazy binding". This means that references to functions in shared libraries are resolved when they are actually used for the first time, rather than when the application is loaded. The hardened toolchain changes this behaviour so that by default it will set the "BIND_NOW" flag, which causes the loader to sort out all of these links before starting execution. It improves the effectiveness of <uri link="#RELROintro">RELRO</uri>. +</p> + +<p> +The Gentoo hardened GCC automatically sets the linker to set the BIND_NOW flag, unless explicitly requested not to. The chapter "<uri link="#NOW">Binding policy NOW</uri>" describes the toolchain modifications to make this happen. +</p> + +</body> +</section> +</chapter> + + +<chapter id="SSP"> +<title>The Stack Smashing Protector (SSP)</title> + +<section id="SSPrationale"> +<title>Rationale for enabling the stack smashing protector globally</title> +<body> + +<p> +The stack smashing protector arranges the code so that a stack overflow is very likely to be detected by the application, which then aborts. This means that an attacker who tries to exploit such a stack overflow error can cause the application to die, but cannot exploit the error to execute code. So the threat is reduced from a privilege elevation to at most a denial of service. Obviously, any such errors in the code should be fixed - SSP is not an excuse to avoid fixing them - however it is extremely difficult to be confident no such errors remain, even after thorough code review and testing. So SSP remains as a safety-net for unfixed stack overflow errors. +</p> +<p> +This is an important part of the overall Hardened Toolchain/PaX/GRsecurity strategy. PaX prevents stack overflows from being executable by making the stack non-executable so an attacker cannot just put his shellcode into a buffer that overflows - however it does not prevent attacks that alter data that affect the program flow; in particular attacks that modify return addresses on the stack. +</p> + +</body> +</section> + +<section id="SSPtoolchain"> +<title>Toolchain modifications for default SSP</title> +<body> + +<p> +At Gentoo we add stack smashing protection patches to the GCC-3.x series compilers and the C library (glibc-2.3.x and uclibc). As such this is the most invasive action taken to harden the toolchain. From gcc-4.1 and glibc-2.4 onwards a different implementation of SSP is provided by the upstream GNU toolchain; glibc-2.4 is also patched by Gentoo to support the GCC-3.x implementation of SSP so binaries built with either SSP implementation will work. +</p> + +<p> +The patches to GCC-3.x are not trivial, so a detailed explanation here is not suitable, even if we could write one. The modifications to the C library are simpler; they provide the canary value which is randomised separately for every process (and separately for every thread in the gcc-4.x/glibc-2.4 implementation), and the handler function called when the canary is checked and found to be corrupt. The handler function reports an error and shuts down the process; this has to be done very carefully to ensure the handler itself cannot be exploited. +</p> + +</body> +</section> + +<section id="SSPissues"> +<title>Issues arising from default SSP</title> +<body> + +<p> +The SSP implementation in gcc-3.x is not perfect, and can cause problems. In particular C++ code can be built incorrectly when SSP is enabled, although the exact details are not clear at the moment. +</p> +<p> +The SSP implementation in gcc-4.x is completely different, even so far as changing the semantics of the compiler switches. At the time of writing, we have little experience in the SSP implementation in gcc-4.x. +</p> + +</body> +</section> +</chapter> + + +<chapter id="PIE"> +<title>Position Independent Executables (PIEs)</title> + +<section id="PIErationale"> +<title>Rationale for building Position Indepedent Executables (PIEs)</title> +<body> + +<p> +The reason for building applications as position-independent is to allow the application to be loaded at a random address; normally the kernel loads all executables to the same fixed address. Randomising this address makes it harder for an attacker to exploit the executable, since it is harder to know where the code (and heap) reside. +</p> +<p> +This is most effective when running a PaX kernel with Address Space Layout Randomisation (ASLR), which increases the randomness of the various parts of a process significantly. It is also necessary to enable the GRsecurity option to hide the location information in the /proc filesystem - otherwise the attacker can just look there to find the addresses needed! +</p> +<p> +A note on prelink: prelinking sets hints for the address at which an ELF file will be loaded. These hints, if followed, would make ASLR ineffective. The PaX kernel causes these hints to be ignored, so prelinking does nothing useful for a Gentoo Hardened system. Since there is no point using prelink, just don't use it. +</p> +<p> +Not using prelink also means you don't have to worry about knock-on effects of prelink. Since prelink modifies the ELF files whenever it prelink is run, these changes need to be propogated to other systems that depend on them. For example host-based Intrusion Detection Systems (IDS) watch for changes to executables and libraries and need to be informed of the changes prelink makes - if prelink is not used then maintenance of such systems is simplified. +</p> +<p> +There are some technologies on the way which reduce the need for prelink. These include: +</p> +<ul><li>Symbol visibility support, which when used properly, reduces dramatically the number of symbols to resolve and hence the amount of time taken to resolve them</li> +<li>Hash tables, which will be generated by the linker and included as a extra section in the ELF file, which make looking up symbols to resolve them nearly free.</li> +<li>Direct binding, which simplifies the search that the loader by incorporating information in each library detailing exactly where the symbol to be resolved is located.</li> +</ul> +<p> +See <uri link="#NOWissues">Issues arising from BIND_NOW</uri> for more. +</p> +</body> +</section> + +<section id="PIEtoolchain"> +<title>Toolchain modifications for automatic PIEs</title> +<body> + +<p> +Support for position-independent executables is provided by the standard GNU toolchain. For PIEs, GCC has different versions of some of the compiler support objects so that for example instead of using crtbegin.o, crt1.o and crtend.o it uses crtbeginS.o, Scrt1.o and crtendS.o (the exact files vary according to the compiler target). It also builds code in a similar fashion to library PIC code, although in the case of executables some symbols are not referenced via the Global Offset Table (GOT). The compiler obtains the list of compiler support objects via the "specs" file - see "info gcc" section 3 (Invoking GCC) subsection 15 (Spec Files). Building code for PIEs is achieved by adding '-fPIE' when compiling and '-fPIE -pie' when linking. +</p> +<p> +To change the default for building executables from absolute to position-independent, it is necessary to change the selection of support objects and to set the -fPIE and -pie options appropriately. The specs rules for this are startfile, endfile, cc1 and link_command. Exact details of the modifications vary according to the target; to illustrate here are the changes for x86: +</p> +<pre caption="standard cc1 rule for x86"> +%(cc1_cpu) %{profile:-p} +</pre> +<pre caption="addition to cc1 rule for x86"> +%{!D__KERNEL__: %{!static: %{!fno-PIC: %{!fno-pic: %{!shared: +%{!nostdlib: %{!nostartfiles: %{!fno-PIE: %{!fno-pie: %{!nopie: +%{!fPIC: %{!fpic:-fPIE} } } } } } } } } } } } +</pre> +<p> +This looks a lot more scary than it really is. All it says is that unless one or more of the listed options are specified, add -fPIE to the compilation. The kernel defines __KERNEL__ on all its compilations, so the -D__KERNEL__ check ensures that -fPIE is not added when building the kernel; the kernel is a static executable but as <uri link="#PIEissues">explained below</uri> this is not so easy to detect. When building shared libraries, either -fPIC or -fpic should be specified, so this is used to prevent adding -fPIE when building shared libraries. The -fno-* checks are to ensure that if a build explicitly requests no position-indepedent code, -fPIE is not added. +</p> +<pre caption="standard link_command rule for x86"> +%{!fsyntax-only:%{!c:%{!M:%{!MM:%{!E:%{!S: %(linker) %l +%{pie: -pie} %X %{o*} %{A} %{d} %{e*} %{m} %{N} %{n} %{r} +%{s} %{t} %{u*} %{x} %{z} %{Z} %{!A:%{!nostdlib:%{!nostartfiles:%S}}} +%{static:} %{L*} %(link_libgcc) %o %{fprofile-arcs|fprofile-generate:-lgcov} +%{!symbolic:%{!shared:%{fbounds-checking:libboundscheck.a%s}}} +%{!symbolic:%{!shared:%{fbc-strings-only:libboundscheck.a%s}}} +%{!nostdlib:%{!nodefaultlibs:%(link_gcc_c_sequence)}} +%{!A:%{!nostdlib:%{!nostartfiles:%E}}} %{T*} }}}}}} +</pre> +<pre caption="replacement for %{pie: -pie} in link_command rule for x86"> +%{!nopie: %{!static: %{!A: %{!shared: %{!nostdlib: %{!nostartfiles: +%{!fno-PIE: %{!fno-pie: -pie} } } } } } } } %{pie: -pie} +</pre> +<p> +As with the cc1 rule, the addition causes -pie to be set for link commands unless one of the listed options are specified. Note that this replaces the '%{pie: -pie}' section in the original link_command rule. +</p> +<p> +In both rules, there is an additional condition '!nopie' - this provides a mechanism to stop the hardened compiler defaulting to PIE by adding '-nopie' to CFLAGS. This is what filter-flags does when asked to filter -fPIE and the compiler is hardened. +</p> + +</body> +</section> + +<section id="PIEissues"> +<title>Issues with PIEs</title> +<body> + +<p> +Ideally, when building a static executable, a shared library, or building without the standard gcc system files, PIE would not be automatically enabled. Unfortunately, the options -static, -shared, -nostdlib and -nostartfiles are link options, so are usually only supplied to the link command of an executable and not to the compilation commands for individual objects. In these cases, -fPIE will be added to the compilation commands when in fact it shouldn't be. This is an unavoidable limitation, since it is impossible to know from a compilation command for an object exactly what the link command is going to be. Indeed in some cases more than one link command can happen using the same objects. Such cases have to be handled by the relevant ebuild on a case-by-case basis. The -nostdlib and -nostartfiles options occur rarely. The -shared option is usually used when the compilation commands have been performed with -fPIC, so the majority of such cases are not a problem. +</p> +<p> +Where an application builds libraries without -fPIC, it is necessary to modify the build process to avoid -fPIE being added by the compiler. For packages that build only libraries, it is sufficient to do: +</p> +<pre caption="switch off automatic PIE for library ebuilds"> +inherit flag-o-matic +... +src_compile() { +... +filter-flags -fPIE +... +} +</pre> +<p> +However if an ebuild creates both executables and libraries then more detailed modifications need to be made, to add the -fno-PIE to the compilation of objects destined for the libraries. Where an object is used for both a shared library and an executable, it is necessary to modify the build process significantly in order to obtain two objects, one built -fPIC and one built -fPIE for linking to the library and the executable respectively. Most packages that provide both a shared library and a static archive do so by using libtool which does the right thing automatically. Both of these approaches can be taken unconditionally; i.e. it is not necessary to make such changes conditional on the presence of the hardened compiler. +</p> +<p> +Occasionally application code will fail to compile with -fPIE. If this happens it is usually down to non-position-independent assembler code, and is most prevelant on X86 which has a limited general purpose register set. However this is rare in application code as normally application authors push most of their code into shared libraries, although it does happen. Most position-independent build problems occur in shared libraries which are not built position-independent - this is a problem regardless of Hardened, and is nothing to do with PIE; it is just that the issue is highlighted by the hardened compiler due to the automatic enabling of -fPIE when -fPIC is not specified as described above. See the <uri link="/proj/en/hardened/pic-fix-guide.xml">PIC fixing guide</uri> for information on how to fix this sort of problem. +</p> +<p> +Some applications have been reported to segfault when built as PIEs. Exactly why this occurs is unclear, but it is likely due to a compiler bug so later compiler versions may resolve such problems. +</p> +<p> +Debugging PIEs at the time of writing only works with sys-devel/gdb-6.3-r5, which includes patches by Elena Zannoni at RedHat. These patches were not included in the main trunk of gdb, so have not been maintained in later versions. +</p> + +</body> +</section> +</chapter> + + +<chapter id="RELRO"> +<title>Mark Read-Only Appropriate Sections</title> + +<section id="RELROrationale"> +<title>Rationale for enabling RELRO globally</title> +<body> + +<p> +Various sections in an ELF file should be written only by the loader, and not by the application. However in normal circumstances these sections remain read/write throughout the life of the process, and there are attack methods that exploit this to affect program execution flow. Enabling RELRO causes the linker to include an extra header informing the loader which sections can be marked read-only after the loader has finished with them. It also affects the layout of sections slightly, to avoid having RELRO sections and read-write sections on the same memory page. Combining RELRO with BIND_NOW allows also the PLT to be managed this way on some arches. +</p> + +</body> +</section> + +<section id="RELROauto"> +<title>Toolchain modifications for default RELRO</title> +<body> + +<p> +RELRO is a link option ("-z relro") provided by the standard GNU toolchain. To switch it on by default, it is simply a matter of adding a small rule to the specs file for GCC as illustrated below: +</p> +<pre caption="standard link_command rule for x86"> +%{!fsyntax-only:%{!c:%{!M:%{!MM:%{!E:%{!S: %(linker) %l +%{pie: -pie} %X %{o*} %{A} %{d} %{e*} %{m} %{N} %{n} %{r} +%{s} %{t} %{u*} %{x} %{z} %{Z} %{!A:%{!nostdlib:%{!nostartfiles:%S}}} +%{static:} %{L*} %(link_libgcc) %o %{fprofile-arcs|fprofile-generate:-lgcov} +%{!symbolic:%{!shared:%{fbounds-checking:libboundscheck.a%s}}} +%{!symbolic:%{!shared:%{fbc-strings-only:libboundscheck.a%s}}} +%{!nostdlib:%{!nodefaultlibs:%(link_gcc_c_sequence)}} +%{!A:%{!nostdlib:%{!nostartfiles:%E}}} %{T*} }}}}}} +</pre> +<pre caption="additionl segment to follow %{pie: -pie} in link_command rule for x86"> +%{!norelro: -z relro} %{relro: } +</pre> +<p> +So a new option is introduced, "norelro", which can be used to prevent the hardened compiler from automatically switching on RELRO. However this is likely to be phased out, as newer binutils provide a "-z norelro" option which can be appended to LDFLAGS as "-Wl,z,norelro". +</p> + +</body> +</section> + +<section id="RELROissues"> +<title>Issues arising from default RELRO</title> +<body> + +<p> +So far, the hardened project has found no issues with switching on RELRO by default. It can make the executable image a little bit bigger (on average by half a page i.e. 2K bytes) which may be of interest for targets with extremely limited memory. +</p> + +</body> +</section> +</chapter> + + +<chapter id="NOW"> +<title>Binding policy NOW</title> + +<section id="NOWrationale"> +<title>Rationale for enabling NOW binding globally</title> +<body> + +<p> +As described in the <uri link="#RELRO">RELRO</uri> chapter, setting BIND_NOW increases the effectiveness of setting RELRO, making attacks that involve overwriting data in the Global Offset Table (GOT) fail. +</p> + +</body> +</section> + +<section id="NOWauto"> +<title>Toolchain modifications for default NOW</title> +<body> + +<p> +NOW binding is a link option ("-z now") provided by the standard GNU toolchain. To switch it on by default, it is simply a matter of adding a small rule to the specs file for GCC as illustrated below: +</p> +<pre caption="standard link_command rule for x86"> +%{!fsyntax-only:%{!c:%{!M:%{!MM:%{!E:%{!S: %(linker) %l +%{pie: -pie} %X %{o*} %{A} %{d} %{e*} %{m} %{N} %{n} %{r} +%{s} %{t} %{u*} %{x} %{z} %{Z} %{!A:%{!nostdlib:%{!nostartfiles:%S}}} +%{static:} %{L*} %(link_libgcc) %o %{fprofile-arcs|fprofile-generate:-lgcov} +%{!symbolic:%{!shared:%{fbounds-checking:libboundscheck.a%s}}} +%{!symbolic:%{!shared:%{fbc-strings-only:libboundscheck.a%s}}} +%{!nostdlib:%{!nodefaultlibs:%(link_gcc_c_sequence)}} +%{!A:%{!nostdlib:%{!nostartfiles:%E}}} %{T*} }}}}}} +</pre> +<pre caption="additionl segment to follow %{pie: -pie} in link_command rule for x86"> +%{!nonow: -z now} %{now: } +</pre> +<p> +So a new option is introduced, "nonow", which can be used to prevent the hardened compiler from automatically switching on NOW binding. However this is likely to be phased out, as newer binutils provide a "-z lazy" option which can be appended to LDFLAGS as "-Wl,z,lazy". +</p> + +</body> +</section> + +<section id="NOWissues"> +<title>Issues arising from default NOW</title> +<body> + +<p> +NOW binding has several noticeable effects. The first is that initial loading time for applications increases, sometimes very noticeably, as the loader resolves all the references before passing execution to the loaded process. +</p> +<p> +One technology that could reduce this overhead significantly is the introduction of "Direct Binding", something that exists on Unix systems (e.g. Solaris) but does not exist in the GNU toolchain. Direct binding adds information to libraries when they are built, to tell the linker which library contains the symbol it is looking for. Normally the linker performs a search across all referenced libraries to find symbols, which adds significantly to the time taken to resolve them. However the implications of direct-binding are significant, and cannot be taken lightly. Michael Meeks at Novell is working on this; see our <uri link="http://bugs.gentoo.org/114008">bug #114008</uri> for our status on this. +</p> +<p> +Other technologies which should help are symbol visibility and hash tables in the ELF files. Both are technologies supported upstream, so when they appear they will be supported directly. With these two together, it is likely that there will not be much further benefit from direct binding and the complications that arise from direct binding may mean it won't be supported. +</p> +<p> +The second more serious effect is that applications that are not written to refer to shared libraries in the standard way can fail; the most obvious of these is X, which has modules with circular resolution dependencies amongst other unusual behaviour. Another trick occasionally performed by applications is to decide between a number of shared libraries at run time, and use lazy binding to resolve references to the chosen library. Normally this would be done with dlopen(3) and friends, including obtaining symbol addresses via dlsym(3), but it is possible to avoid using dlsym(3) and a plethora of pointers in the code by using lazy binding, although it's not pretty. +</p> +<p> +The following packages have issues with BIND_NOW at the time of writing, and it has to be relaxed somewhat for them: +</p> +<ul> +<li>X - some drivers consist of several libraries which are co-dependent, and the modules frequently have references to modules that they load.</li> +<li>transcode - relies on lazy binding to be able to load its modules; the issues are similar to the X issues.</li> +</ul> + +</body> +</section> +</chapter> + + +<chapter id="references"> +<title>References</title> + +<section id="gentoorefs"> +<title>Other Gentoo Documentation</title> +<body> + +<ul> +<li><uri link="/proj/en/hardened/pax-quickstart.xml">PaX QuickStart</uri></li> +<li><uri link="/proj/en/hardened/pic-guide.xml">Introduction to Position-Independent Code (PIC)</uri></li> +<li><uri link="/proj/en/hardened/pic-fix-guide.xml">Guide to fixing non-PIC shared libraries</uri></li> +</ul> + +</body> +</section> + +<section id="externalrefs"> +<title>External Documentation</title> +<body> + +<ul> +<li><uri link="http://people.redhat.com/drepper/dsohowto.pdf">How to Write Shared Libraries</uri> by Ulrich Drepper (PDF)</li> +</ul> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/hardenedxorg.xml b/xml/hardenedxorg.xml new file mode 100644 index 0000000..74852cc --- /dev/null +++ b/xml/hardenedxorg.xml @@ -0,0 +1,186 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/hardenedxorg.xml,v 1.11 2006/12/23 13:03:11 phreak Exp $ --> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="hardenedxorg.xml"> +<title>Using Xorg on Hardened Gentoo</title> +<author title="Author"> + <mail link="tocharian@gentoo.org">Adam Mondl</mail> +</author> +<author title="Contributor"> + <mail link="kevquinn@gentoo.org">Kevin Quinn</mail> +</author> +<author title="Contributor"> + <mail link="solar@gentoo.org">Ned Ludd</mail> +</author> +<author title="Contributor"> + <mail link="phreak@gentoo.org">Christian Heim</mail> +</author> +<author title="Contributor"> + <mail link="zaid_a@users.sourceforge.net">Zaid A.</mail> +</author> + +<abstract> +How to install and use Xorg on Hardened Gentoo +</abstract> + +<version>1.6</version> +<date>2006-12-23</date> + +<chapter> +<title>Background</title> +<section> +<title>What is different about running Xorg with Hardened Gentoo?</title> +<body> + +<p> +PaX, a patch for the Linux kernel, is a central part of the Hardened Gentoo +project. PaX provides various functionality such as ASLR and NX memory. More +information is available at <uri>http://www.gentoo.org/proj/en/hardened/docs/pax-howto.xml</uri> +For the purposes of this document, it will be assumed that the reader has a general +understanding of how PaX works as well as the concept of Position Independent Executables (PIE). +</p> + +<p> +The specific feature of PaX of interest in this article is MPROTECT, which +guards against executable code in a program's address space. One of the main features +of Hardened Gentoo is the ability to run PaX effectively because of the ET_DYN/PIE base. +The eventual goal for Xorg is to have the binary itself built as ET_DYN/PIE to remove text +relocations from it and randomize the base address without the EX_EXEC performance hit. +</p> + +<p> +At this point, compiling Xorg with PIC code sounds like an obvious, logical choice. Hardened +Gentoo offers hardened gcc for this purpose, which provides transparent PIE/SSP compiling. This +is where you begin to run into problems with Xorg. Xorg currently uses elfloader to handle loading +the modules it needs, however elfloader is unable to resolve various types of relocatable symbols that are +always generated by PIC code. Most importantly, the elfloader has no support for Global Offset +Table (GOT) or Procedure Linkage Table (PLT) type symbols which are both essential for shared libraries. +</p> + +<p> +So if elfloader won't work then what will? Luckily there is already a fully operational, well tested, +mature dynamic loader installed on your system. It is ld-linux.so which is provided by glibc. The obvious idea +that occurs at this point, is that ideally there would be a programmatic interface to the glibc loader, and the +X loader could be modified to use that instead of home-brewing its own loader. Turns out that such an interface +exists - dlopen(3) et. al. - and this is exactly what the dlloader uses. +</p> + +<note>Starting with Xorg 7.0, dlloader is the default module loader for X.</note> + +</body> +</section> +</chapter> + +<chapter> +<title>Kernel Configuration options</title> +<section> +<title>CONFIG_PAX_KERNEXEC</title> +<body> + +<p> +The option 'CONFIG_PAX_KERNEXEC' is the kernel land equivalent of PAGEEXEC and MPROTECT. By enabling this option, it will get +harder to inject and execute 'foreign' code in kernel memory itself. This option may also give you some strange experiences on +a hardened Xorg setup (being the Mouse pointer being stuck on the left side of the screen). +Suggestion therefore is, to turn this option off by deselecting it in your config. +</p> + +</body> +</section> + +<section> +<title>CONFIG_GRKERNSEC_IO</title> +<body> + +<p> +Enabling this option will result in all ioperm(2) and iopl(2) calls returning an error messge. ioperm(2) and iopl(2) might be +used to modify the running kernel. As you wish to run a Xorg server on top of your hardened kernel (mostly GRsecurity), you'll +have to disable this config option, in order to get the XServer up and running. +</p> + +</body> +</section> + +</chapter> + +<chapter> +<title>Installation</title> +<section> +<title>Current Install Options</title> +<body> + +<p> +Since Xorg 7.0 and up uses the dlloader instead of the elfloader by default, there is no need to do anything special to get Xorg +compiling and working on a hardened profile. +</p> + +</body> +</section> + +</chapter> + +<chapter> +<title>Configuration</title> +<section> +<title>/etc/X11/xorg.conf</title> +<body> + +<p> +You can setup your Xorg configuration file using The X Server +Configuration HOWTO found at: +<uri>http://www.gentoo.org/doc/en/xorg-config.xml</uri> +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Known Issues</title> +<section> +<title>The dlloader Experiences</title> +<body> + +<p> +Hardened Gentoo makes the default link strategy to resolve all symbols at load time, and enforces +this on all shared libraries when they are built. Normally the loader uses "lazy" resolution if requested, +whereby symbols are resolved as and when they are used. Unfortunately some Xorg modules have mutual +dependencies and other issues that mean they cannot load unless lazy symbol resolution is enabled. To work +around this issue, currently Gentoo compiles the Xorg modules and the server itself with the -nonow gcc flag. +This fixes the "dlopen: undefined symbol" errors so previous methods of manually detecting and loading modules are +no longer needed. +</p> + +<impo> +Please report all issues to bugs.gentoo.org with full attached +logs and configs. +</impo> + +</body> +</section> + +<section> +<title>Binary Drivers</title> +<body> + +<p> +Binary drivers are currently not supported on the hardened profile and you are encouraged to use the +opensource drivers instead. +</p> + +</body> +</section> + +<section> +<title>PaX Flags</title> +<body> + +<p> +The PaX flags -P (PAGEEXEC), -S (SEGMEXEC), -M (MPROTECT) as well as -R (RANDMMAP) now work with Xorg. +</p> + +</body> +</section> + +</chapter> +</guide> diff --git a/xml/index2.xml b/xml/index2.xml new file mode 100644 index 0000000..cd0b6fc --- /dev/null +++ b/xml/index2.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?> +<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> +<!DOCTYPE project SYSTEM "/dtd/project.dtd"> +<project> +<name>hardened</name> +<longname>Hardened Gentoo</longname> +<date>2010-10-25</date> + +<description> +Hardened Gentoo brings advanced security measures to Gentoo Linux. +</description> + +<longdescription> +<p> +Hardened Gentoo is a project which oversees the research, implementation, and +maintenance of security oriented projects for Gentoo Linux. We are a team of +very competent individuals dedicated to bringing advanced security to Gentoo +with a number of subprojects. +</p> + +</longdescription> + +<goals> +<p> +Hardened Gentoo's purpose is to make Gentoo viable for high security, high +stability production server environments. This project is not a standalone +project separated from the rest of Gentoo. Instead, it is intended to be a team +of Gentoo developers which are focused on delivering solutions to Gentoo that +provide strong security and stability. These solutions will be available in +Gentoo once they've been tested for security and stability by the Hardened team. +</p> + +</goals> + +<dev role="Member" description="Bastille Lead">battousai</dev> +<dev role="Member" description="PaX/Grsecurity, Hardened sources">gengor</dev> +<dev role="Project Lead" description="Hardened Toolchain, Doc">Zorry</dev> +<dev role="Member" description="PaX/Grsecurity, Hardened sources">blueness</dev> +<dev role="Member" description="Hardened sources, Doc">quantumsummers</dev> +<dev role="Member" description="Hardened sources">Chainsaw</dev> +<dev role="Member" description="PPC arch team liaison">nixnut</dev> +<!--<dev role="Member" description="SELinux">pebenito</dev>--> + +<!-- In the future we could use inheritmembers="yes" but we need pages for all +or most of the subprojects --> +<subproject ref="/proj/en/hardened/selinux/index.xml" inheritresources="yes" +inheritmembers="yes"/> +<!-- RSBAC is no longer with us :( +<subproject ref="/proj/en/hardened/rsbac/index.xml" inheritresources="yes" /> +--> +<extraproject name="PaX/Grsecurity" lead="blueness"> +Grsecurity is a complete security solution providing such features as a MAC or +RBAC system, Chroot restrictions, address space modification protection (via +PaX), auditing features, randomization features, linking restrictions to prevent +file race conditions, ipc protections and much more. +</extraproject> + +<extraproject name="Hardened Toolchain" lead="Zorry"> +Transparent implementation of +<uri link="http://pax.grsecurity.net/docs/aslr.txt">PaX</uri> address space +layout randomizations and stack smashing protections using ELF shared objects as +executables. +</extraproject> + +<extraproject name="Hardened-Sources" lead="blueness"> +A kernel which provides patches for hardened subprojects, and stability/security +oriented patches. Includes Grsecurity and SELinux. +</extraproject> + +<extraproject name="Bastille" lead="battousai"> +Bastille is an interactive application which gives the user suggestions on +securing their machine. It will be customized to make suggestions about other +Hardened Gentoo subprojects. +</extraproject> + +<!-- Still rewieving it. +<plannedproject name="Security Documentation">Maintain +documentation about best practices, and general security measures +such as process limiting, setting quotas, securing systems with +kerberos, chrooting, tightening services, etc.</plannedproject> +--> + +<resource link="http://www.gentoo.org/proj/en/hardened/primer.xml"> +Introduction to Hardened Gentoo</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/hardenedfaq.xml"> +Hardened Frequently Asked Questions</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/roadmap.xml"> +Hardened Roadmap</resource> +<!-- This is WIP will apppear when it's done. +<resource link="http://www.gentoo.org/proj/en/hardened/?.xml">Hardened Debuging +</resource>--> +<resource link="http://www.gentoo.org/proj/en/hardened/hardenedxorg.xml"> +Using Xorg with Hardened</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/hardened-toolchain.xml"> +Hardened Toolchain Technical Description</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/pax-quickstart.xml"> +A quickstart covering PaX and Hardened Gentoo</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/pax-utils.xml"> +PaX Utils</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/grsecurity.xml"> +Grsecurity2 QuickStart Guide</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/capabilities.xml"> +Capabilities Listing</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/pic-guide.xml"> +PIC Intro (beginner)</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/pic-internals.xml"> +PIC Internals (intermediate)</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/pic-fix-guide.xml"> +PIC Fixing (advanced)</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/gnu-stack.xml"> +GNU Stack Quickstart</resource> + +<herd name="hardened" /> + +<extrachapter position="bottom"> +<title>I Want to Participate</title> +<section> +<body> + +<p> +To participate in the Hardened Gentoo project first join the mailing list at +<c><mail link="gentoo-hardened@lists.gentoo.org"> +gentoo-hardened@lists.gentoo.org</mail></c>. Then ask if there are plans to +support something that you are interested in, propose a new subproject that you +are interested in, choose one of the planned subprojects to work on or simply +ask if you can help with something. You can also talk to the developers and +users in the IRC channel <c>#gentoo-hardened</c> on <c>irc.freenode.net</c> for +more information or just to chat about the project or any subprojects. +</p> + +<p> +If you think you don't have the knowledge or abilities to help, then try reading +the current documents (there are always sections that can be improved or typos +which we miss) and when you feel brave enough then try writing those documents +you missed. Usually this only requires some internet research on your side and +after some documents you'll most probably be able to help with other things you +though you weren't able before. +</p> + +<p> +Also, if you don't have time to actively help by contributing work we will +always need testers to maintain the security and stability of the overall +product. All development, testing, and productive comments and feedback will be +greatly appreciated. +</p> + +</body> +</section> +</extrachapter> +</project> diff --git a/xml/link.5.html b/xml/link.5.html new file mode 100644 index 0000000..b5b499c --- /dev/null +++ b/xml/link.5.html @@ -0,0 +1,449 @@ +<html> +<head><title>link(5) man page</title></head> +<body> +<pre> +LINK(5) BSD File Formats Manual LINK(5) + +NAME + link -- dynamic loader and link editor interface + +SYNOPSIS + #include <link.h> + +DESCRIPTION + The include file <link.h> declares several structures that are present in + dynamically linked programs and libraries. The structures define the + interface between several components of the link-editor and loader mecha- + nism. The layout of a number of these structures within the binaries + resembles the a.out(5) format in many places as it serves such similar + functions as symbol definitions (including the accompanying string table) + and relocation records needed to resolve references to external entities. + + It also records a number of data structures unique to the dynamic loading + and linking process. These include references to other objects that are + required to complete the link-editing process and indirection tables to + facilitate Position Independent Code (PIC) to improve sharing of code + pages among different processes. + + The collection of data structures described here will be referred to as + the Run-time Relocation Section (RRS) and is embedded in the standard + text and data segments of the dynamically linked program or shared object + image as the existing a.out(5) format offers no room for it elsewhere. + + Several utilities cooperate to ensure that the task of getting a program + ready to run can complete successfully in a way that optimizes the use of + system resources. The compiler emits PIC code from which shared + libraries can be built by ld(1). The compiler also includes size infor- + mation of any initialized data items through the .size assembler direc- + tive. + + PIC code differs from conventional code in that it accesses data vari- + ables through an indirection table, the Global Offset Table, by conven- + tion accessible by the reserved name _GLOBAL_OFFSET_TABLE_. The exact + mechanism used for this is machine dependent, usually a machine register + is reserved for the purpose. The rational behind this construct is to + generate code that is independent of the actual load address. Only the + values contained in the Global Offset Table may need updating at run-time + depending on the load addresses of the various shared objects in the + address space. + + Likewise, procedure calls to globally defined functions are redirected + through the Procedure Linkage Table (PLT) residing in the data segment of + the core image. Again, this is done to avoid run-time modifications to + the text segment. + + The linker-editor allocates the Global Offset Table and Procedure Linkage + Table when combining PIC object files into an image suitable for mapping + into the process address space. It also collects all symbols that may be + needed by the run-time link-editor and stores these along with the + image's text and data bits. Another reserved symbol, _DYNAMIC is used to + indicate the presence of the run-time linker structures. Whenever + _DYNAMIC is relocated to 0, there is no need to invoke the run-time link- + editor. If this symbol is non-zero, it points at a data structure from + which the location of the necessary relocation- and symbol information + can be derived. This is most notably used by the start-up module, crt0. + The _DYNAMIC structure is conventionally located at the start of the data + segment of the image to which it pertains. + +DATA STRUCTURES + The data structures supporting dynamic linking and run-time relocation + reside both in the text and data segments of the image they apply to. + The text segments contain read-only data such as symbols descriptions and + names, while the data segments contain the tables that need to be modi- + fied by during the relocation process. + + The _DYNAMIC symbol references a _dynamic structure: + + struct _dynamic { + int d_version; + struct so_debug *d_debug; + union { + struct section_dispatch_table *d_sdt; + } d_un; + struct ld_entry *d_entry; + }; + + d_version This field provides for different versions of the dynamic + linking implementation. The current version numbers under- + stood by ld and ld.so are LD_VERSION_SUN (3), which is used by + the SunOS 4.x releases, and LD_VERSION_BSD (8), which is cur- + rently in use by NetBSD. + + d_un Refers to a d_version dependent data structure. + + d_debug this field provides debuggers with a hook to access symbol + tables of shared objects loaded as a result of the actions of + the run-time link-editor. + + d_entry this field is obsoleted by CRT interface version CRT_VER- + SION_BSD4, and is replaced by the crt_ldentry in crt_ldso. + + The section_dispatch_table structure is the main ``dispatcher'' table, + containing offsets into the image's segments where various symbol and + relocation information is located. + + struct section_dispatch_table { + struct so_map *sdt_loaded; + long sdt_sods; + long sdt_paths; + long sdt_got; + long sdt_plt; + long sdt_rel; + long sdt_hash; + long sdt_nzlist; + long sdt_filler2; + long sdt_buckets; + long sdt_strings; + long sdt_str_sz; + long sdt_text_sz; + long sdt_plt_sz; + }; + + sdt_loaded A pointer to the first link map loaded (see below). This + field is set by ld.so(1) for the benefit of debuggers that + may use it to load a shared object's symbol table. + + sdt_sods The start of a (linked) list of shared object descriptors + needed by this object. + + sdt_paths Library search rules. A colon separated list of directories + corresponding to the -R option of ld(1). + + sdt_got The location of the Global Offset Table within this image. + + sdt_plt The location of the Procedure Linkage Table within this + image. + + sdt_rel The location of an array of relocation_info structures (see + a.out(5)) specifying run-time relocations. + + sdt_hash The location of the hash table for fast symbol lookup in this + object's symbol table. + + sdt_nzlist The location of the symbol table. + + sdt_filler2 + Currently unused. + + sdt_buckets + The number of buckets in sdt_hash + + sdt_strings + The location of the symbol string table that goes with + sdt_nzlist. + + sdt_str_sz The size of the string table. + + sdt_text_sz + The size of the object's text segment. + + sdt_plt_sz The size of the Procedure Linkage Table. + + A sod structure describes a shared object that is needed to complete the + link edit process of the object containing it. A list of such objects + (chained through sod_next) is pointed at by the sdt_sods in the sec- + tion_dispatch_table structure. + + struct sod { + long sod_name; + u_int sod_library : 1, + sod_unused : 31; + short sod_major; + short sod_minor; + long sod_next; + }; + + sod_name The offset in the text segment of a string describing this + link object. + + sod_library If set, sod_name specifies a library that is to be searched + for by ld.so. The path name is obtained by searching a set + of directories (see also ldconfig(8)) for a shared object + matching lib<sod_name>.so.n.m. If not set, sod_name should + point at a full path name for the desired shared object. + + sod_major Specifies the major version number of the shared object to + load. + + sod_minor Specifies the preferred minor version number of the shared + object to load. + + The run-time link-editor maintains a list of structures called link maps + to keep track of all shared objects loaded into a process' address space. + These structures are only used at run-time and do not occur within the + text or data segment of an executable or shared library. + + struct so_map { + caddr_t som_addr; + char *som_path; + struct so_map *som_next; + struct sod *som_sod; + caddr_t som_sodbase; + u_int som_write : 1; + struct _dynamic *som_dynamic; + caddr_t som_spd; + }; + + som_addr The address at which the shared object associated with this + link map has been loaded. + + som_path The full path name of the loaded object. + + som_next Pointer to the next link map. + + som_sod The sod structure that was responsible for loading this + shared object. + + som_sodbase Tossed in later versions the run-time linker. + + som_write Set if (some portion of) this object's text segment is cur- + rently writable. + + som_dynamic Pointer to this object's _dynamic structure. + + som_spd Hook for attaching private data maintained by the run-time + link-editor. + + Symbol description with size. This is simply an nlist structure with one + field (nz_size) added. Used to convey size information on items in the + data segment of shared objects. An array of these lives in the shared + object's text segment and is addressed by the sdt_nzlist field of + section_dispatch_table. + + struct nzlist { + struct nlist nlist; + u_long nz_size; + #define nz_un nlist.n_un + #define nz_strx nlist.n_un.n_strx + #define nz_name nlist.n_un.n_name + #define nz_type nlist.n_type + #define nz_value nlist.n_value + #define nz_desc nlist.n_desc + #define nz_other nlist.n_other + }; + + nlist (see nlist(3)). + + nz_size The size of the data represented by this symbol. + + A hash table is included within the text segment of shared object to + facilitate quick lookup of symbols during run-time link-editing. The + sdt_hash field of the section_dispatch_table structure points at an array + of rrs_hash structures: + + struct rrs_hash { + int rh_symbolnum; /* symbol number */ + int rh_next; /* next hash entry */ + }; + + rh_symbolnum The index of the symbol in the shared object's symbol table + (as given by the ld_symbols field). + + rh_next In case of collisions, this field is the offset of the next + entry in this hash table bucket. It is zero for the last + bucket element. + The rt_symbol structure is used to keep track of run-time allocated com- + mons and data items copied from shared objects. These items are kept on + linked list and is exported through the dd_cc field in the so_debug + structure (see below) for use by debuggers. + + struct rt_symbol { + struct nzlist *rt_sp; + struct rt_symbol *rt_next; + struct rt_symbol *rt_link; + caddr_t rt_srcaddr; + struct so_map *rt_smp; + }; + + rt_sp The symbol description. + + rt_next Virtual address of next rt_symbol. + + rt_link Next in hash bucket. Used by internally by ld.so. + + rt_srcaddr Location of the source of initialized data within a shared + object. + + rt_smp The shared object which is the original source of the data + that this run-time symbol describes. + + The so_debug structure is used by debuggers to gain knowledge of any + shared objects that have been loaded in the process's address space as a + result of run-time link-editing. Since the run-time link-editor runs as + a part of process initialization, a debugger that wishes to access sym- + bols from shared objects can only do so after the link-editor has been + called from crt0. A dynamically linked binary contains a so_debug struc- + ture which can be located by means of the d_debug field in _dynamic. + + struct so_debug { + int dd_version; + int dd_in_debugger; + int dd_sym_loaded; + char *dd_bpt_addr; + int dd_bpt_shadow; + struct rt_symbol *dd_cc; + }; + + dd_version Version number of this interface. + + dd_in_debugger Set by the debugger to indicate to the run-time linker + that the program is run under control of a debugger. + + dd_sym_loaded Set by the run-time linker whenever it adds symbols by + loading shared objects. + + dd_bpt_addr The address were a breakpoint will be set by the run-time + linker to divert control to the debugger. This address + is determined by the start-up module, crt0.o, to be some + convenient place before the call to _main. + + dd_bpt_shadow Contains the original instruction that was at + dd_bpt_addr. The debugger is expected to put this + instruction back before continuing the program. + + dd_cc A pointer to the linked list of run-time allocated sym- + bols that the debugger may be interested in. + + The ld_entry structure defines a set of service routines within ld.so. + See dlfcn(3) for more information. + + struct ld_entry { + void *(*dlopen)(char *, int); + int (*dlclose)(void *); + void *(*dlsym)(void *, char *); + int (*dlctl)(void *, int, void *); + void (*dlexit)(void); + }; + + The crt_ldso structure defines the interface between ld.so and the start- + up code in crt0. + + struct crt_ldso { + int crt_ba; + int crt_dzfd; + int crt_ldfd; + struct _dynamic *crt_dp; + char **crt_ep; + caddr_t crt_bp; + char *crt_prog; + char *crt_ldso; + char *crt_ldentry; + }; + #define CRT_VERSION_SUN 1 + #define CRT_VERSION_BSD2 2 + #define CRT_VERSION_BSD3 3 + #define CRT_VERSION_BSD4 4 + + crt_ba The virtual address at which ld.so was loaded by crt0. + + crt_dzfd On SunOS systems, this field contains an open file descriptor + to ``/dev/zero'' used to get demand paged zeroed pages. On + NetBSD systems it contains -1. + + crt_ldfd Contains an open file descriptor that was used by crt0 to load + ld.so. + + crt_dp A pointer to main's _dynamic structure. + + crt_ep A pointer to the environment strings. + + crt_bp The address at which a breakpoint will be placed by the run- + time linker if the main program is run by a debugger. See + so_debug + + crt_prog The name of the main program as determined by crt0 (CRT_VER- + SION_BSD3 only). + + crt_ldso The path of the run-time linker as mapped by crt0 (CRT_VER- + SION_BSD4 only). + + crt_ldentry + The dlfcn(3) entry points provided by the run-time linker + (CRT_VERSION_BSD4 only). + + The hints_header and hints_bucket structures define the layout of the + library hints, normally found in ``/var/run/ld.so.hints'', which is used + by ld.so to quickly locate the shared object images in the file system. + The organization of the hints file is not unlike that of an a.out(5) + object file, in that it contains a header determining the offset and size + of a table of fixed sized hash buckets and a common string pool. + + struct hints_header { + long hh_magic; + #define HH_MAGIC 011421044151 + long hh_version; + #define LD_HINTS_VERSION_1 1 + #define LD_HINTS_VERSION_2 2 + long hh_hashtab; + long hh_nbucket; + long hh_strtab; + long hh_strtab_sz; + long hh_ehints; + long hh_dirlist; + }; + + hh_magic Hints file magic number. + + hh_version Interface version number. + + hh_hashtab Offset of hash table. + + hh_strtab Offset of string table. + + hh_strtab_sz Size of strings. + + hh_ehints Maximum usable offset in hints file. + + hh_dirlist Offset in string table of a colon-separated list of direc- + tories that was used in constructing the hints file. See + also ldconfig(8). This field is only available with inter- + face version number LD_HINTS_VERSION_2 and higher. + + /* + * Hash table element in hints file. + */ + struct hints_bucket { + int hi_namex; + int hi_pathx; + int hi_dewey[MAXDEWEY]; + int hi_ndewey; + #define hi_major hi_dewey[0] + #define hi_minor hi_dewey[1] + int hi_next; + }; + + hi_namex Index of the string identifying the library. + + hi_pathx Index of the string representing the full path name of the + library. + + hi_dewey The version numbers of the shared library. + + hi_ndewey The number of valid entries in hi_dewey. + + hi_next Next bucket in case of hashing collisions. + +BSD October 23, 1993 BSD +</pre> +</body> +</html> diff --git a/xml/pax-quickstart.xml b/xml/pax-quickstart.xml new file mode 100644 index 0000000..8ad18b6 --- /dev/null +++ b/xml/pax-quickstart.xml @@ -0,0 +1,297 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/pax-quickstart.xml,v 1.12 2007/11/11 17:08:51 solar Exp $ --> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/pax-quickstart.xml"> +<title>Hardened Gentoo PaX Quickstart</title> + +<author title="Author"> + <mail link="tseng@gentoo.org">Brandon Hale</mail> +</author> +<author title="Editor"> + <mail link="blackace@gentoo.org">Blackace</mail> +</author> +<author title="Editor"> + <mail link="solar@gentoo.org">solar</mail> +</author> + +<abstract> +A quickstart covering PaX and Hardened Gentoo. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> +<license/> + +<version>1.4</version> +<date>2007-09-11</date> + +<chapter> +<title>What is Hardened Gentoo?</title> +<section> +<body> + +<p> +Hardened Gentoo is a project interested in the hardening of a Gentoo system. +Several different solutions are supported by us and there is a fair bit of +flexibility to create your own setup. At the heart of a common Hardened Gentoo +setup is <e>PaX</e>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>What is PaX?</title> +<section> +<body> + +<p> +PaX is a patch to the Linux kernel that provides hardening in two ways. +</p> + +<p> +The first, <e>ASLR</e> (Address Space Layout Randomization) provides a means to +randomize the addressing scheme of all data loaded into memory. When an +application is built as a <e>PIE</e> (Position Independent Executable), PaX is +able to also randomize the addresses of the application base in addition. +</p> + +<p> +The second protection provided by PaX is non-executable memory. This prevents a +common form of attack where executable code is inserted into memory by an +attacker. More information on PaX can be found throughout this guide, but the +homepage can be found at <uri>http://pax.grsecurity.net</uri>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>An Introduction to PIE and SSP</title> +<section> +<body> + +<p> +As mentioned above, PaX is complemented by PIE. This method of building +executables stores information needed to relocate parts of the executable in +memory, hence the name <e>Position Independent</e>. +</p> + +<p> +<e>SSP</e> (Stack Smashing Protector) is a second complementary technology we +introduce at executable build time. SSP was originally introduced by IBM under +the name <e>ProPolice</e>. It modifies the C compiler to insert initialization +code into functions that create a buffer in memory. +</p> + +<note> +In newer versions of SSP, it is possible to apply SSP to all functions, +adding protection to functions whose buffer would normally be below the size +limit for SSP. This is enabled via the CFLAG -fstack-protector-all. +</note> + +<p> +At run time, when a buffer is created, SSP adds a secret random value, the +canary, to the end of the buffer. When the function returns, SSP makes sure +that the canary is still intact. If an attacker were to perform a buffer +overflow, he would overwrite this value and trigger that stack smashing +handler. Currently this kills the target process. +</p> + +<p> +<uri link="http://www.trl.ibm.com/projects/security/ssp/">Further reading on +SSP.</uri> +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Building a PaX-enabled Kernel</title> +<section> +<body> + +<p> +Several Gentoo kernel trees are already patched with PaX. +</p> + +<p> +For 2.4/2.6 based machines, the recommended kernels are <c>hardened-sources</c> +</p> + +<p> +Grab one of the recommended source trees, or apply the appropriate patch from +<uri>http://pax.grsecurity.net</uri> to your own tree and configure it as you +normally would for the target machine. +</p> + +<p> +In <c>Security Options -> PaX</c>, apply the options as shown below. +</p> + +<pre caption="Kernel configuration"> +[*] Enable various PaX features + +PaX Control -> + + [ ] Support soft mode + [*] Use legacy ELF header marking + [*] Use ELF program header marking + MAC system integration (none) ---> + +Non-executable page -> + + [*] Enforce non-executable pages + [*] Paging based non-executable pages + [*] Segmentation based non-executable pages + [*] Emulate trampolines + [*] Restrict mprotect() + [ ] Disallow ELF text relocations + +Address Space Layout Randomization -> + + [*] Address Space Layout Randomization + [*] Randomize kernel stack base + [*] Randomize user stack base + [*] Randomize mmap() base + [*] Randomize ET_EXEC base +</pre> + +<p> +Build this kernel as you normally would and install it to <path>/boot</path>. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Building a PIE/SSP Enabled Userland</title> +<section> +<body> + +<p> +Hardened Gentoo has added support for transparent PIE/SSP building via GCC's +specfile. This means that any users upgrading an older Hardened install should +remove any LDFLAGS or CFLAGS used to trigger PIE/SSP. Also, the +<c>hardened-gcc</c> package is now deprecated and should be unmerged +(version 5.0 is a dummy package). To get the current GCC, add +<c>USE="hardened pic"</c> to <path>/etc/make.conf</path> if not using the hardened +profile. +</p> + +<p> +To maintain a consistant toolchain, first <c>emerge binutils gcc virtual/libc</c>. +Next, rebuild the entire system with <c>emerge -e world</c>. All future packages +will be built with PIE/SSP. +</p> + +<warn> +Both PIE and SSP are known to cause issues with some packages. If you come +across a package that fails to compile, please file a detailed bug report including +a log of the failed compile and the output of <c>emerge info</c> to +<uri>http://bugs.gentoo.org/</uri>. +</warn> + +<p> +You will probably also want to merge pax-utils. +Often if an ELF has executable relocations in the text segment these can cause problems for us. +scanelf -BRylptq +</p> + + +</body> +</section> +</chapter> + +<chapter> +<title>When Things Misbehave (PaX Control)</title> +<section> +<body> + +<p> +Some legitimate applications will attempt to generate code at run time which is +executed out of memory. Naturally, PaX does not allow this and it will promptly +kill the offending application. +</p> + +<note> +The most notable of these applications are XFree/Xorg, mplayer and multimedia tools +based on xine-lib. The easiest way around these problems are to disable PaX +protections. +</note> + +<p> +Luckily there is a utility to toggle protections on a per-executable basis, +<e>paxctl</e>. As with any other package in Gentoo, install paxctl with the +command <c>emerge paxctl</c>. Usage is show by <c>paxctl -h</c>. +</p> + +<note> +If you have an older version of binutils, you will need to use <e>chpax</e>, +which edits the old-style PaX markings. Usage of chpax is largely the same as +paxctl. This also requires legacy marking support built into your kernel. +New versions of paxctl make chpax obsolete. +</note> + +<pre caption="paxctl -h"> +usage: paxctl <options> <files> + +options: + -p: disable PAGEEXEC -P: enable PAGEEXEC + -e: disable EMUTRMAP -E: enable EMUTRMAP + -m: disable MPROTECT -M: enable MPROTECT + -r: disable RANDMMAP -R: enable RANDMMAP + -x: disable RANDEXEC -X: enable RANDEXEC + -s: disable SEGMEXEC -S: enable SEGMEXEC + + -v: view flags -z: restore default flags + -q: suppress error messages -Q: report flags in short format flags +</pre> + +<p> +The first option we will note is <c>-v</c>, which can display flags set on a +particular binary. +</p> + +<pre caption="paxctl -v"> +shell user # paxctl -v /usr/bin/Xorg +PaX control v0.2 +Copyright 2004 PaX Team <pageexec@freemail.hu> + +- PaX flags: -p-sM--x-eR- [/usr/bin/Xorg] + PAGEEXEC is disabled + SEGMEXEC is disabled + MPROTECT is enabled + RANDEXEC is disabled + EMUTRAMP is disabled + RANDMMAP is enabled +</pre> + +<p> +This shows an XFree binary with all protections disabled. +</p> + +<p> +To set flags on a binary, the <c>-z</c> flag is useful as it restores the +default flags. +</p> + +<p> +To disable protections on Xorg, run +<c>paxctl -zpeMRxs /usr/bin/Xorg</c>. +</p> + +<p> +Play around with disabling/enabling protections to see what is the least needed +to run. Often we find that we need the -m -sp combos. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/pax-utils.xml b/xml/pax-utils.xml new file mode 100644 index 0000000..39a3a9d --- /dev/null +++ b/xml/pax-utils.xml @@ -0,0 +1,756 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/pax-utils.xml,v 1.9 2010/08/30 03:01:13 nightmorph Exp $ --> + +<guide> +<title>Gentoo PaX Utilities</title> + +<author title="Author"> + <mail link="swift"/> +</author> +<author title="Editor"> + <mail link="solar"/> +</author> +<author title="Editor"> + <mail link="nightmorph"/> +</author> + +<abstract> +This guide provides instruction on securing your system by using the pax-utils +package to find and identify problematic binaries. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> +<license/> + +<version>2</version> +<date>2010-08-29</date> + +<chapter> +<title>What is this guide about?</title> +<section> +<title>Introduction</title> +<body> + +<p> +The security of a system goes beyond setting up a decent firewall and good +service configurations. The binaries you run, the libraries you load, might +also be vulnerable against attacks. Although the exact vulnerabilities are not +known until they are discovered, there are ways to prevent them from happening. +</p> + +<p> +One possible attack vector is to make advantage of writable <e>and</e> +executable segments in a program or library, allowing malicious users to run +their own code using the vulnerable application or library. +</p> + +<p> +This guide will inform you how to use the <c>pax-utils</c> package to find +and identify problematic binaries. We will also cover the use of <c>pspax</c> (a +tool to view PaX-specific capabilities) and <c>dumpelf</c> (a tool that prints +out a C structure containing a workable copy of a given object). +</p> + +<p> +But before we start with that, some information on <e>objects</e> is in place. +Users familiar with segments and dynamic linking will not learn anything from +this and can immediately continue with <uri link="#scanelf">Extracting ELF +Information from Binaries</uri>. +</p> + +</body> +</section> +<section> +<title>ELF objects</title> +<body> + +<p> +Every executable binary on your system is structured in a specific way, +allowing the Linux kernel to load and execute the file. Actually, this goes +beyond plain executable binaries: this also holds for shared objects; more +about those later. +</p> + +<p> +The structure of such a binary is defined in the ELF standard. ELF stands for +<e>Executable and Linkable Format</e>. If you are really interested in the gory +details, check out the <uri +link="http://refspecs.linux-foundation.org/LSB_4.0.0/LSB-Core-generic/LSB-Core-generic/elf-generic.html"> +Generic ELF spec</uri> or the <c>elf(5)</c> man page. +</p> + +<p> +An executable ELF file has the following parts: +</p> + +<ul> + <li> + The <e>ELF header</e> contains information on the <e>type</e> of file (is it + an executable, a shared library, ...), the target architecture, the + location of the Program Header, Section Header and String Header in the + file and the location of the first executable instruction + </li> + <li> + The <e>Program Header</e> informs the system how to create a process from + the binary file. It is actually a table consisting of entries for each + segment in the program. Each entry contains the type, addresses (physical + and virtual), size, access rights, ... + </li> + <li> + The <e>Section Header</e> is a table consisting of entries for each section + in the program. Each entry contains the name, type, size, ... and + <e>what</e> information the section holds. + </li> + <li> + Data, containing the sections and segments mentioned previously. + </li> +</ul> + +<p> +A <e>section</e> is a small unit consisting of specific data: instructions, +variable data, symbol table, relocation information, and so on. A <e>segment</e> +is a collection of sections; segments are the units that are actually +transferred to memory. +</p> + +</body> +</section> +<section> +<title>Shared Objects</title> +<body> + +<p> +Way back when, every application binary contained <e>everything</e> it needed to +operate correctly. Such binaries are called <e>statically linked</e> binaries. +They are, however, space consuming since different applications use the same +functions over and over again. +</p> + +<p> +A <e>shared object</e> contains the definition and instructions for such +functions. Every application that wants can <e>dynamically</e> link against such +a shared object so that it can benefit from the already existing functionality. +</p> + +<p> +An application that is dynamically linked to a shared object contains +<e>symbols</e>, references for the real functionality. When such an application +is loaded in memory, it will first ask the runtime linker to resolve each and +every symbol it has. The runtime linker will load the appropriate shared objects +in memory and resolve the symbolic references between them. +</p> + +</body> +</section> +<section> +<title>Segments and Sections</title> +<body> + +<p> +How the ELF file is looked upon depends on the view we have: when we are dealing +with a binary file in Execution View, the ELF file contains segments. When +the file is seen in Linking View, the ELF file contains sections. +One segment spans just one or more (continuous) sections. +</p> + +</body> +</section> +</chapter> + +<chapter id="scanelf"> +<title>Extracting ELF Information from Binaries</title> +<section> +<title>The scanelf Application</title> +<body> + +<p> +The <c>scanelf</c> application is part of the <c>app-misc/pax-utils</c> package. +With this application you can print out information specific to the ELF +structure of a binary. The following table sums up the various options. +</p> + +<table> +<tr> + <th>Option</th> + <th>Long Option</th> + <th>Description</th> +</tr> +<tr> + <ti>-p</ti> + <ti>--path</ti> + <ti>Scan all directories in PATH environment</ti> +</tr> +<tr> + <ti>-l</ti> + <ti>--ldpath</ti> + <ti>Scan all directories in /etc/ld.so.conf</ti> +</tr> +<tr> + <ti>-R</ti> + <ti>--recursive</ti> + <ti>Scan directories recursively</ti> +</tr> +<tr> + <ti>-m</ti> + <ti>--mount</ti> + <ti>Don't recursively cross mount points</ti> +</tr> +<tr> + <ti>-y</ti> + <ti>--symlink</ti> + <ti>Don't scan symlinks</ti> +</tr> +<tr> + <ti>-A</ti> + <ti>--archives</ti> + <ti>Scan archives (.a files)</ti> +</tr> +<tr> + <ti>-L</ti> + <ti>--ldcache</ti> + <ti>Utilize ld.so.cache information (use with -r/-n)</ti> +</tr> +<tr> + <ti>-X</ti> + <ti>--fix</ti> + <ti>Try and 'fix' bad things (use with -r/-e)</ti> +</tr> +<tr> + <ti>-z [arg]</ti> + <ti>--setpax [arg]</ti> + <ti>Sets EI_PAX/PT_PAX_FLAGS to [arg] (use with -Xx)</ti> +</tr> +<tr> + <th>Option</th> + <th>Long Option</th> + <th>Description</th> +</tr> +<tr> + <ti>-x</ti> + <ti>--pax</ti> + <ti>Print PaX markings</ti> +</tr> +<tr> + <ti>-e</ti> + <ti>--header</ti> + <ti>Print GNU_STACK/PT_LOAD markings</ti> +</tr> +<tr> + <ti>-t</ti> + <ti>--textrel</ti> + <ti>Print TEXTREL information</ti> +</tr> +<tr> + <ti>-r</ti> + <ti>--rpath</ti> + <ti>Print RPATH information</ti> +</tr> +<tr> + <ti>-n</ti> + <ti>--needed</ti> + <ti>Print NEEDED information</ti> +</tr> +<tr> + <ti>-i</ti> + <ti>--interp</ti> + <ti>Print INTERP information</ti> +</tr> +<tr> + <ti>-b</ti> + <ti>--bind</ti> + <ti>Print BIND information</ti> +</tr> +<tr> + <ti>-S</ti> + <ti>--soname</ti> + <ti>Print SONAME information</ti> +</tr> +<tr> + <ti>-s [arg]</ti> + <ti>--symbol [arg]</ti> + <ti>Find a specified symbol</ti> +</tr> +<tr> + <ti>-k [arg]</ti> + <ti>--section [arg]</ti> + <ti>Find a specified section</ti> +</tr> +<tr> + <ti>-N [arg]</ti> + <ti>--lib [arg]</ti> + <ti>Find a specified library</ti> +</tr> +<tr> + <ti>-g</ti> + <ti>--gmatch</ti> + <ti>Use strncmp to match libraries. (use with -N)</ti> +</tr> +<tr> + <ti>-T</ti> + <ti>--textrels</ti> + <ti>Locate cause of TEXTREL</ti> +</tr> +<tr> + <ti>-E [arg]</ti> + <ti>--etype [arg]</ti> + <ti>Print only ELF files matching etype ET_DYN,ET_EXEC ...</ti> +</tr> +<tr> + <ti>-M [arg]</ti> + <ti>--bits [arg]</ti> + <ti>Print only ELF files matching numeric bits</ti> +</tr> +<tr> + <ti>-a</ti> + <ti>--all</ti> + <ti>Print all scanned info (-x -e -t -r -b)</ti> +</tr> +<tr> + <th>Option</th> + <th>Long Option</th> + <th>Description</th> +</tr> +<tr> + <ti>-q</ti> + <ti>--quiet</ti> + <ti>Only output 'bad' things</ti> +</tr> +<tr> + <ti>-v</ti> + <ti>--verbose</ti> + <ti>Be verbose (can be specified more than once)</ti> +</tr> +<tr> + <ti>-F [arg]</ti> + <ti>--format [arg]</ti> + <ti>Use specified format for output</ti> +</tr> +<tr> + <ti>-f [arg]</ti> + <ti>--from [arg]</ti> + <ti>Read input stream from a filename</ti> +</tr> +<tr> + <ti>-o [arg]</ti> + <ti>--file [arg]</ti> + <ti>Write output stream to a filename</ti> +</tr> +<tr> + <ti>-B</ti> + <ti>--nobanner</ti> + <ti>Don't display the header</ti> +</tr> +<tr> + <ti>-h</ti> + <ti>--help</ti> + <ti>Print this help and exit</ti> +</tr> +<tr> + <ti>-V</ti> + <ti>--version</ti> + <ti>Print version and exit</ti> +</tr> +</table> + +<p> +The format specifiers for the <c>-F</c> option are given in the following table. +Prefix each specifier with <c>%</c> (verbose) or <c>#</c> (silent) accordingly. +</p> + +<table> +<tr> + <th>Specifier</th> + <th>Full Name</th> + <th>Specifier</th> + <th>Full Name</th> +</tr> +<tr> + <ti>F</ti> + <ti>Filename</ti> + <ti>x</ti> + <ti>PaX Flags</ti> +</tr> +<tr> + <ti>e</ti> + <ti>STACK/RELRO</ti> + <ti>t</ti> + <ti>TEXTREL</ti> +</tr> +<tr> + <ti>r</ti> + <ti>RPATH</ti> + <ti>n</ti> + <ti>NEEDED</ti> +</tr> +<tr> + <ti>i</ti> + <ti>INTERP</ti> + <ti>b</ti> + <ti>BIND</ti> +</tr> +<tr> + <ti>s</ti> + <ti>Symbol</ti> + <ti>N</ti> + <ti>Library</ti> +</tr> +<tr> + <ti>o</ti> + <ti>Type</ti> + <ti>p</ti> + <ti>File name</ti> +</tr> +<tr> + <ti>f</ti> + <ti>Base file name</ti> + <ti>k</ti> + <ti>Section</ti> +</tr> +<tr> + <ti>a</ti> + <ti>ARCH/e_machine</ti> + <ti> </ti> + <ti> </ti> +</tr> +</table> + +</body> +</section> +<section> +<title>Using scanelf for Text Relocations</title> +<body> + +<p> +As an example, we will use <c>scanelf</c> to find binaries containing text +relocations. +</p> + +<p> +A relocation is an operation that rewrites an address in a loaded segment. Such +an address rewrite can happen when a segment has references to a shared object +and that shared object is loaded in memory. In this case, the references are +substituted with the real address values. Similar events can occur inside the +shared object itself. +</p> + +<p> +A text relocation is a relocation in the text segment. Since text segments +contain executable code, system administrators might prefer not to have these +segments writable. This is perfectly possible, but since text relocations +actually write in the text segment, it is not always feasible. +</p> + +<p> +If you want to eliminate text relocations, you will need to make sure +that the application and shared object is built with <e>Position Independent +Code</e> (PIC), making references obsolete. This not only increases security, +but also increases the performance in case of shared objects (allowing writes in +the text segment requires a swap space reservation and a private copy of the +shared object for each application that uses it). +</p> + +<p> +The following example will search your library paths recursively, without +leaving the mounted file system and ignoring symbolic links, for any ELF binary +containing a text relocation: +</p> + +<pre caption="Scanning the system for text relocation binaries"> +# <i>scanelf -lqtmyR</i> +</pre> + +<p> +If you want to scan your entire system for <e>any</e> file containing text +relocations: +</p> + +<pre caption="Scanning the entire system for text relocation files"> +# <i>scanelf -qtmyR /</i> +</pre> + +</body> +</section> +<section> +<title>Using scanelf for Specific Header</title> +<body> + +<p> +The scanelf util can be used to quickly identify files that contain a +given section header using the -k .section option. +</p> + +<p> +In this example we are looking for all files in /usr/lib/debug +recursively using a format modifier with quiet mode enabled that have been +stripped. A stripped elf will lack a .symtab entry, so we use the '!' +to invert the matching logic. +</p> + +<pre caption="Scanning for stripped or non stripped executables"> +# <i>scanelf -k '!.symtab' /usr/lib/debug -Rq -F%F#k</i> +</pre> + +</body> +</section> +<section> +<title>Using scanelf for Specific Segment Markings</title> +<body> + +<p> +Each segment has specific flags assigned to it in the Program Header of the +binary. One of those flags is the type of the segment. Interesting values are +PT_LOAD (the segment must be loaded in memory from file), PT_DYNAMIC (the +segment contains dynamic linking information), PT_INTERP (the segment +contains the name of the program interpreter), PT_GNU_STACK (a GNU extension +for the ELF format, used by some stack protection mechanisms), and PT_PAX_FLAGS +(a PaX extension for the ELF format, used by the security-minded +<uri link="http://pax.grsecurity.net/">PaX Project</uri>. +</p> + +<p> +If we want to scan all executables in the current working directory, PATH +environment and library paths and report those who have a writable and +executable PT_LOAD or PT_GNU_STACK marking, you could use the following command: +</p> + +<pre caption="Scanning for Write/eXecute flags for PT_LOAD and PT_GNU_STACK"> +# <i>scanelf -lpqe .</i> +</pre> + +</body> +</section> +<section> +<title>Using scanelf's Format Modifier Handler</title> +<body> + +<p> +A useful feature of the <c>scanelf</c> utility is the format modifier handler. +With this option you can control the output of <c>scanelf</c>, thereby +simplifying parsing the output with scripts. +</p> + +<p> +As an example, we will use <c>scanelf</c> to print the file names that contain +text relocations: +</p> + +<pre caption="Example of the scanelf format modifier handler"> +# <i>scanelf -l -p -R -q -F "%F #t"</i> +</pre> + +</body> +</section> +</chapter> + +<chapter id="pspax"> +<title>Listing PaX Flags and Capabilities</title> +<section> +<title>About PaX</title> +<body> + +<p> +<uri link="http://pax.grsecurity.net">PaX</uri> is a project hosted by the <uri +link="http://www.grsecurity.net">grsecurity</uri> project. Quoting the <uri +link="http://pax.grsecurity.net/docs/pax.txt">PaX documentation</uri>, its main +goal is "to research various defense mechanisms against the exploitation of +software bugs that give an attacker arbitrary read/write access to the +attacked task's address space. This class of bugs contains among others +various forms of buffer overflow bugs (be they stack or heap based), user +supplied format string bugs, etc." +</p> + +<p> +To be able to benefit from these defense mechanisms, you need to run a Linux +kernel patched with the latest PaX code. The <uri +link="http://hardened.gentoo.org">Hardened Gentoo</uri> project supports PaX and +its parent project, grsecurity. The supported kernel package is +<c>sys-kernel/hardened-sources</c>. +</p> + +<p> +The Gentoo/Hardened project has a <uri +link="/proj/en/hardened/pax-quickstart.xml">Gentoo PaX Quickstart Guide</uri> +for your reading pleasure. +</p> + +</body> +</section> +<section> +<title>Flags and Capabilities</title> +<body> + +<p> +If your toolchain supports it, your binaries can have additional PaX flags in +their Program Header. The following flags are supported: +</p> + +<table> +<tr> + <th>Flag</th> + <th>Name</th> + <th>Description</th> +</tr> +<tr> + <ti>P</ti> + <ti>PAGEEXEC</ti> + <ti> + Refuse code execution on writable pages based on the NX bit + (or emulated NX bit) + </ti> +</tr> +<tr> + <ti>S</ti> + <ti>SEGMEXEC</ti> + <ti> + Refuse code execution on writable pages based on the + segmentation logic of IA-32 + </ti> +</tr> +<tr> + <ti>E</ti> + <ti>EMUTRAMP</ti> + <ti> + Allow known code execution sequences on writable pages that + should not cause any harm + </ti> +</tr> +<tr> + <ti>M</ti> + <ti>MPROTECT</ti> + <ti> + Prevent the creation of new executable code to the process + address space + </ti> +</tr> +<tr> + <ti>R</ti> + <ti>RANDMMAP</ti> + <ti> + Randomize the stack base to prevent certain stack overflow + attacks from being successful + </ti> +</tr> +<tr> + <ti>X</ti> + <ti>RANDEXEC</ti> + <ti> + Randomize the address where the application maps to to + prevent certain attacks from being exploitable + </ti> +</tr> +</table> + +<p> +The default Linux kernel also supports certain capabilities, grouped in the +so-called <e>POSIX.1e Capabilities</e>. You can find a listing of those +capabilities in our <uri +link="/proj/en/hardened/capabilities.xml">POSIX Capabilities</uri> document. +</p> + +</body> +</section> +<section> +<title>Using pspax</title> +<body> + +<p> +The <c>pspax</c> application, part of the <c>pax-utils</c> package, displays the +run-time capabilities of all programs you have permission for. On Linux kernels +with additional support for extended attributes (such as SELinux) those +attributes are shown as well. +</p> + +<p> +When ran, <c>pspax</c> shows the following information: +</p> + +<table> +<tr> + <th>Column</th> + <th>Description</th> +</tr> +<tr> + <ti>USER</ti> + <ti>Owner of the process</ti> +</tr> +<tr> + <ti>PID</ti> + <ti>Process id</ti> +</tr> +<tr> + <ti>PAX</ti> + <ti>Run-time PaX flags (if applicable)</ti> +</tr> +<tr> + <ti>MAPS</ti> + <ti>Write/eXecute markings for the process map</ti> +</tr> +<tr> + <ti>ELF_TYPE</ti> + <ti>Process executable type: ET_DYN or ET_EXEC</ti> +</tr> +<tr> + <ti>NAME</ti> + <ti>Name of the process</ti> +</tr> +<tr> + <ti>CAPS</ti> + <ti>POSIX.1e capabilities (see note)</ti> +</tr> +<tr> + <ti>ATTR</ti> + <ti>Extended attributes (if applicable)</ti> +</tr> +</table> + +<note> +<c>pspax</c> only displays these capabilities when it is linked with +the external capabilities library. This requires you to build <c>pax-utils</c> +with -DWANT_SYSCAP. +</note> + +<p> +By default, <c>pspax</c> does not show any kernel processes. If you want those +to be taken as well, use the <c>-a</c> switch. +</p> + +</body> +</section> +</chapter> + +<chapter id="dumpelf"> +<title>Programming with ELF files</title> +<section> +<title>The dumpelf Utility</title> +<body> + +<p> +With the <c>dumpelf</c> utility you can convert a ELF file into human readable C +code that defines a structure with the same image as the original ELF file. +</p> + +<pre caption="dumpelf example"> +$ <i>dumpelf /bin/hostname</i> +#include <elf.h> + +<comment>/* + * ELF dump of '/bin/hostname' + * 10276 (0x2824) bytes + */</comment> + +struct { + Elf32_Ehdr ehdr; + Elf32_Phdr phdrs[8]; + Elf32_Shdr shdrs[26]; +} dumpedelf_0 = { + +.ehdr = { +<comment>(... Output stripped ...)</comment> +</pre> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/pic-fix-guide.xml b/xml/pic-fix-guide.xml new file mode 100644 index 0000000..6a63d36 --- /dev/null +++ b/xml/pic-fix-guide.xml @@ -0,0 +1,956 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/pic-fix-guide.xml" lang="en"> +<title>HOWTO Locate and Fix .text Relocations (TEXTRELs)</title> + +<author title="Author"> + <mail link="vapier@gentoo.org">Mike Frysinger</mail> +</author> +<author title="Author"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Contributor"> + <mail link="pageexec@freemail.hu">The PaX team</mail> +</author> +<author title="Contributor"> + <mail link="kevquinn@gentoo.org">Kevin F. Quinn</mail> +</author> + +<abstract>A guide for tracking down and fixing .text relocations (TEXTRELs)</abstract> + +<!-- The content of this document is placed into the public domain, have fun --> + +<version>1.2</version> +<date>2007-08-19</date> + +<chapter> +<title>Introduction</title> +<section> +<body> + +<p> +You should make sure to read the <uri link="pic-guide.xml">Introduction to +Position Independent Code</uri> before tackling this guide. +</p> + +<p> +This guide is x86-centric for now. The reason being, the majority of broken +object files are due to poorly written x86 assembly stemming from the simple +fact that the x86 architecture has so few registers. Other architectures have +a large enough register set that they can reserve a register as the "PIC +register" without incurring a performance hit. Every architecture has to be +mindful of PIC and its implications, x86 just happens to be the dominant +architecture at the moment in the 'desktop' world of open source. +</p> + +<p> +We will update for non-x86 as we aquire details and useful examples. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Finding broken object code</title> +<section> +<body> + +<p> +Before you can start fixing something, you got to make sure it's broken first, +right? For this reason, we've developed a suite of tools named <uri +link="/proj/en/hardened/pax-utils.xml">PaX Utilities</uri>. If you are not +familiar with these utilities, you should read the <uri +link="/proj/en/hardened/pax-utils.xml">PaX Utilities Guide</uri> now. Gentoo +users can simply do <c>emerge pax-utils</c>. Non-Gentoo users should be able +to find a copy of the source tarball in the <path>distfiles</path> on a <uri +link="/main/en/mirrors.xml">Gentoo Mirror</uri>. Once you have the PaX +Utilities setup on your system, we can start playing around with +<c>scanelf</c>. +</p> + +<p> +Keep in mind that although these utilities are named PaX Utilities, they +certainly do not require PaX or anything else like that on your system. +The name is a historical artifact and want of a better name, has stuck. +</p> + +<p> +Let's see if your system has any broken files. +</p> + +<pre caption="Scan your system"> +$ <i>scanelf -lpqt</i> +TEXTREL /usr/lib/opengl/xorg-x11/lib/libGL.so.1.2 +TEXTREL /usr/lib/libSDL-1.2.so.0.7.2 +TEXTREL /usr/lib/libdv.so.4.0.2 +TEXTREL /usr/lib/libsmpeg-0.4.so.0.1.3 +TEXTREL /usr/lib/libOSMesa.so.4.0 +TEXTREL /usr/lib/libxvidcore.so.4.1 +</pre> + +<p> +Ideally, scanelf should not display anything, but on an x86 system, this is +rarely the case. Here we can see six libraries with TEXTRELs in them. +To quickly find out what package these files come from, Gentoo users can +<c>emerge portage-utils</c> and use <c>qfile</c>. +</p> + +<pre caption="Determine the broken packages"> +$ <i>qfile `scanelf -qylpF%F#t`</i> +media-libs/libdv (/usr/lib/libdv.so.4.0.2) +media-libs/libsdl (/usr/lib/libSDL-1.2.so.0.7.2) +media-libs/smpeg (/usr/lib/libsmpeg-0.4.so.0.1.3) +media-libs/xvid (/usr/lib/libxvidcore.so.4.1) +x11-base/xorg-x11 (/usr/lib/opengl/xorg-x11/lib/libGL.so.1.2) +x11-base/xorg-x11 (/usr/lib/libOSMesa.so.4.0) +</pre> + +<p> +Now that we know the offenders, we have a choice. We can file a bug upstream +(who generally don't care unless you can provide a fix), file a bug in the +<uri link="http://bugs.gentoo.org/">Gentoo Bugzilla</uri> (which is a nice +lazy cop out), or we can fix it ourselves (that is why you're reading this +guide right?). You should double check that the package version you have +installed is the latest upstream has to offer and the latest version your +distro has to offer. Who knows, maybe you can get lucky and someone else has +already fixed it. If you wish to get feedback on your work, feel free to +contact the <mail link="hardened@gentoo.org">Gentoo hardened team</mail>. +</p> + +</body> +</section> + +<section> +<title>"False" Positives</title> +<body> + +<p> +Sometimes you may come across a package which contains a mountain of TEXTRELs +with seemingly no relation to assembler. This may simply be because the +objects were not properly compiled with the appropriate PIC flag. The fix is +quite simple: make sure every object file that is linked into the final shared +object is compiled with the appropriate PIC flag (typically -fPIC). +</p> + +<p> +For example, let's look at the silc-plugin package. It builds up a few +modules, but only compiles some of the objects with -fPIC that are linked into +the final libsilc_core.so module. The output of scanelf here is quite +extensive! +</p> + +<pre caption="Run scanelf on silc-plugin"> +$ <i>scanelf -qT /usr/lib/irssi/modules/libsilc_core.so | wc -l</i> +10734 +$ <i>scanelf -qT /usr/lib/irssi/modules/libsilc_core.so</i> +... + libsilc_core.so: silc_client_ftp_ask_name [0xD542C] in silc_client_receive_new_id [0xD5380] + libsilc_core.so: silc_client_run_one [0xD55CA] in silc_client_receive_new_id [0xD5380] + libsilc_core.so: silc_id_payload_parse [0xD5842] in silc_client_packet_parse_type [0xD57B0] + libsilc_core.so: fgetc@@GLIBC_2.0 [0xD5857] in silc_client_packet_parse_type [0xD57B0] +... +</pre> + +<p> +A TEXTREL on glibc's fgetc() function!? Either people are calling fgetc() from +assembler (and should be shot), or something else is going on. A good rule of +thumb is that if it seems like just about every function/variable reference +causes a TEXTREL and it is all done in C code, then the file was not built as +PIC. Just review the build output and see if the command to compile it was +invoked with -fPIC. If not, go fix the build system as you do not need to dig +into the source. Dodged the bullet this time! +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Dissecting broken object code</title> +<section> +<body> + +<p> +So we have identified some broken libraries, and we want to fix them. The +trouble is, shared library code can be huge. They can have thousands of +functions which come from thousands of object files and thousands of source +code files which total megabytes in size (source code and compiled objects). +Where the hell do we start!? Once again, Mighty Mouse^W^W<c>scanelf</c> is +here to save the day. Before we dive into source code, lets check out a few +libraries. +</p> + +</body> +</section> + +<section> +<title>Dissect libsmpeg</title> +<body> + +<pre caption="Scan libsmpeg"> +<comment>[The output has been truncated from about 35 lines]</comment> +$ <i>scanelf -qT /usr/lib/libsmpeg-0.4.so.0.1.3</i> + libsmpeg-0.4.so.0.1.3: (memory/fake?) [0x2FB3C] in cpu_flags [0x2FB10] + libsmpeg-0.4.so.0.1.3: (memory/fake?) [0x2FB42] in cpu_flags [0x2FB10] + libsmpeg-0.4.so.0.1.3: (memory/fake?) [0x2FB55] in IDCT_mmx [0x2FB48] + libsmpeg-0.4.so.0.1.3: (memory/fake?) [0x2FB84] in IDCT_mmx [0x2FB48] + /usr/lib/libsmpeg-0.4.so.0.1.3 +</pre> + +<p> +The output here tells us that the <e>cpu_flags</e> and the <e>IDCT_mmx</e> +functions are to blame for our TEXTRELs. The first field indicates that this +is poor usage of memory references. Unfortunately, the symbolic name of the +memory being referenced has not been retained in the object code (probably +because the code is hand written assembly), so we need to do a little more +digging. This is where the offset addresses come in to play along with the +<c>objdump</c> utility from the <e>binutils</e> package. The first address +(e.g. 0x2FB3C) is the offset of the TEXTREL while the second address is the +offset of the function (e.g. 0x2FB10). Get used to this because the behavior +of not retaining the symbol name is quite common. +</p> + +<pre caption="Dissecting libsmpeg"> +$ <i>objdump -d /usr/lib/libsmpeg-0.4.so.0.1.3</i> +... + 2fb0f: 90 nop + +<i>0002fb10 <cpu_flags>:</i> + 2fb10: 9c pushf + 2fb11: 58 pop %eax +... + 2fb32: 60 pusha + 2fb33: b8 01 00 00 00 mov $0x1,%eax + 2fb38: 0f a2 cpuid + <i>2fb3a: 89 15 d0 d3 03 00 mov %edx,0x3d3d0</i> + 2fb40: 61 popa + <i>2fb41: a1 d0 d3 03 00 mov 0x3d3d0,%eax</i> + 2fb46: c3 ret + 2fb47: 90 nop +... +</pre> + +<p> +As you can see here, the two lines picked out in the body of <e>cpu_flags</e> +have absolute memory references. In this case, they both refer to memory +location <e>0x3d3d0</e>. Since this object code may be loaded into any +address, using an aboslute reference obviously won't fly. That means +everytime libsmpeg is loaded into memory, the dynamic loader has to rewrite +the <e>0x3d3d0</e> to the actual calculated address on the fly. +</p> + +</body> +</section> + +<section> +<title>Dissect libdv</title> +<body> + +<pre caption="Scan libdv"> +<comment>[The output has been truncated from about 180 lines]</comment> +$ <i>scanelf -qT /usr/lib/libdv.so.4.0.2</i> + libdv.so.4.0.2: (memory/fake?) [0x14AA9] in dv_parse_ac_coeffs_pass0 [0x14A84] + libdv.so.4.0.2: (memory/fake?) [0x14C28] in dv_parse_ac_coeffs_pass0 [0x14A84] + libdv.so.4.0.2: (memory/fake?) [0x14C8A] in dv_parse_video_segment [0x14C6F] + libdv.so.4.0.2: (memory/fake?) [0x14CA6] in dv_parse_video_segment [0x14C6F] + libdv.so.4.0.2: (memory/fake?) [0x15248] in _dv_idct_block_mmx [0x15210] + libdv.so.4.0.2: (memory/fake?) [0x152BE] in _dv_idct_block_mmx [0x15210] + libdv.so.4.0.2: (memory/fake?) [0x1583D] in _dv_dct_88_block_mmx [0x157F8] + libdv.so.4.0.2: (memory/fake?) [0x15847] in _dv_dct_88_block_mmx [0x157F8] + libdv.so.4.0.2: (memory/fake?) [0x15F91] in _dv_dct_248_block_mmx [0x15F58] + libdv.so.4.0.2: (memory/fake?) [0x15FE6] in _dv_dct_248_block_mmx [0x15F58] + libdv.so.4.0.2: (memory/fake?) [0x163D3] in _dv_rgbtoycb_mmx [0x163C8] + libdv.so.4.0.2: (memory/fake?) [0x163DD] in _dv_rgbtoycb_mmx [0x163C8] + libdv.so.4.0.2: dv_vlc_class_index_mask [0x149A7] in dv_decode_vlc [0x14998] + libdv.so.4.0.2: dv_vlc_class_index_rshift [0x149B0] in dv_decode_vlc [0x14998] + libdv.so.4.0.2: dv_vlc_classes [0x149B9] in dv_decode_vlc [0x14998] + libdv.so.4.0.2: dv_vlc_index_mask [0x149C4] in dv_decode_vlc [0x14998] + libdv.so.4.0.2: sign_mask [0x149EB] in dv_decode_vlc [0x14998] + libdv.so.4.0.2: sign_mask [0x14A5D] in __dv_decode_vlc [0x14A1C] + libdv.so.4.0.2: sign_mask [0x14B82] in dv_parse_ac_coeffs_pass0 [0x14A84] + libdv.so.4.0.2: dv_vlc_class_lookup5 [0x14A2F] in __dv_decode_vlc [0x14A1C] + libdv.so.4.0.2: dv_parse_ac_coeffs_pass0 [0x14E03] in dv_parse_video_segment [0x14C6F] + libdv.so.4.0.2: dv_parse_ac_coeffs [0x14E51] in dv_parse_video_segment [0x14C6F] + libdv.so.4.0.2: dv_quant_offset [0x14E69] in _dv_quant_88_inverse_x86 [0x14E5C] + libdv.so.4.0.2: dv_quant_offset [0x14FB3] in _dv_quant_x86 [0x14FA4] + /usr/lib/libdv.so.4.0.2 +</pre> + +<p> +Again, we can see that many functions (like <e>dv_parse_ac_coeffs_pass0</e> +and <e>_dv_idct_block_mmx</e>) have absolute memory references. What we also +see is that a bunch of functions which refer to variables. For example, +<e>dv_decode_vlc</e> misuses the variable <e>dv_vlc_class_index_mask</e> while +<e>dv_parse_video_segment</e> misuses the variable <e>dv_parse_ac_coeffs</e>. +Much easier to locate the problem in the source code when you have the symbol +name. +</p> + +</body> +</section> + +<section> +<title>Dissect libSDL</title> +<body> + +<pre caption="Scan libSDL"> +<comment>[The output has been truncated from about 50 lines]</comment> +$ <i>scanelf -qT /usr/lib/libSDL-1.2.so.0.7.2</i> + libSDL-1.2.so.0.7.2: (memory/fake?) [0x4E213] in _ConvertMMXpII32_24RGB888 [0x4E210] + libSDL-1.2.so.0.7.2: (memory/fake?) [0x4E29E] in _ConvertMMXpII32_16RGB565 [0x4E29B] + libSDL-1.2.so.0.7.2: (memory/fake?) [0x4E3F6] in _ConvertMMXpII32_16BGR555 [0x4E3F3] + libSDL-1.2.so.0.7.2: (memory/fake?) [0x4E402] in _ConvertMMXpII32_16RGB555 [0x4E3FF] + libSDL-1.2.so.0.7.2: (memory/fake?) [0x4E555] in _Hermes_X86_CPU [0x4E529] + libSDL-1.2.so.0.7.2: _copy_row [0x316A2] in SDL_SoftStretch [0x313C0] + libSDL-1.2.so.0.7.2: _mmxreturn [0x4E4FB] in _ConvertMMXpII32_16RGB555 [0x4E3FF] + libSDL-1.2.so.0.7.2: _x86return [0x4E590] in _ConvertX86p16_16BGR565 [0x4E560] + libSDL-1.2.so.0.7.2: _x86return [0x4EE99] in _ConvertX86p32_16BGR555 [0x4EDCA] + libSDL-1.2.so.0.7.2: _x86return [0x4EF4D] in _ConvertX86p32_8RGB332 [0x4EE9D] + /usr/lib/libSDL-1.2.so.0.7.2 +</pre> + +<p> +Doesn't seem to be anything new here. Poor memory usage in functions like +<e>_ConvertMMXpII32_24RGB888</e> and no symbol name which means it's probably +pure hand written assembler. The <e>SDL_SoftStretch</e> function misuses the +symbol <e>_copy_row</e> and since the symbol name has been retained, it's +probably inline assembly code. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Finding the broken source code</title> +<section> +<body> + +<p> +We've identified the functions and sometimes the variables which are causing +us such headaches. Before we can actually fix them though, we have to narrow +down the source code to the offending lines. Since we know the function +names and either the symbol name or a relative position in the function, we +should be able to focus our efforts quite easily. +</p> + +</body> +</section> + +<section> +<title>libsmpeg source dive</title> +<body> + +<p> +Let's start with libsmpeg. We know that both the <e>cpu_flags</e> and +<e>IDCT_mmx</e> functions are broken. But where are they defined? +</p> + +<pre caption="Searching libsmpeg source"> +$ <i>tar zxf smpeg-0.4.4.tar.gz</i> +$ <i>cd smpeg-0.4.4.tar.gz</i> + +<comment>[Find the cpu_flags function]</comment> +$ <i>grep -Rl cpu_flags *</i> +video/mmxflags_asm.S +video/parseblock.cpp +$ <i>grep cpu_flags video/mmxflags_asm.S</i> +.globl cpu_flags + .type cpu_flags,@function <comment><-- here is what we want</comment> +cpu_flags: + jz cpu_flags.L1 # Processor is 386 + je cpu_flags.L1 +cpu_flags.L1: + .size cpu_flags,.Lfe1-cpu_flags + +<comment>[Find the IDCT_mmx function]</comment> +$ <i>grep -Rl IDCT_mmx *</i> +video/parseblock.cpp +video/mmxidct_asm.S +$ <i>grep IDCT_mmx video/mmxidct_asm.S</i> +.globl IDCT_mmx + .type IDCT_mmx,@function <comment><-- here is what we want</comment> +IDCT_mmx: + .size IDCT_mmx,.Lfe1-IDCT_mmx +</pre> + +<p> +As we suspected, both the <e>cpu_flags</e> and the <e>IDCT_mmx</e> functions +are written in pure assembly code. This makes tracking down the unamed +memory reference easier because the source code should closely match the +output of <c>objdump</c>. If we review the output from earlier, we know the +<e>cpuid</e> instruction is used. Since it isn't a common instruction, we +search for it in the source code. +</p> + +<pre caption="Find cpuid in cpu_flags"> +$ <i>grep -A 8 cpuid video/mmxflags_asm.S</i> + cpuid + + movl %edx,flags + + popa + + movl flags,%eax + +cpu_flags.L1: +</pre> + +<p> +In GNU assembler, registers are prefixed with a <e>%</e> and constants are +prefixed with a <e>$</e>, that <e>flags</e> looks suspicious. It also lines +up well with the <c>objdump</c> output from earlier. So what is <e>flags</e>? +</p> + +<pre caption="What is 'flags'?"> +$ <i>grep -C 2 flags video/mmxflags_asm.S</i> +.data + .align 16 + .type flags,@object +flags: .long 0 + +.text +</pre> + +<p> +Seems <e>flags</e> is a data variable local to <path>mmxflags_asm.S</path> +which functions access with absolute memory references rather than relative. +Now we are pretty much done. That's all there is to it. We started with the +library <path>libsmpeg.so</path> and tracked it back to the function +<e>cpu_flags</e> and the variable <e>flags</e> in the +<path>video/mmxflags_asm.S</path> file. That wasn't so hard now was it? :) +</p> + +<p> +If we analyze the <e>IDCT_mmx</e> function, we find a similar trend. +</p> + +<pre caption="IDCT_mmx snippets"> +<comment>[Local variables]</comment> +.data + .align 8 + .type x4546454645464546,@object + .size x4546454645464546,8 +<i>x4546454645464546</i>: + .long 0x45464546,0x45464546 + + .align 8 + .type x61f861f861f861f8,@object + .size x61f861f861f861f8,8 +<i>x61f861f861f861f8</i>: + .long 0x61f861f8,0x61f861f8 + + .align 8 + .type scratch1,@object + .size scratch1,8 +<i>scratch1</i>: + .long 0,0 + +<comment>[Absolute memory references]</comment> +.text +... + psraw $1, %mm5 /* t90=t93 */ + pmulhw <i>x4546454645464546</i>,%mm0 /* V35 */ + psraw $1, %mm2 /* t97 */ +... + psubsw %mm2, %mm1 /* V32 ; free mm2 */ + pmulhw <i>x61f861f861f861f8</i>,%mm1 /* V36 */ + psllw $1, %mm7 /* t107 */ +... + movq 8*3(%esi), %mm7 + psraw $4, %mm4 + movq %mm2, <i>scratch1</i> /* out1 */ +</pre> + +</body> +</section> + +<section> +<title>libSDL source dive</title> +<body> + +<p> +Again, before we jump into how to fix these, lets analyze a few more source +files to get a better handle on identifying problematic code. +</p> + +<pre caption="Broken _ConvertMMXpII32_24RGB888 in libSDL code"> +<comment>[objdump of _ConvertMMXpII32_24RGB888 memory reference]</comment> +<i>0004e210 <_ConvertMMXpII32_24RGB888>:</i> + <i>4e210: 0f 6f 35 50 55 05 00 movq 0x55550,%mm6</i> + 4e217: 0f ef ff pxor %mm7,%mm7 + +<comment>[_ConvertMMXpII32_24RGB888 is defined in src/hermes/mmxp2_32.asm]</comment> + SECTION .data +ALIGN 8 +;; Constants for conversion routines +mmx32_rgb888_mask dd 00ffffffh,00ffffffh +... + SECTION .text +_ConvertMMXpII32_24RGB888: <comment>start of function 0x4E210</comment> + ; set up mm6 as the mask, mm7 as zero + movq mm6, qword [mmx32_rgb888_mask] <comment>memory reference 0x4E213</comment> + pxor mm7, mm7 +</pre> + +<p> +Simple enough, the <e>_ConvertMMXpII32_24RGB888</e> function refers to the +<e>mmx32_rgb888_mask</e> variable. +</p> + +<pre caption="Broken SDL_SoftStretch in libSDL code"> +<comment>[SDL_SoftStretch is defined in src/video/SDL_stretch.c]</comment> +int SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect, + SDL_Surface *dst, SDL_Rect *dstrect) +{ +... +#ifdef __GNUC__ + __asm__ __volatile__ ( + "call _copy_row" + : "=&D" (u1), "=&S" (u2) + : "0" (dstp), "1" (srcp) + : "memory" ); +#else +</pre> + +<p> +Another straight forward bug. An absolute reference to the <e>_copy_row</e> +variable in assembly. If we were to let gcc handle the <e>_copy_row</e> +reference instead though ... +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>How to write PIC (in theory)</title> + +<section> +<title>Rules of thumb</title> +<body> + +<p> +Now we know what broken code looks like. We can point out issues in code and +confidently declare "that crap is broken". While this is a good thing, it +certainly doesn't help much if no one knows how it's supposed to be written. +Let's start with some rules of thumb. +</p> + +<p>General rules</p> +<ul> + <li>Do not mix PIC and non-PIC object code</li> + <li>Shared libraries contain PIC objects</li> + <li>Static libraries contain non-PIC objects (normal/non-PIE systems only)</li> + <li>Let gcc figure out the details whenever possible (e.g. inline asm)</li> + <li>Use the stack for loading of large masks instead of variables</li> + <li>Do not clobber the PIC register when generating PIC objects</li> +</ul> + +<p>x86-specific rules</p> +<ul> + <li>Use @GOT relocations when using external symbols</li> + <li>Use @GOTOFF relocations when using local symbols</li> +</ul> + +</body> +</section> + +<section> +<title>PIC registers by architecture</title> +<body> + +<table> + <tr><th>arch</th><th>register</th></tr> + <tr><ti>blackfin</ti><ti>P3</ti></tr> + <tr><ti>frv</ti><ti>GR15</ti></tr> + <tr><ti>hppa</ti><ti>r19</ti></tr> + <tr><ti>x86</ti><ti>ebx</ti></tr> +</table> + +</body> +</section> +</chapter> + +<chapter> +<title>Cookie cutter PIC fixes</title> + +<section> +<title>Don't use the PIC register</title> +<body> + +<p> +If you come across code which uses the PIC register in some inline assembly, +one fix may be to simply use a different register. For example, the x86 +architecture has 6 general purpose registers (<e>eax</e>, <e>ebx</e>, +<e>ecx</e>, <e>edx</e>, <e>esi</e>, <e>edi</e>). If the code uses just +<e>eax</e> and <e>ebx</e>, just change all references to <e>ebx</e> to +<e>ecx</e> and you're done! +</p> + +<p> +A cleaner fix might be to just let gcc allocate the registers accordingly. If +the inline assembly doesn't actually care which registers it uses, change the +references from <e>ebx</e> to <e>r</e> in the clobber list, and refer to the +variable by number. +</p> + +<p> +Or, if the assembly uses an instruction which always clobbers <e>ebx</e> (e.g. +<e>cpuid</e>), simply hide the value in another register (like <e>esi</e>). +</p> + +<p> +If all else fails, you can fall back to the slow push/pop <e>ebx</e> on the +stack method. +</p> + +<pre caption="Just don't use the PIC register"> +<comment>/* change this code from */</comment> +asm(" + mov %0, %%eax + mov %1, %%ebx + add %%eax, %%ebx + " : : "m"(input1), "m"(input2) : "eax" "ebx"); + +<comment>/* to this functionality equivalent version */</comment> +asm(" + mov %0, %%eax + mov %1, %%ecx + add %%eax, %%ecx + " : : "m"(input1), "m"(input2) : "eax" "ecx"); +</pre> + +<pre caption="Let gcc allocate registers"> +<comment>/* change this code from */</comment> +asm(" + mov %2, %%eax + mov %3, %%ebx + add %%eax, %%ebx + " : "=a"(output1) "=b"(output2) : "m"(input1), "m"(input2)); + +<comment>/* to this functionality equivalent version */</comment> +asm(" + mov %2, %0 + mov %3, %1 + add %0, %1 + " : "=r"(output1) "=r"(output2) : "m"(input1), "m"(input2)); +</pre> + +<pre caption="Hide the PIC register"> +asm("cpuid" : : : "eax", "ebx", "ecx", "edx"); + +<comment>/* can be written to hide ebx */</comment> +asm(" + movl %%ebx, %%edi + cpuid + movl %%edi, %%ebx + " : : : "eax", "ecx", "edx", "edi"); + +<comment>/* or a slower version using the stack */</comment> +asm(" + pushl %%ebx + cpuid + popl %%ebx + " : : : "eax", "ecx", "edx"); +</pre> + +</body> +</section> + +<section> +<title>MMX/SSE masks</title> +<body> + +<p> +A lot of x86 MMX/SSE code loads bitmasks from local variables since they need +to fill up a register which is larger (MMX/64bits or SSE/128bits) than the +native bitsize (x86/32bits). They do this by defining the mask in +consecutive bytes in memory and then having the cpu load the data from the +memory region. +</p> + +<p> +One way to get around this is by being creative with the stack. Rather than +use an absolute memory reference for the mask, push a bunch of 32bit values +onto the stack and use the address specified by the <e>esp</e> register. +Once you're finished, just add a constant to <e>esp</e> rather than popping +off since you don't care about the actual values once they are loaded into +the MMX/SSE registers. +</p> + +<pre caption="Load masks into registers via stack"> +<comment>/* Load masks from memory (causes TEXTRELs) */</comment> + .data +m0X000000: .byte 0, 0, 0, 0, 0, 0, 255, 0 + .text +movq m0X000000, %mm5 + +<comment>/* Load mask from stack (no TEXTRELs)*/</comment> +pushl $0x00FF0000 +pushl $0x00000000 +movq (%esp), %mm5 +addl 8, %esp +</pre> + +</body> +</section> + +<section> +<title>Let gcc worry about it</title> +<body> + +<p> +A lot of inline assembly is written with the symbol names placed right in the +code. Rather than trying to write custom code to handle PIC in assembly, just +let gcc worry about it. Pass in the symbol via the input operand list as a +memory constraint ("m") and gcc will handle all the rest. +</p> + +<pre caption="How to make gcc worry about it"> +unsigned long long a_mmx_mask = 0xf8007c00ffea0059ULL; +void somefunction() +{ + <comment>/* Common (but incorrect) method for loading masks */</comment> + asm("pmullw a_mmx_mask, %%mm0" : : ); + + <comment>/* The correct way is to let gcc do it */</comment> + asm("pmullw %0, %%mm0" : : "m"(a_mmx_mask)); +} +</pre> + +<p> +If your get a warning/error about one of the memory inputs needing to be an +lvalue, then this usually means you're trying to pass in a pointer to an +array/structure rather than the memory location itself. Fixing this may be as +simple as dereferencing the variable in the constraint list rather than in the +assembly itself. +</p> + +</body> +</section> + +<section> +<title>Thunk it in assembly</title> +<body> + +<p> +Hand written assembly sometimes need to access variables (whether they be +local or global). Since none of the previous tricks will work, you just need +to grind your teeth and dig in to write real PIC references yourself using +the GOT. Make sure you keep in mind the first rule of thumb: Do not mix PIC +and non-PIC object code. This probably will require the hand written +assembly be preprocessed before it is assembled, so an assembly source file +with a <e>.s</e> suffix will not work. It needs to be <e>.S</e>. +</p> + +<p> +Also keep in mind that using @GOTOFF will return the variable while using @GOT +will return a pointer to the variable. So accessing a variable with @GOT will +require two steps. +</p> + +<pre caption="How to refer to variables via the GOT"> +#ifdef __PIC__ + +# undef __i686 /* gcc builtin define gets in our way */ +# define MUNG_LOCAL(sym) sym ## @GOTOFF(%ebx) +# define MUNG_EXTERN(sym) sym ## @GOT(%ebx) +# define DEREF_EXTERN(reg) movl (reg), reg +# define INIT_PIC() \ + call __i686.get_pc_thunk.bx ; \ + addl $_GLOBAL_OFFSET_TABLE_, %ebx + +#else + +# define MUNG_LOCAL(sym) sym +# define MUNG_EXTERN(sym) sym +# define DEREF_EXTERN(reg) +# define INIT_PIC() + +#endif + +... +some_function: +... + <comment>/* needs to be before first memory reference */</comment> + INIT_PIC() +... + movl MUNG_EXTERN(some_external_variable), %eax + DEREF_EXTERN(%eax) +... + movl %eax, MUNG_LOCAL(some_local_variable) +... + +#ifdef __PIC__ + .section .gnu.linkonce.t.__i686.get_pc_thunk.bx,"ax",@progbits +.globl __i686.get_pc_thunk.bx + .hidden __i686.get_pc_thunk.bx + .type __i686.get_pc_thunk.bx,@function +__i686.get_pc_thunk.bx: + movl (%esp), %ebx + ret +#endif +</pre> + +<note> +Usage of <e>ebx</e> as the register to do relative addressing is not required, +it is just common convention. The above examples could just as easily be done +by using <e>ecx</e> or <e>edx</e>. +</note> + +<p> +Since we hide the PIC details behind the preprocessor define <e>__PIC__</e>, +we know that the correct code will be generated for both the PIC and non-PIC +cases. +</p> + +<p> +The <e>__i686.get_pc_thunk.bx</e> function is a standard method for acquiring +the address of the GOT at runtime and storing the result in <e>ebx</e>. The +funky name is what gcc uses by convention when generating PIC objects, so we +too use the same name. The <e>@GOT</e> and <e>@GOTOFF</e> notation tells the +assembler where to find the variables in memory. The <e>.section +.gnu.linkonce.t</e> is useful because it tells the linker to only include one +instance of this function in the final object code. So if you have multiple +files which declare this same function which are compiled and linked into the +same final library, the linker will discard all duplicate instances of the +function thus saving space (which is always a good thing). +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>How to fix broken PIC (in practice)</title> +<section> +<body> + +<p> +So if the previous code snippets were broken, what should they look like you +may wonder. Well let's find out. +</p> + +</body> +</section> + +<section> +<title>Fix libsmpeg</title> +<body> + +<pre caption="Fixing cpu_flags in libsmpeg by rewriting it"> +<comment>[Non-PIC Version]</comment> +.type flags,@object +flags: .long 0 +... + pusha + movl $1,%eax + cpuid + movl %edx,flags + popa + movl flags,%eax + + +<comment>[PIC Version]</comment> + pushl %ebx + movl $1,%eax + cpuid + movl %edx,%eax + popl %ebx +</pre> + +<pre caption="Fixing IDCT_mmx in libsmpeg by using relative addressing"> +<comment>[Non-PIC Version]</comment> + pmulhw x5a825a825a825a82, %mm1 + + +<comment>[PIC Version]</comment> +#ifdef __PIC__ +# undef __i686 /* gcc define gets in our way */ + call __i686.get_pc_thunk.bx + addl $_GLOBAL_OFFSET_TABLE_, %ebx +#endif +... + pmulhw x5a825a825a825a82@GOTOFF(%ebx), %mm1 +... +#ifdef __PIC__ + .section .gnu.linkonce.t.__i686.get_pc_thunk.bx,"ax",@progbits +.globl __i686.get_pc_thunk.bx + .hidden __i686.get_pc_thunk.bx + .type __i686.get_pc_thunk.bx,@function +__i686.get_pc_thunk.bx: + movl (%esp), %ebx + ret +#endif +</pre> + +</body> +</section> + +<section> +<title>Fix libSDL</title> +<body> + +<pre caption="Fixing _ConvertMMXpII32_24RGB888 in libSDL"> +<comment>[Non-PIC Version]</comment> +mmx32_rgb888_mask dd 00ffffffh,00ffffffh +... + movq mm6, qword [mmx32_rgb888_mask] + + +<comment>[PIC Version]</comment> +%macro _push_immq_mask 1 + push dword %1 + push dword %1 +%endmacro +%macro load_immq 2 + _push_immq_mask %2 + movq %1, [esp] +%endmacro +%define mmx32_rgb888_mask 00ffffffh +... + load_immq mm6, mmx32_rgb888_mask + CLEANUP_IMMQ_LOADS(1) +</pre> + +<pre caption="Fixing SDL_SoftStretch in libSDL"> +<comment>[Non-PIC Version]</comment> + __asm__ __volatile__ ( + "call _copy_row" + : "=&D" (u1), "=&S" (u2) + : "0" (dstp), "1" (srcp) + : "memory" ); + + +<comment>[PIC Version]</comment> + __asm__ __volatile__ ( + "call *%4" + : "=&D" (u1), "=&S" (u2) + : "0" (dstp), "1" (srcp), "r" (&_copy_row) + : "memory" ); +</pre> + +</body> +</section> +</chapter> + +<chapter> +<title>References</title> +<section> +<body> + +<ul> + <li>thanks to the PaX team for holding my hand</li> + <li><uri link="http://www.ibiblio.org/gferg/ldp/GCC-Inline-Assembly-HOWTO.html">GCC Inline Assembly HOWTO</uri></li> + <li><uri link="http://nasm.sourceforge.net/">NASM</uri>'s Documentation on <uri link="http://nasm.sourceforge.net/doc/html/nasmdoc6.html#section-6.5.2">ELF shared libraries</uri></li> + <li>Linkers and Loaders <uri link="http://www.iecc.com/linker/linker08.html">chapter 8</uri> and <uri link="http://www.iecc.com/linker/linker10.html">chapter 10</uri></li> +</ul> + +</body> +</section> + +</chapter> +</guide> diff --git a/xml/pic-guide.xml b/xml/pic-guide.xml new file mode 100644 index 0000000..ce94b20 --- /dev/null +++ b/xml/pic-guide.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/pic-guide.xml" lang="en"> +<title>Introduction to Position Independent Code</title> + +<author title="Author"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Editor"> + <mail link="pappy@gentoo.org">Alexander Gabert</mail> +</author> + +<abstract>What every developer should understand about using Position Independent Code</abstract> + +<!-- The content of this document is placed into the public domain, have fun --> +<license/> + +<version>1.2</version> +<date>2005-10-11</date> + +<chapter> +<title>Introduction to PIC - (Position Independent Code)</title> +<section> +<body> + +<p> +PIC code radically differs from conventional code in the way it +calls functions and operates on data variables.<br/> + +It will access these functions and data through an indirection table, +the "Global Offset Table" (GOT), by software convention accessible using +the reserved name "_GLOBAL_OFFSET_TABLE_".<br/> + +The exact mechanism used for this is hardware architecture dependent, +but usually a special machine register is reserved for setting up +the location of the GOT when entering a function.<br/> + +The rationale behind this indirect addressing is to generate code +that can be independently accessed of the actual load address.<br/> + +In a true PIC library without relocations in the text segment, +only the symbols exported in the "Global Offset Table" need updating +at run-time depending on the current load address of the various +shared libraries in the address space of the running process. +</p> + +<p> +Likewise, procedure calls to globally defined functions are redirected +through the "Procedure Linkage Table" (PLT) residing in the data segment +of the core image. Again, this is done to avoid run-time modifications +to the text segment. +</p> + +<p> +The linker-editor allocates the Global Offset Table and Procedure +Linkage Table when combining PIC object files into an image suitable for +mapping into the process address space. It also collects all symbols +that may be needed by the run-time link-editor and stores these along +with the image's text and data bits. Another reserved symbol, _DYNAMIC +is used to indicate the presence of the run-time linker structures. +Whenever _DYNAMIC is relocated to 0, there is no need to invoke the +run-time link- editor. If this symbol is non-zero, it points at a data +structure from which the location of the necessary relocation- and +symbol information can be derived. This is most notably used by the +start-up module, crt0, crt1S and more recently Scrt1. The _DYNAMIC +structure is conventionally located at the start of the data segment of +the image to which it pertains. +</p> + +<p> +On most architectures, when you compile source code to object code, you +need to specify whether the object code should be position independent +or not. There are occasional architectures which don't make the +distinction, usually because all object code is position independent by +virtue of the Application Binary Interface (ABI), or less often because +the load address of the object is fixed at compile time, which implies +that shared libraries are not supported by such a platform). + +If an object is compiled as position independent code (PIC), +then the operating system can load the object at any address +in preparation for execution. This involves a time overhead, +in replacing direct address references with relative addresses at +compile time, and a space overhead, in maintaining information to help +the runtime loader fill in the unresolved addresses at runtime. +Consequently, PIC objects are usually slightly larger and slower at +runtime than the equivalent non-PIC object. The advantage of sharing +library code on disk and in memory outweigh these problems as soon as +the PIC object code in shared libraries is reused. +</p> + +<p> +PIC compilation is exactly what is required for objects which will +become part of a shared library. Consequently, libtool builds PIC +objects for use in shared libraries and non-PIC objects for use in +static libraries. Whenever libtool instructs the compiler to generate a +PIC object, it also defines the preprocessor symbol, `PIC', so that +assembly code can be aware of whether it will reside in a PIC object or +not. +</p> + +<p> +Typically, as libtool is compiling sources, it will generate a `.lo' +object, as PIC, and a `.o' object, as non-PIC, and then it will use the +appropriate one of the pair when linking executables and libraries of +various sorts. On architectures where there is no distinction, the `.lo' +file is just a soft link to the `.o' file. +</p> + +<p> +In practice, you can link PIC objects into a static archive for a small +overhead in execution and load speed, and often you can similarly link +non-PIC objects into shared archives. +</p> + +<p> +When you use position-independent code, relocatable references are +generated as an indirection that use data in the shared object's data +segment. The text segment code remains read-only, and all relocation +updates are applied to corresponding entries within the data segment. +</p> + +<p> +If a shared object is built from code that is not position-independent, +the text segment will usually require a large number of relocations to +be performed at runtime. Although the runtime linker is equipped to +handle this, the system overhead this creates can cause serious +performance degradation. +</p> + +<p> +You can identify a shared object that requires relocations against its +text segment using tools such as 'readelf -d foo' and inspect the output +for any TEXTREL entry. The value of the TEXTREL entry is irrelevant. Its +presence in a shared object indicates that text relocations exist. +</p> + +<p> +References: +</p> +<ul> + <li><uri link="link.5.html">NetBSD link(5) File Formats Manual</uri></li> + <li><uri link="http://sources.redhat.com/autobook/autobook/autobook_71.html#SEC71">Autobook (Position Independent Code) from Chapter 10.2.1</uri></li> + <li><uri link="http://docs.sun.com/app/docs/doc/817-1984">docs.sun.com: Linker and Libraries Guide</uri></li> + <li>Linkers and Loaders <uri link="http://www.iecc.com/linker/linker08.html">chapter 8</uri> and <uri link="http://www.iecc.com/linker/linker10.html">chapter 10</uri></li> +</ul> + +</body> +</section> +</chapter> +</guide> diff --git a/xml/pic-internals.xml b/xml/pic-internals.xml new file mode 100644 index 0000000..53568bb --- /dev/null +++ b/xml/pic-internals.xml @@ -0,0 +1,283 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/pic-internals.xml" lang="en"> +<title>Position Independent Code internals</title> + +<author title="Author"> + <mail link="pappy@gentoo.org">Alexander Gabert</mail> +</author> +<author title="Contributor"> + <mail link="solar@gentoo.org">solar</mail> +</author> +<author title="Contributor"> + <mail link="pageexec@freemail.hu">The PaX team</mail> +</author> + +<abstract>Understanding the impact of text relocations and explaining the use of PIC in shared libraries</abstract> + +<!-- The content of this document is placed into the public domain, have fun --> +<license/> + +<version>1.0</version> +<date>Feb 14 2004</date> + +<chapter> +<title>Excerpt</title> +<section> +<body> +<p> +This technical documentation tries to explain and evaluate the technical background and the performance benefit or likewise penalty of PIC (Position Independent Code). +</p> + +<p> +The goal should be achieved by illustrating an easy to follow learning path to understand text relocations and why they are imposing a security risk and a speed penalty to running applications. +</p> + +<p> +To enhance the reading comfort for beginners, it is not covering stack layouts, the technical details of starting functions and discussing internal toolchain processings during building and executing programs. + +We are aware of the fact that this document may put a smile on the face of experienced readers due to the sometimes barely justified oversimplification of technical internals. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Introduction to PIC - (Position Independent Code)</title> +<section> +<body> + +<p> +PIC code differs from traditional code in the method it will perform access to function code and data objects/variables through an indirect accessing table. + +This table is called the "Global Offset Table" because it contains the addresses of code functions and data objects exported by a shared library. +</p> + +<p> +The dynamic loader modifies the GOT slots to resemble the current memory address for every exported symbol in the library. + +When the dynamic loader has completed, the GOT contains full absolute addresses for each symbol reference constructed from the load address (PT_LOAD) of the shared library that contains these symbols plus their offset inside this shared library. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Using PIC for building shared libraries</title> +<section> +<body> + +<p> +Besides for using position independent executables (see PIE-SSP docs, PaX specs files using -shared and Jelinek binutils patches for -pie support), +the natural reason for using "-fPIC" (position independent code) is the use in shared dynamic libraries. + +This makes the overall footprint of all dynamically linked ELF executables on the system as small as possible, +while it also prevents possible code duplication and actively reduces requirements on memory and file system. +</p> + +<p> +A unique characteristic of a typical shared library is that it can be located anywhere in the process memory layout. +Because of this, the contents of the shared library are not accessed directly but via clearly exported definitions in symbol tables during building. +Today, shared libraries can be easily implemented by incorporating this key advantage of the ELF standard. + +Making libraries larger, smaller or moving around functions in the library is very easy as long as the symbol table to access the functions does not change. +</p> + +<p> +During building, The linker is only responsible for setting up exported symbols of the library in question. + +Telling the object code that it needs to be position independent is the task of the preprocessor and the compiler. +Here, the role of the Makefiles and the CFLAGS/LDFLAGS feeding the compiler with instructions becomes visible. + +The preprocessor is adding special definitions ("__PIC__" "__pic__") and the compiler is using "-fPIC" or "-fpic" depending on the data access model. +Hopefully, when there is no PIC unaware assembler in the source code, these flags are generating the object code needed for position independence. + +The object code needs to be generated PIC for successfully opening the doors to position independent relocation of the library, created from the PIC .o relocatable objects. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Relocations in the TEXT segment of shared libraries used by dynamically linked executables</title> +<section> +<body> + +<p> +This chapter is going to explain the reasons why relocations in the TEXT segment of a library, also called "text relocations", must be avoided by designers of shared libraries. +</p> + +<p> +The performance penalty of text relocations is the reason that every shared library object code should be generated with -fPIC or -fpic, depending on the addressing range of the data that is used. + +Otherwise the library is considered not "clean". +</p> + +<p> +A text relocation is a memory address in the "LOAD READ-EXECUTE" text segment of a shared library where text segment means the segment that contains the program code. + +Such a nonPIC text segment often contains large amounts of memory addresses that need to be "patched" (manipulated, modified, corrected) with the runtime location of functions and data. + +This is performed by the dynamic loader (ld.so in glibc) during startup of the dynamically linked executable and invocation of these libraries in the process space. + +The reason that the dynamic loader needs to spend so much time "patching" memory addresses (relocations) was stated above: +a unique characteristic of a typical shared library is that it can be located anywhere in the process memory layout. + +</p> + +<p> +So the dynamic loader is the key to the "located anywhere" functionality: it recognizes and reorganizes the memory addresses that need to be refurbished and applies the change to these locations. + +This means that the dynamic loader will be responsible for relocating the memory address. + +For example, in a non-PIC compiled libmpeg3 library there are roughly 6000 memory locations left inside the shared library to point to some 200-300 functions and data referred by the instructions. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Using prelink and LD_BIND_NOW</title> +<section> +<body> + +<p> +Using prelink somehow mitigates the performance-intensive relocation process to a one-time operation: the relocation is satisfied and prematurely resolved/patched inside the binaries and the nonPIC shared libraries. + +This can be reached with using a program like prelink that is working on the actual files and modifying the relocations and GOT slots in the executables and libraries directly, thus saving the dynamic loader a lot of work during actually starting and running the executable. + +While dealing with executables, note that prelink inserts a "hint" into the PT_LOAD segment of every shared library to make the kernel load it at the expected address. +</p> + +<p> +Bear in mind that not all relocations are resolved at startup time. +When LD_BIND_NOW is not used, the lazy binding for libraries somehow tries to minimize the overhead to a more timely fashion by only relocating symbols at their first invocation during program flow. + +The environment variable LD_BIND_NOW (and the ld switch "-z now") tries to address this problem for slow machines by moving all needed relocations to be done at startup of a binary, invoking much much slower startup times but later making the binary run more fluently on slower machines because relocations are satisfied now :-) + +But you should be careful and know that using LD_BIND_NOW is not recommended on machines where responsiveness is an issue, clicking on an icon in KDE or GNOME and waiting 20 seconds for evolution to start is sometimes inacceptable by users. + +In doubt, use prelink! +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>More about negative side effects of text relocations in shared libraries</title> +<section> +<body> + +<p> +There are two drawbacks of nonPIC shared libraries currently. +</p> + +<p> +There is a moderate security risk on nonPIC libraries containing text relocations. +The TEXT pages for shared libraries cannot be marked READONLY by the kernel starting the binary and mapping in ELF segments and libraries. +</p> + +<p> +There is also a memory overhead and performance penalty: data and code cannot be shared amongst processes via COW. + +COW means "copy on write", this uses the same readonly memory pages for all instances of the same binary and for all processes referring to the same used libraries. + +Using COW, readonly memory pages for shared libraries and executables need not to be recreated for new processes in their memory until they are are about to be changed by the new process, like for patching in text relocations by the dynamic loader, this is all implemented transparently in the virtual memory management of the Linux kernel. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>So, why not use -fPIC building as default for all applications?</title> +<section> +<body> + +<p> +So why not compile all applications with -fPIC if it has so much advantages? + +The impact of "-fPIC" on certain arches like AMD64 can be tolerated due to the true PIC-oriented data and code addressing scheme and is even necessary on several (considered broken) architectures that refuse to build certain applications without -fPIC (errors with nonPIC relocation types on PARISC). + +There is only one official method to add flags like "-fPIC" to ebuilds: using the flag-o-matic eclass and "append-flags". + +However, it is not a good idea to enable "-fPIC" in global CFLAGS or create ebuilds that automatically add the "-fPIC" flag independent of the situation and architecture it is applied. + +There are people referring to a noticeable performance penalty when running executables containing position independent code compared to executables incorporating normally compiled object code. +</p> + +<p> +Normally, the setup of the PIC register takes about three assembler commands per function that is entered and additional overhead of 1-2 assembler commands per accessed symbol (code function or data object). + +Thus, we have the inverted situation for normal executables that the invocation of the "-fPIC" flag is doing the exact opposite like in shared libraries. + +Instead of giving us speed for low memory profile by saving memory via COW and making text relocations unnecessary, the additional overhead in the addressing mode is imposing a speed penalty on our executable. +</p> + +<p> +Why does a normal dynamically linked executable (not position independent shared executable) need no text relocations and PIC addressing? + +Because the kernel (in a normal world) always moves it to the same location in process memory when started, making it unnecessary for the dynamic loader to address any TEXT relocations in the normal executable: because there are none! + +We have learned that only shared libraries are located at a given, freely choosen, address space in the process memory of the dynamically linked executable. + +So, in the text segment of a "fixed load location" normal executable there are no TEXT segment relocations because all addresses are at the same location in memory during every invocation of the program. + +The addressing of data and functions inside the executable are provided via relative and absolute relocations in a common used set of platform-dependent, performance oriented assembler commands. +</p> + +<p> +While the architectures supported by Gentoo are quite differently addressing memory, they all share the same characteristic: direct non-PIC-aware addressing is always cheaper (read: faster) than PIC addressing. + +For example the RISC (Reduced Instruction Set) architectures sparc, ppc and hppa sometimes use more than one assembler command issuing several more opcodes to do what x86 does with a single variable length assembler command, loading a full 32-Bit address for example. + +Only the AMD64 seems to support some kind of "emulation" mode where it does not seem to make a difference if PIC or normal addressing is used for referring code functions and data to access. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Conclusion</title> +<section> +<body> + +<p> +The only way that time-wasting text relocations are imposed on a process, leading to the dynamic loader having to work overtime, are with using nonPIC dynamically shared libraries. +</p> + +<p> +For normal executables that are dynamically linked to these shared libraries, the executables themselves need not to be using -fPIC for building the object code they consist of. + +These executables simply do not need the PIC addressing mode for their functions and data and will use the PLT (Process Linkage Table) and the GOT (Global Offset Table) anyway for addressing external data in shared libraries. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>References</title> +<section> +<body> + +<ul> + <li><uri link="pic-guide.xml">Introduction to Position Independent Code</uri></li> + <li><uri link="http://www.iecc.com/linker/">Linkers and Loaders</uri> by Levine (the Levine book)</li> + <li><uri link="http://people.redhat.com/drepper/dsohowto.pdf">How to Write Shared Libraries</uri> by Ulrich Drepper</li> +</ul> + +<p>I would like to say personal thanks to the PaX team for supporting us with an extraordinary and outstanding commitment to our toolchain issues!</p> + +</body> +</section> +</chapter> + +</guide> diff --git a/xml/pie-ssp.xml b/xml/pie-ssp.xml new file mode 100644 index 0000000..ceaaa34 --- /dev/null +++ b/xml/pie-ssp.xml @@ -0,0 +1,287 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="pie-ssp.xml"> + +<title>Gentoo Linux PIE-SSP Documentation</title> + +<author title="Author"> + <mail link="pappy@gentoo.org">Alexander Gabert</mail> +</author> + +<author title="Contributor"> + <mail link="solar@gentoo.org">solar</mail> +</author> + +<abstract>(This DOC is badly outdated and mostly obsolete) This introductionary guide explains the basic behaviour of the hardened toolchain.</abstract> + +<version>1.45</version> + +<date>20050805</date> + +<chapter> + <title>Introduction to Randomization and Stack Protection</title> + <section> +<body> + +<p> +First of all, the PaX homepage has moved to http://pax.grsecurity.net, +please update your bookmarks. +</p> + +<p> +While the goal of the PaX suite has remained the same ever since, +preventing memory related security vulnerabilities, there has been major +advancements in the progress of getting similar and coexisting kernel +patches into the attention of the wide public. +</p> + +<p> +Even though linear stack smashing attacks, formatstring overflows and +return to libc style attacks cannot be fully prevented or suppressed by +effective randomization of the running executable, there seems to be a +wide consent amongst information security experts and GNU/Linux +distributions that it does help putting up another barrier (see chapter +3). +</p> + +<p> +The outstanding support and help from the Gentoo toolchain main developer +and coordinator, Martin Schlemmer as well as Dr. Hiroaki Etoh and moid +from the OpenBSD team with the closer integration of the SSP patch into +the Gentoo toolchain and userland has proven the common goals and +commitments between developers throughout the world striving for better +support and acceptance of technology that provides a security oriented, +high quality, automatic response to simple linear stack overflow attempts. +</p> + +</body> +</section> +</chapter> + +<chapter> + <title>Kernels with PaX patches</title> + <section> +<body> +<p> +The positive feedback generated by users who are enhanced by the +grsecurity patch being included as a standard security measure in the +native gentoo-sources leads us to uphold the support for grsecurity in +this common practice kernel. +</p> + +<p> +While the hardened-sources has been abolished in favour of the ongoing +concurrent development of fully supported MAC/ACL schemes in Gentoo +Hardened, selinux-sources and grsec-sources can benefit from the thorough +implementation of a true PIE (position independent executables) and SSP +(stack smashing protector) environment via the incorporated PaX patch. +</p> + +<p> +Chris Pebenito holds up the high quality and standard of the +selinux-sources while keeping in touch with the PaX developments and +introducing randomization and userland features of PIE and SSP via PaX or +correlating patches according to the requirements of the solutions needed +by our partners. +</p> + +<p> +The hardened-sources are maintained by hardened team and is the ideal +kernel to use with a hardened toolchain. +</p> +</body> +</section> +</chapter> + +<chapter> + <title>GNU C Compiler and the history of PIE support</title> + <section> +<body> +<p> +As described in the introduction, in the last year we have seen major +advancements (and confusion) in the GNU upstream toolchain regarding the +implementation of a system wide scenario for storing information about +stack protection requirements and randomization of executables via PIE +(position independent executables) support. +</p> +<p> + +When the first PaX randomization patches came out, a modification to the +GNU C compiler specs file was needed to create so-called +"shared executables". +</p> +<p> + +This means that these days the linker was told to explicitly link -fPIC +(gcc function to force the creation of position independent code) compiled +.o object files with a interp.o interpreter field pointing to "/lib/ld.so" +from glibc on the intel platform, using a special custom formed crt1S.o +which was able to set up the addresses of "_main", "_init" (recent glibc: +"__libc_csu_init") and "_fini" (recent glibc: "__libc_csu_fini") in the +"_start" function in a position independent manner. +</p> + +<p> +So basically a setup like in a shared library was used to set up the PIC +(position independent code) addressing of the data and the code segments +in the executable that needs to be started via the main() function. +</p> + +<p> +There has been a bug on nonintel arches regarding the setup of the PIC +register (%r19 on parisc) for statically linked binaries. +Since this bug has been fixed on all arches we can support, it is now also +safe to create this library-like PIC setup for statically compiled +binaries. +</p> + +<p> +When Ingo Molnar from Redhat started to introduce the execshield kernel +patches, the developers at Redhat also wanted to make use of the "hot and +new" randomization for binaries, so Jakub Jelinek invested a lot of time +in the preparation of the toolchain (binutils, glibc, gcc) to introduce +the -pie flag which generates these binaries with the correct interpreter +and a glibc provided Scrt1.o. +</p> + +<p> +With Russell Coker involved in the Fedora distribution of Redhat, the +future directions to an Execshield based selinux setup with -pie support +from the toolchain are a visible example for the integration of security +improvements in a full-scale commercial office and home user distribution. +</p> + +<p> +Russell Coker also seems to be interested in supporting selinux for +Debian. +</p> + +<p> +However, the technical approach to support compatibility needs of +applications (java apps, gcc heuristically sets executable stack for +nested functions) over default security measures (as implemented in PaX +kernels) may not suit environments with higher risk analysis and threat +potential. +</p> +</body> +</section> +</chapter> + + +<chapter> +<title>A proven gcc extension for linear stack overflow protection</title> +<section> +<body> +<p> +When the OpenBSD team discovered SSP as their favourite utility to limit +the possibility of linear stack overflows, they also evaluated the stack +smash handler functions and found out that the best way to introduce SSP +into their toolchain was a modification of the dynamic linker for +executables requiring that no standard libraries were included (boot +loaders!) and giving all other dynamically linked applications the chance +to retrieve the guard object and the necessary related functions via their +standard C library. +Thus, the dynamically linked executables and shared libraries protected +via propolice were using one exact shared copy of the __guard reference +and the needed functions for setup and smash handling in a single +location. +</p> + +<p> +Statically linked executables will have their own copy of __guard and the +functions to work properly. +</p> + +<p> +On the Linux platform, Dr. Etoh decided to put the __guard, the +__guard_setup and the __stack_smash_handler into the libgcc of the gcc +package. +This led to problems with big packages like apache2 and mod_php4 producing +false positives because the wrong local __guard copies in shared libraries +and/or the main executable were used by different __stack_smash_handlers, +this odd momentum has been resolved and isolated in gdb sessions by pipacs +from the PaX team. +</p> +<p> +Having moid from the OpenBSD team to help us mitigating this negative side +effect of the GNU C compiler and working close together with Dr. Etoh from +the IBM labs in japan gave us the chance to introduce the first +glibc-based SSP setup for userland in GNU/Linux for Gentoo-Linux at all! +( PIE-SSP it works! ) +</p> +</body> +</section> +</chapter> + +<chapter> + <title>Position Independent Executables with Propolice support</title> +<section> +<body> + +<p>On a Gentoo system this is currently accomplished by merging <c>gcc</c>: </p> + +<pre caption="Emerging gcc"> +# <i>USE="hardened pic" emerge sys-devel/gcc</i> +</pre> + +<p>While a hardened <c>gcc</c> starts the transparent conversion of a system to position independence for your binaries via making use of gcc spec file handling.</p> + +<p>Once the gcc has been equipped with that new specs file, a package or a kernel building can only return to the conventional building behaviour when it feeds the correct CFLAGS and LDFLAGS to the build process.</p> + + <p>As an example lets try the rebuilding our chpax binary as a position independent + executable. We can use the file(1) command to determine if we + in fact we are building our executables as ET_EXEC or ET_DYN.</p> + + <p>The first example here we have chpax built as a ET_DYN + and the second one is chpax not built as a standard ET_EXEC file.</p> + + <pre caption="Example files"> +# <i>file /sbin/chpax</i> +/sbin/chpax: ELF 32-bit LSB shared object, Intel 80386, version 1 \ + (GNU/Linux), stripped + +# <i>file /sbin/chpax</i> +/sbin/chpax: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), for \ + GNU/Linux 2.0.0, dynamically linked (uses shared libs), stripped +</pre> + +<p>The <c>gcc</c> package has been designed to easily revert back to a conventional building environment behaviour in case of problems.</p> + +<p>Users can restore the original gcc specs file behaviour at any time by calling the gcc-config utility on the commandline. gcc-config -l ; gcc-config</p> + +<p>Ebuilds that experience problems with the a hardened gcc automatic transparency can evaluate the existence of the hardened gcc package on the target system and use compatibility CFLAGS to restore the original gcc behaviour during the emerge.</p> + +</body> +</section> +</chapter> + +<chapter> + <title>Using distcc with hgcc</title> + <section> + <body> + <p> +<mail link="lisa@gentoo.org">Lisa Marie Seelye</mail> says you need the same hgcc and gcc versions on all distcc host volunteer machines. +</p> + </body> + </section> +</chapter> + +<chapter> + <title>Credits and Reference</title> + <section> + <body> + <ul> + <li><uri link="http://pax.grsecurity.net">PaX Homepage</uri></li> + <li><uri link="http://pax.grsecurity.net/docs/index.html">PaX Documentation</uri></li> + <li><uri link="http://www.research.ibm.com/trl/projects/security/ssp/">Propolice/SSP Homepage</uri></li> + <li><uri link="http://www.grsecurity.net">Grsecurity Homepage</uri></li> + <li><uri link="http://fedora.redhat.com">Fedora Homepage</uri></li> + <li><uri link="http://www.openbsd.com">OpenBSD Homepage</uri></li> + <li><uri link="http://www.nsa.gov/selinux">SElinux Homepage</uri></li> + <li><uri link="http://www.gentoo.org/doc/en/distcc.xml">Gentoo Distcc Documentation</uri></li> + </ul> + </body> + </section> +</chapter> + +</guide> diff --git a/xml/prelude-ids.xml b/xml/prelude-ids.xml new file mode 100644 index 0000000..43aeb38 --- /dev/null +++ b/xml/prelude-ids.xml @@ -0,0 +1,572 @@ +<?xml version='1.0' encoding="UTF-8"?> + +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="prelude-ids.xml"> +<title>Gentoo Linux Documentation -- Prelude Intrusion Detection System</title> +<author title="Author"><mail link="zack@tehunlose.com"> + Zack Gilburd</mail> +</author> +<author title="Contributors"> + <mail link="mboman@gentoo.org">Michael Boman</mail> +</author> +<author title="Contributors"> + <mail link="kzaraska@student.uci.agh.edu.pl">Krzysztof Zaraska</mail> +</author> + +<abstract> + This guide will assist you in setting up the Prelude Intrustion Detection System along with the rules needed to make it useful. +</abstract> +<version>0.0.99</version> +<date>17 Jul 2003</date> +<chapter> + <title>About Prelude</title> + <section> + <title>Background Information</title> + <body> + <p> + Prelude was founded and writen by Yoann Vandoorselaere in 1998. Many others have also greatly contributed to it. + </p> + <p> + Prelude is a hybrid intrustion detection system that will detect and monitor security instrusions, whether they happen in an attack mobilized over the Internet or an attack mobilzed locally. The monitoring work that Prelude does is made possible via an LML (Log Monitoring Lackey). Prelude can also utilize the rulesets from intrusion detection systems such as Snort. + </p> + </body> + </section> + <section> + <title>What Are the Components?</title> + <body> + <ul><li><path>prelude-manager</path> : The manager is the place where all the main logging is done. When the manager receives a signal from the sensors, it logs the signal so the user can investigate. Logging can either be done to a file or to a datebase such as MySQL. The latter is the recommended solution.</li></ul> + <ul><li><path>prelude-nids</path> : NIDS is a plugin for Prelude and stands for Network Intrusion Detection System. The prelude-nids package should definately be used along side Prelude proper, but is not mandatory. The NIDS package also provides for functionality like that of <uri link="http://snort.org">Snort</uri></li></ul> + <ul><li><path>prelude-lml</path> : The LML stands for Log Monitoring Lackey. Like the NIDS, it is also a sensor. The LML watches your logfiles and looks for anything out of the ordinary. Should abnormalities be found, an alert is sent to the manager.</li></ul> + <ul><li><path>libprelude</path> : libprelude provides for the libraries necessary in order for the manager to be able to talk to the other plugins. It also provides the sensors with extra features.</li></ul> + <ul><li><path>piwi</path> : PIWI stands for Prelude Intrusion (Detection System) Web Interface. The title pretty much describes the said package; it is an interface powered by perl that can help the end user manage their rules and see when attacks are happening or have happened.</li></ul> + </body> + </section> +</chapter> +<chapter> + <title>Installing Prelude</title> + <section> + <title>Emerging the Packages</title> + <body> + <p> + We will now begin by adding <path>ssl</path> to our <path>make.conf</path>, then emerging each of the packages described above. + </p> + <pre caption="/etc/make.conf"> +<comment>You do not have to delete other entries from your USE, just add ssl.</comment> +USE="ssl" +</pre> + <pre caption="Starting the Emerges"> +<comment>Emerging the libraries.</comment> +# <i>emerge libprelude</i> +<comment>Now for the log lackey.</comment> +# <i>emerge prelude-lml</i> +<comment>Installing the Network Intrustion Detection System</comment> +# <i>emerge prelude-nids</i> +<comment>Now for the most important component: The manager.</comment> +# <i>emerge prelude-manager</i> +<comment>Lastly, we will install PIWI.</comment> +# <i>emerge piwi</i> +</pre> + </body> + </section> +</chapter> +<chapter> + <title>Configuring Prelude</title> + <section> + <title>Setting up the Manager</title> + <body> + <p> + We will now edit the Manager's main configuration file, <path>prelude-manager.conf</path>. Two of the most important settings are for changing where Prelude will listen. For instance, if you have two IPs but only one Prelude to listen on one of them, you would supply the said IP in the configuration.</p> + <pre caption="/etc/prelude-manager/prelude-manager.conf"> +# Sensor Server is listening on any IP +sensors-srvr = 0.0.0.0; +# Admin Server is listening on any IP +admin-srvr = 0.0.0.0; +</pre> + </body> + </section> + <section> + <title>Setting up the Database</title> + <body> + <p> + If you want to set up Prelude to work with its backend being a database like MySQL or PostgreSQL (and believe me, you do), then you will want to continue with this section. If you really and truly would rather use plaintext logging, then you can skip this section. + </p> + <impo>Your SQL server, whether it be MySQL or PostgreSQL, needs to be running before you proceed.</impo> + <pre caption="Creating the Database"> +# <i>/usr/bin/prelude-manager-db-create.sh</i> + +Prelude Database Support Installation +===================================== + +*** Phase 0/7 *** + +Warning: if you want to use database support with prelude + You should dedicate the database for this job only. + +So if you ever have a database running for another job + please think about taking it away, because this script + will install prelude as a dedicated database and you + could meet some troubles with your old bases. + +<comment>Since we want database support, we are going to say "y" here.</comment> +Do you want to install a dedicated database for prelude ? + (y)es / (n)o : y + + +*** Phase 1/7 *** + +<comment>Here you can either chose to have your database be MySQL (mysql) or +PostgreSQL (pgsql). I'll be choosing MySQL.</comment> +Enter the type of the database [mysql|pgsql]: mysql + + +*** Phase 2/7 *** + +<comment>Unless you are going to be running the MySQL server on a different +box than Prelude, just hit ENTER here to choose "localhost".</comment> +Enter the name of the host where the database is running [localhost]: + + +*** Phase 3/7 *** + +<comment>3306 is the default port for MySQL, so unless you plan on running +the MySQL daemon on a different port, then just hit ENTER here.</comment> +Enter the port where the database is running [3306]: + + +*** Phase 4/7 *** + +<comment>Hit ENTER here to have the database that stores all the information +that Prelude keeps track of be named "prelude".</comment> +Enter the name of the database that should be created to stock alerts [prelude]: + +*** Phase 5/7 *** + +<comment>You can go ahead and hit ENTER here unless you have your MySQL super-user +set up under a different name.</comment> +This installation script has to connect to your mysql database in order to creat +e a user dedicated to stock prelude's alerts +What is the database administrative user ? [root]: + +We need the password of the admin user "root" to log on the database. +By default under mysql, root has an empty password. +Please enter a password: +Please confirm entered password: + +*** Phase 6/7 *** + +We need to create a database user account that will be used by the Prelude Manag +er in order to access the "prelude" database. + +Username to create [prelude] : + +We need to set a password for this special "prelude" account. +This password will have to be used by prelude-manager to access the database. +Please enter a password: +Please confirm entered password: + +*** Phase 7/7 *** + +Please confirm those information before processing : + +Database name : prelude +Database admin user: root +Database admin password: (not shown) + +prelude owner user: prelude +prelude owner password: (not shown) + +Is everything okay ? (yes/no) : yes + +Creating the database prelude... + +Creating user "prelude" for database "prelude", +using "root" to connect to the database. + +Creating tables with /usr/share/prelude-manager/mysql/mysql.sql + +-------------- End of Database Support Installation ------------- +If it succeeded, you should now be able to launch prelude-manager like that : +==> prelude-manager --mysql --dbhost localhost --dbname prelude --dbuser pre +lude --dbpass xxxxxx + +Or you may modify the prelude-manager configuration file (/usr/local/etc/prelude +-manager/prelude-manager.conf by default) in order to launch prelude-manager wit +hout database arguments: +---------- cut here ---> +[MySQL] +# Host the database is listening on. +dbhost = localhost; +# Port the database is listening on. +dbport = 3306; +# Name of the database. +dbname = prelude; +# Username to be used to connect the database. +dbuser = prelude; +# Password used to connect the database. +dbpass = xxxxxx; +<--- cut here ---------- + +Replace xxxxxx by the password you choose for the manager account +----------------------------------------------------------------- + +</pre> + </body> + </section> + <section> + <title>NIDS Configuration</title> + <body> + <p> + Now we just need to set up NIDS so it knows which ethernet device to monitor.</p> + <pre caption="/etc/conf.d/prelude-nids"> +<comment>Change eth0 to match the ethernet device to be monitored.</comment> +OPTIONS="-i eth0" +</pre> + </body> + </section> + </chapter> + <chapter> + <title>Installing Sensors</title> + <section> + <title>Prerequisit Configuration</title> + <body> + <p> + We will now be setting up the default configuration for the sensors in the <path>/etc/prelude-sensors/sensors-default.conf</path> file. This will be used globally for the sensors. You can edit the below and then place it in the configuration file. + </p> + <pre caption="/etc/prelude-sensors/sensors-default.conf"> +<comment># Replace this with the IP of the manager.</comment> +manager-addr = 192.168.0.1; +<comment># Here you will want to fill in your full hostname.</comment> +node-name = yourbox.yourdomain.com; +<comment># This is just a plaintext descriptor. You can put almost anything here.</comment> +node-location = Rack 2, Server 5. Monitoring Network A from an SPAN port on switch 28A; +[Node Adress] +<comment># The IP address of the box Prelude is being set up on.</comment> +address = 192.168.0.1; +<comment># The netmask for the box.</comment> +netmask = 255.255.255.0; +</pre> + <p> + We will now be adding our sensors to the manager. There are two ways of setting up the manager to talk to the sensors: via an SSL encrypted connection and via an unencrypted connection. The only time when you will want to opt for the latter is when the manager and the sensor are on the same box.</p> + </body> + </section> + <section> + <title>Installing the NIDS Sensor</title> + <body> + <p> + We will now run the necessary commands to set up the SSL connection. + </p> + <pre caption="Setting Up the Encrypted Connection"> +# <i>manager-adduser</i> + +No Manager key exist... Building Manager private key... + +<comment>How many bits should the encryption be? I would recommend just hitting +ENTER here.</comment> +What keysize do you want [1024] ? + + +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + +<comment>Here you can hit ENTER again to select a key that does not expire.</comment> +Key is valid for [0] : + + +Key length : 1024 +Expire : Never +<comment>Granted everything is okay, type in "yes" and hit enter.</comment> +Is this okay [yes/no] : yes + + +Generating a 1024 bit RSA private key... +................++++++ +...........................++++++ +Writing new private key to '/etc/prelude-manager/prelude-manager.key'. +Adding self signed Certificate to '/etc/prelude-manager/prelude-manager.key' + + +<comment>This password is VERY important. Do NOT lose it until you've completed the sensor-adduser.</comment> +Generated one-shot password is "p=7f6N7+". + +This password will be requested by "sensor-adduser" in order to connect. +Please remove the first and last quote from this password before using it. + +waiting for install request from Prelude sensors... +<comment>Do not close this terminal! Leave it open an open another session to +continue the guide.</comment> +</pre> + <p> + Now open up another terminal if you have not already done so and proceed to add the sensor user. Right now we will be adding the user for the NIDS component to Prelude. + </p> + <impo>Remeber that if both the sensor and the manager are running on the same machine, it is important to specify the machines ethernet IP, not <path>127.0.0.1</path>. If you specify <path>127.0.0.1</path>, <c>sensor-adduser</c> will default to an unencrypted connection.<br /><br />However, if you do not want to use SSL, specify the said IP. + </impo> + <pre caption="Adding the Sensor User"> +<comment> You will want to change "192.168.1.102" if the manager is on a different IP.</comment> +# <i>sensor-adduser -s prelude-nids -m 192.168.1.102 -u 0</i> + + +Now please start "manager-adduser" on the Manager host where +you wish to add the new user. + +Please remember that you should call "sensor-adduser" for each configured +Manager entry. + +<comment>We have already done this; hit ENTER.</comment> +Press enter when done. + +Please use the one-shot password provided by the "manager-adduser" program. + +<comment>Enter that password that I talked about above. I hope you did not lose it ;). +Also, be aware that while I am going to fill in the fields here, the password will +not echo back to you.</comment> +Enter registration one shot password : p=7f6N7+ +Please confirm one shot password : p=7f6N7+ +<comment>If you do not see that the connection suceeded then you closed the terminal +that I told you not to. Remove /etc/prelude-manager/prelude-manager.key and start +again with manager-adduser.</comment> +connecting to Manager host (127.0.0.1:5553)... Succeeded. + + +What keysize do you want [1024] ? 1024 + + +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + +Key is valid for [0] : 0 + + +Key length : 1024 +Expire : Never + +Is this okay [yes/no] : yes +Generating a 1024 bit RSA private key... +...........++++++ +........................................++++++ +Writing new private key to '/etc/prelude-sensors/ssl/prelude-nids-key.0'. +Adding self signed Certificate to '/etc/prelude-sensors/ssl/prelude-nids-key.0' +writing Prelude Manager certificate. +Using already allocated ident for prelude-nids@yourbox: 1057315311. +</pre> + <p> + Now switch back to the terminal with manager-adduser running in it. You should see output that resembles that below. + </p> + <pre caption="manager-adduser Output"> +Connection from 192.168.1.102. +sensor choose to use SSL communication method. +Writing Prelude certificate to /etc/prelude-manager/prelude-sensors.cert +Registration completed. +</pre> + </body> + </section> + <section> + <title>Adding the LML Sensor</title> + <body> + <p> + We will now set up the Log Monitoring Lackey. + </p> + <note>You may realize that there are quite a bit of lines of output "missing" from this example. In fact, the lines of output that are not present in this example go away after the initial <c>manager-adduser</c></note> + <pre caption="Setting up the Manager for the LML"> +# <i>manager-adduser</i> + + +Generated one-shot password is "4;%f7%1Y". + +This password will be requested by "sensor-adduser" in order to connect. +Please remove the first and last quote from this password before using it. + +waiting for install request from Prelude sensors... +</pre> + <p> + Again, switch over to another terminal and proceed with the next example. + </p> + <note> + We will be using the same methods we used in the NIDS example, so the same comments in red from before apply here, too. + </note> + <pre caption="Setting up the LML"> +# <i>sensor-adduser -s prelude-lml -m 192.168.101 -u 0</i> + + +Now please start "manager-adduser" on the Manager host where +you wish to add the new user. + +Please remember that you should call "sensor-adduser" for each configured +Manager entry. + +<comment>Hit enter; we have already started manager-adduser.</comment> +Press enter when done. + + + +Please use the one-shot password provided by the "manager-adduser" program. + +Enter registration one shot password : 4;%f7%1Y +Please confirm one shot password : 4;%f7%1Y +connecting to Manager host (127.0.0.1:5553)... Succeeded. + +What keysize do you want [1024] ? 1024 + + +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + +Key is valid for [0] : 0 + + +Key length : 1024 +Expire : Never + +Is this okay [yes/no] : yes +Generating a 1024 bit RSA private key... +...............++++++ +.++++++ +Writing new private key to '/etc/prelude-sensors/ssl/prelude-lml-key.0'. +Adding self signed Certificate to '/etc/prelude-sensors/ssl/prelude-lml-key.0' +writing Prelude Manager certificate. +Using already allocated ident for prelude-lml@yourbox: 1057887742. +</pre> + </body> + </section> + </chapter> + <chapter> + <title>Post Installation</title> + <section> + <title>Testing the Manager</title> + <body> + <p> + On the manager box, start the Prelude manager in the foreground. + </p> + <pre caption="Starting the Manager"> +# <i>prelude-manager</i> +- Initialized 2 reporting plugins. +- Initialized 1 database plugins. +- Subscribing Prelude NIDS data decoder to active decoding plugins. +- Initialized 1 decoding plugins. +- Initialized 0 filtering plugins. +- Subscribing TextMod to active reporting plugins. +- sensors server started (listening on 127.0.0.1:5554). +</pre> + <p> + Now go ahead and switch over to the sensor box. We will test the communication by using the NIDS sensor. + </p> + <pre caption="Starting the NIDS Sensor"> +<comment>Remember to change the manager address if it differs from the example.</comment> +# <i>prelude-nids -i eth0 --manager-addr 127.0.0.1</i> +- Initialized 3 protocols plugins. +- Initialized 5 detections plugins. + +- RpcMod subscribed for "rpc" protocol handling. +- TelnetMod subscribed for "telnet" protocol handling. +- HttpMod subscribed for "http" protocol handling. +- Done loading Unicode table (663 Unichars, 0 ignored, 0 with errors) +- ScanDetect subscribed to : "[TCP,UDP]". +- ArpSpoof subscribed to : "[ARP]". +/etc/prelude-nids/ruleset/web-misc.rules (7) Parse error: Unknow key regex +/etc/prelude-nids/ruleset/web-misc.rules (65) Parse error: Unknow key regex +- Signature engine added 890 and ignored 2 signature. +- Connecting to Unix prelude Manager server. +- Plaintext authentication succeed with Prelude Manager. + +- Initializing packet capture. +</pre> + <p> + Make sure that your output looks relatively the same. Let us make sure that we have the important output displaying correctly. + </p> + <pre caption="Important output from NIDS"> +- Connecting to Unix prelude Manager server. +- Plaintext authentication succeed with Prelude Manager. +</pre> + <pre caption="Important output from the manager after we have started NIDS"> +[unix] - accepted connection. +[unix] - plaintext authentication succeed. +[unix] - sensor declared ident 578232824809457160. +</pre> + <p> + If you do not see those two sets of output, make sure that the manager is listening on the right IP and that the manager address is supplied properly for NIDS. + </p> + </body> + </section> + </chapter> + <chapter> + <title>Running and Managing Prelude</title> + <section> + <title>Starting up the Prelude Daemons</title> + <body> + <p> + There are several init scripts that control the different parts to Prelude, so we will want to start those up now. + </p> + <pre caption="Starting the Prelude Daemons"> +<comment>First, we will start up the manager.</comment> +# <i>/etc/init.d/prelude-manager start</i> +<comment>Next, it is time to start the NIDS</comment> +# <i>/etc/init.d/prelude-nids start</i> +<comment>And finally, we will start up the LML.</comment> +# <i>/etc/init.d/prelude-lml start</i> +</pre> + <p> + Most likely, you are going to want Prelude and its components to start up when you boot up the computer. In order to achieve this, we will add the necessary components to the default runlevel. + </p> + <pre caption="Adding the Daemons to the Run Level"> +# <i>rc-update add prelude-manager default</i> +# <i>rc-update add prelude-nids default</i> +# <i>rc-update add prelude-lml default</i> +</pre> + </body> + </section> + <section> + <title>Installing PIWI</title> + <body> + <p> + The first thing we will do to get PIWI working is emerge it. + </p> + <pre caption="Emerging PIWI"> +# <i>emerge piwi</i> +</pre> + <p> + We will now follow the instructions that the emerge process gives us + </p> + <impo>Depending on what version of Apache you are running, the following file names may vary. If you are using Apache2, the files will be located in <path>/etc/apache2/conf</path> and the files will be named differently. Usually, the file names will differ only by a present "2" that is not there in the Apache1 file names. For example, <path>apache.conf</path> becomes <path>apache2.conf</path> in Apache2.</impo> + <pre caption="/etc/apache/conf/apache.conf"> +<comment>The best place for this line is probably at the end of the file.</comment> +Include /etc/piwi/piwi-apache.conf +</pre> + <p>Now we will tell Apache to load the PIWI specific configuration directives. If we were to skip this step, when you go to the location of your website with the PIWI files, the Perl scripts will likely just show up as plain text.</p> + <note>If you are already loading other Apache modules, you merely have to add <path>-D PIWI</path> rather than replacing the whole <path>APACHE_OPTS</path> line.</note> + <pre caption="/etc/conf.d/apache"> +APACHE_OPTS="-D PIWI" +</pre> + <p> + Next, we need to edit the PIWI configuration file to match our MySQL database settings that we used for Prelude. + </p> + <pre caption="/etc/piwi/config.pl"> +<comment>Edit the next two lines to suit your setup.</comment> +$conf{'dblogin'}='prelude'; +$conf{'dbpasswd'}='dbpass'; +</pre> + <p> + All that is left to do is start up Apache and check to make sure that the PIWI scripts are being processed correctly. + </p> + <pre caption="Starting Apache"> +# <i>/etc/init.d/apache start</i> +</pre> + <p> + Now point your browswer to <path>http://yoursite/piwi</path> and you should be greeted by a Web interface. + </p> + </body> + </section> + </chapter> + <chapter> + <title>Credits</title> + <section> + <title>Works Cited</title> + <body> + <ul><li>Collective Work. PreludeIntrusionDetectionSystem - Gentoo Wiki.</li></ul> + <ul><li><mail link="polombo@cartel-securite.fr">Polombo, Daniel</mail>. <uri link="http://prelude-ids.org/article.php3?id_article=6">Prelude Hybrid IDS</uri>.</li></ul> + </body> + </section> + </chapter> +</guide> diff --git a/xml/primer.xml b/xml/primer.xml new file mode 100644 index 0000000..988a21c --- /dev/null +++ b/xml/primer.xml @@ -0,0 +1,268 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="/proj/en/hardened/primer.xml"> + <title>Introduction to Hardened Gentoo</title> + <author title="Author"> + <mail link="method@gentoo.org">Joshua Brindle</mail> + </author> + <author title="Contributor"> + <mail link="tocharian@gentoo.org">Adam Mondl</mail> + </author> + <author title="Editor"> + <mail link="solar@gentoo.org">Ned Ludd</mail> + </author> + <abstract>A Primer on Hardened Gentoo.</abstract> + <version>1.2</version> + <date>2007-02-07</date> + <chapter> + <title>Introduction</title> + <section> + <body> + <p> + This guide is meant for anyone unsure about the offerings of the + Hardened Gentoo project, how to use them together, and what their + respective roles in the project are. + </p> + <p> + The basic security principle that we emphasize is layers of security. + Layers are fundamental in ensuring a users machine is not compromised, + and if it is, minimizing the damages done. By combining a series of + dissimilar, though security related technologies, we make an attacker + jump through additional hoops before a compromise may occur. For this + reason we always recommended that you decide what your specific needs + are and combine those solutions to protect your system. We will try to + explain the options and how they can be used together in this + document. + </p> + <p> + Hardened Gentoo is not a product or solution in itself, it is merely a + project with a group of developers all working toward the same goal of + very proactive security. The sub-projects contained in Hardened Gentoo + aren't related in any more way than they are hosted within the same + project. You might think of it as the same way KDE and GNOME are both + part of the desktop project, and both have a common goal but are + otherwise unrelated to each other. + </p> + <note> + Asking for help installing or support of your 'Hardened Gentoo' machine + is not clear and should always be clarified by saying you have a + SELinux problem, PIE/SSP problem, and so on. + </note> + </body> + </section> + </chapter> + <chapter> + <title>Technologies Offered</title> + <section> + <title>PaX</title> + <body> + <p> + At the heart of the project is PaX. PaX is a kernel patch + that allows you to protect against buffer and heap overflows and + similar attacks. PaX is your first line of defense. + </p> + + <p>Because of badly + written software you are always at risk of a compromise because of + buffer and heap overflows. Buffer and Heap overflows are the result of + unchecked bounds in user input in applications. When an attacker has + the ability to give input to an application that is inserted into + memory but not checked there exists the possibility of an overflow. + Lower level programming languages like C and C++ do not automatically + protect from overruns, and the end result is that when a buffer is + overrun adjacent executable code can be overwritten with input from the + user. This would normally cause the application to crash if the users + input isn't understood by the machine. This generally manifests itself + as a page fault because the characters that overrun the buffer into the + executable area will be treated as an address which probably won't + exist. This is the most benign result of an overrun. + </p> + + <p>If the attacker + knows of an overrun, however, they will have the opportunity to add + shellcode to the input and rather than causing the application to crash + it will instead execute the instructions they give. This is done + because shellcode is how instructions are stored in memory for + execution by the processor. Basically shellcode consists of 'opcodes' + which translate to assembly routines. An attacker knows these opcodes + very well and can create shellcode which allows them to do anything + they desire, such as run a root shell and bind it to a port. When this + happens the user won't even be aware that it has because the + application doesn't crash, instead it starts executing the attackers + arbitrary code allowing them to do anything they please. PaX mitigates + this problem by randomly placing each function and buffer in an + application in memory. This is called ASLR or Address Space Layout + Randomization and is the cornerstone of PaX By having random offsets + for functions and buffers the attacker is unable to craft an input + which will guarantee that the shellcode will be executed (and makes it + very difficult since the application will probably crash and be + restarted with new random offsets). ASLR is most useful when used with + PIE (position independent executable) code but also works with standard + executable code, at the cost of overhead. + </p> + + <p>PaX also offers the ability + for executable segments to be executable and not writable, and likewise + writable segments to be writable and not executable. This is called + pageexec. On x86 based processors there is no ability to do this on a + hardware level since the x86 designers collapsed the read and execute + memory flags into 1 to save space. Since a page can either be writable + or readable and executable it is not useful to set buffers as + non-executable since they would no longer be readable. So on x86 PaX + emulates this behavior at a software level, which introduces overhead + but is very helpful for security. + </p> + </body> + </section> + <section> + <title>PIE/SSP</title> + <body> + <p> + In the interest of clarity, while PIE and SSP are generally grouped in + discussion because they are both part of the hardened toolchain, they + are indeed different technologies with different purposes. PIE by itself + provides no additional security, but when combined with PaX in the kernel + provides a powerful tool against overflows. SSP is entirely implemented + in userland and protects against stack smashing attacks without the + assistance of the kernel. Since these are implemented separately and do + different things they are indeed 2 different layers of protection, for + example, one attack that might get past PaX, called ret2libc, would be + blocked by SSP. + </p> + + <p> + We have gone through great lengths to provide users with an easy way to + build the entire userland with PIE code as to take advantage of ASLR + with very little overhead. In addition to PIE our 'hardened' toolchain + also provides SSP or stack smashing protection. SSP protects against + stack smashing by allocating an area outside of buffers and putting a + random, cryptographic canary (or marker) in it. This allows SSP to check + whether the canary was overwritten after any write to the buffer and + allows it to kill the app if it was overwritten. The hardened toolchain + gives users a PIE/SSP userland the easiest possible way. Stages marked + with 'hardened' are standard stages built with PIE and SSP, they do not + include SELinux/RSBAC/grsecurity access controls. + </p> + </body> + </section> + <section> + <title>Mandatory Access Control</title> + <body> + <p> + While PaX is the first layer of protection, perhaps even the second or + third if you have firewalls and/or network intrusion detection, it is + also recommended that you use access control to further secure your system. + It is very important that you realize access control as your <b>last</b> + layer of protection. Access control is very helpful to contain attackers + which already got access to your system, or local users. Currently + Hardened Gentoo supports 3 access control solutions: SELinux, + grsecurity, and RSBAC. + </p> + + <p> + If you wish to use grsecurity you need not worry about which stages to use as grsecurity + requires no userland changes. Simply use the hardened stages and once you are + ready to build a kernel use a grsecurity-enabled kernel such as + hardened-sources. Once your system is up and running you can use + grsecurity's learning mode to build ACL's for your system. + </p> + + <p> + Similar to grsecurity, RSBAC does not require any userland changes but can be + installed after setting up a normal Gentoo installation. RSBAC is supported by + the rsbac-sources kernel. Once your system is running you + can then choose from the different access control models offered by RSBAC + since they are all modules. The RSBAC Gentoo documentation lists the various models + offered and provides more information about each one. + </p> + + <p> + So we've talked about 2 layers that we offer, we have intentions to offer more + and will in the future. Examples of additional layers are intrusion + detection/prevention, which would be first even before PaX. + Encrypted disks and swap which offer protection from 'physical' security + breaches. Auditing, which would allow you to see and act upon risks before + they become a compromise. Encrypted network traffic and strong authentication + are also layers which are very supported in mainline Linux installations and + probably won't be focused upon here. + </p> + </body> + </section> + </chapter> + <chapter> + <title>Resources</title> + <section> + <body> + <table> + <tr> + <th> + Project + </th> + <th> + Project homepage + </th> + <th> + Gentoo project page + </th> + </tr> + <tr> + <ti> + PaX + </ti> + <ti> + <uri link="http://pax.grsecurity.net">http://pax.grsecurity.net</uri> + </ti> + <ti> + <uri link="http://hardened.gentoo.org/pax-quickstart.xml">http://hardened.gentoo.org/pax-quickstart.xml</uri> + </ti> + </tr> + <tr> + <ti> + PIE + </ti> + <ti> + Not Available + </ti> + <ti> + Not Available + </ti> + </tr> + <tr> + <ti> + SSP + </ti> + <ti> + <uri link="http://www.trl.ibm.com/projects/security/ssp/">http://www.trl.ibm.com/projects/security/ssp/</uri> + </ti> + <ti> + Not available + </ti> + </tr> + <tr> + <ti> + SELinux + </ti> + <ti> + <uri link="http://www.nsa.gov/selinux">http://www.nsa.gov/selinux</uri> + </ti> + <ti> + <uri link="http://hardened.gentoo.org/selinux">http://hardened.gentoo.org/selinux</uri> + </ti> + </tr> + <tr> + <ti> + grsecurity + </ti> + <ti> + <uri link="http://www.grsecurity.net">http://www.grsecurity.net</uri> + </ti> + <ti> + <uri link="http://hardened.gentoo.org/grsecurity.xml">http://hardened.gentoo.org/grsecurity.xml</uri> + </ti> + </tr> + </table> +</body> +</section> +</chapter> + +</guide> diff --git a/xml/roadmap.xml b/xml/roadmap.xml new file mode 100644 index 0000000..a998165 --- /dev/null +++ b/xml/roadmap.xml @@ -0,0 +1,310 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link = "roadmap.xml"> +<title>Hardened Gentoo Roadmap</title> +<author title="Author"> + <mail link="tocharian@gentoo.org">Adam Mondl</mail> +</author> +<author title="Editor"> + <mail link="tigger@gentoo.org">Rob Holland</mail> +</author> +<author title="Contributor"> + <mail link="solar@gentoo.org">Ned Ludd</mail> +</author> +<author title="Contributor"> + <mail link="pebenito@gentoo.org">Chris PeBenito</mail> +</author> +<author title="Contributor"> + <mail link="method@gentoo.org">Joshua Brindle</mail> +</author> +<author title="Contributor"> + <mail link="kang@gentoo.org">Guillaume Destuynder</mail> +</author> +<author title="Contributor"> + <mail link="pappy@retired">Alexander Gabert</mail> +</author> +<author title="Contributor"> + <mail link="tseng@retired">Brandon Hale</mail> +</author> + +<abstract> +A roadmap that plots current needs and goals of the +Hardened Gentoo project. +</abstract> + +<version>1.2</version> +<date>2005-11-09</date> + +<chapter> +<title>Where the Hardened Gentoo Project Is Today</title> +<section> +<body> + +<p> +Past Hardened Gentoo work has focused on developing the hardened toolchain into +the more mature, consistent approach that it currently takes. It is +implemented as a patchset for gcc with rules that control object code creation +and linking scenarios. Since the spotlight of development is no longer on the +design aspect of the toolchain, the goals of the Hardened Gentoo Project must +shift accordingly. +</p> + +<p> +Similarly, the access control systems offered by the Hardened Gentoo Project +have continued to mature, and both Grsecurity2 and the latest version of +SELinux are now offered. Recent work by Guillaume Destuynder (kang) has also +introduced RSBAC as another access control system available to Hardened Gentoo +users. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Short-Term Goals</title> +<section> +<title>Hardened Toolchain</title> +<body> + +<p> +Now is the time to take a step back and examine the work that has been done so +far. A review of the current approach that the hardened toolchain takes is +needed. There may be ways to strengthen the current implementation or areas of +code that can be cleaned up to allow changes to be pushed upstream easier. +</p> + +<p> +As a lingering effect of the previous hardened toolchain, many ebuilds +currently filter hardened CFLAGS such as -fPIC and -fstack-protector. Work can +now be devoted to reviewing those packages and seeking alternate solutions for +the filters. Also, the hardened code in flag-o-matic.eclass should be reviewed +and possibly rewritten. +</p> + +</body> +</section> + +<section> +<title>Access Control Systems</title> +<body> + +<p><b>Grsecurity</b></p> + +<ul> +<li> +Documents regarding Grsecurity are currently a major need for Gentoo. The +existing Grsecurity2 document needs to be converted to Handbook XML. Also, a +document describing the RBAC system in more detail is needed. +</li> +</ul> + +<p><b>SELinux</b></p> + +<ul> +<li> +Strengthen and extend current policies. +</li> +<li> +Extend support to more architectures. +</li> +<li> +Policy module support. +</li> +<li> +Additional Daemon Policies. +</li> +</ul> + +<p><b>RSBAC</b></p> + +<ul> +<li> +Bring policy support tool to Gentoo packages. +</li> +<li> +Develop default Gentoo policies with policy support tool. +</li> +<li> +Enhance current documentation, and possibly add documentation about desktop +RSBAC. +</li> </ul> + +</body> +</section> + +</chapter> + +<chapter> +<title>Long-Term Goals</title> +<section> +<title>Documentation</title> +<body> + +<p> +The Hardened Gentoo Project is currently very lacking in documentation. The +hardened toolchain needs to be documented fully, and older documents that have +a relationship to the toolchain need to be updated, such as the SSP, PIE, and PIC +documents. Also, comparative documents should be written to explain the choices +that Hardened Gentoo has made in deciding which security tools to support and +which not to support. +</p> + +</body> +</section> + +<section> +<title>Support More Architectures</title> +<body> + +<p> +A long-term goal of the Hardened Gentoo Project is to support all of the +architectures that are officially supported by Gentoo. The only strong support +that exists at the moment is for x86. +</p> + +<p> +The hardened toolchain supports x86, amd64, and sparc64, and would like to extend +support to ppc, ppc64, s390, and similar architectures. With access to different +kinds of hardware, hardened support can slowly be extended to those architectures +as well. +</p> + +</body> +</section> + +<section> +<title>Expand the Hardened Team</title> +<body> + +<p> +There will always be unfinished tasks for the Hardened Team. Users who take a +proactive approach to finding places for improvement and filling in the holes +will be noticed and probably recruited. Current Hardened Team members will be +responsible for training new developers to fill new roles. If you are +interested in helping out, stop by the IRC channel and let someone know what +you are interested in and what you will be doing about it. Input/peer review +should always be welcome as it helps everyone out in the long run. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Roadmap Tracking</title> +<section> +<title>Hardened Toolchain</title> +<body> + +<table> + <tr> + <th>Description</th><th>Coordinator(s)</th><th>Status</th> + </tr> + <tr> + <ti>x86 Support</ti><ti>solar</ti><ti>Complete</ti> + </tr> + <tr> + <ti>amd64 Support</ti><ti>solar,r2d2</ti><ti>In experimental</ti> + </tr> + <tr> + <ti>sparc32 Support</ti><ti></ti><ti>Unassigned</ti> + </tr> + <tr> + <ti>sparc64 Support</ti><ti></ti><ti>Stalled</ti> + </tr> + <tr> + <ti>ppc Support</ti><ti></ti><ti>In testing</ti> + </tr> + <tr> + <ti>ppc64 Support</ti><ti>solar,dostrow</ti><ti>seed stage built</ti> + </tr> + <tr> + <ti>s390 Support</ti><ti></ti><ti>Unassigned</ti> + </tr> + <tr> + <ti>hppa Support</ti><ti></ti><ti>Not supported</ti> + </tr> + <tr> + <ti>arm Support</ti><ti></ti><ti>Unassigned (uclibc only)</ti> + </tr> + <tr> + <ti>mips Support</ti><ti></ti><ti>Unassigned (uclibc only)</ti> + </tr> +</table> + +</body> +</section> + +<section> +<title>SELinux</title> +<body> + +<table> + <tr> + <th>Description</th><th>Coordinator(s)</th><th>Status</th> + </tr> + <tr> + <ti>Strengthen and extend the current policies</ti><ti>pebenito/kaiowas</ti><ti>In Progress</ti> + </tr> + <tr> + <ti>Extend support to more architectures</ti><ti>pebenito</ti><ti>In Progress</ti> + </tr> + <tr> + <ti>Policy module support</ti><ti>pebenito</ti><ti>In Progress</ti> + </tr> + <tr> + <ti>Additional Daemon Policies</ti><ti>pebenito/kaiowas</ti><ti>In Progress</ti> + </tr> +</table> +</body> +</section> + +<section> +<title>RSBAC</title> +<body> + +<table> + <tr> + <th>Description</th><th>Coordinator(s)</th><th>Status</th> + </tr> + <tr> + <ti>Bring policy support tool to Gentoo packages.</ti><ti>kang</ti><ti>In Progress</ti> + </tr> + <tr> + <ti>Enhance RSBAC Documentation</ti><ti></ti><ti>Unassigned</ti> + </tr> +</table> + +</body> +</section> + +<section> +<title>Documentation</title> +<body> + +<table> + <tr> + <th>Description</th><th>Coordinator(s)</th><th>Status</th> + </tr> + <tr> + <ti>Comparative analysis of security approaches taken by distributions.</ti> + <ti>Dave Monnier</ti><ti>In Progress</ti> + </tr> + <tr> + <ti>Rework Grsecurity Documentation</ti><ti></ti><ti>Unassigned</ti> + </tr> + <tr> + <ti>Update/Rewrite Propolice Documentation</ti><ti>Adam Mondl</ti><ti>In Progress</ti> + </tr> + <tr> + <ti>Document the Hardened Toolchain</ti><ti></ti><ti>Unassigned</ti> + </tr> +</table> + +</body> +</section> +</chapter> + +</guide> diff --git a/xml/rsbac/CVS/Entries b/xml/rsbac/CVS/Entries new file mode 100644 index 0000000..17d2fb8 --- /dev/null +++ b/xml/rsbac/CVS/Entries @@ -0,0 +1,6 @@ +/index.xml/1.10/Mon Aug 11 01:55:38 2008// +/intro.xml/1.1/Fri Sep 17 23:02:28 2004// +/overview.xml/1.6/Wed Oct 12 08:24:42 2005// +/quickstart.xml/1.11/Tue Jul 4 20:08:05 2006// +/transition.xml/1.1/Wed Feb 15 16:22:08 2006// +D diff --git a/xml/rsbac/CVS/Repository b/xml/rsbac/CVS/Repository new file mode 100644 index 0000000..1c5b220 --- /dev/null +++ b/xml/rsbac/CVS/Repository @@ -0,0 +1 @@ +gentoo/xml/htdocs/proj/en/hardened/rsbac diff --git a/xml/rsbac/CVS/Root b/xml/rsbac/CVS/Root new file mode 100644 index 0000000..da304d3 --- /dev/null +++ b/xml/rsbac/CVS/Root @@ -0,0 +1 @@ +:pserver:anonymous@anoncvs.gentoo.org/var/cvsroot diff --git a/xml/rsbac/index.xml b/xml/rsbac/index.xml new file mode 100644 index 0000000..8247dad --- /dev/null +++ b/xml/rsbac/index.xml @@ -0,0 +1,96 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?> +<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> +<!DOCTYPE project SYSTEM "/dtd/project.dtd"> +<project> + +<name>RSBAC</name> +<longname>Rule Set Based Access Control</longname> + +<description> +RSBAC is Mandatory Access Control security system based on the GFAC framework logic. It includes standard models, like the Role Compatibility, Access Control Lists and Mandatory Access Control. RSBAC enforces access control rules on your operating system. +</description> + +<longdescription><p> +This project manages the RSBAC support within Gentoo. This includes providing kernels with RSBAC support (loosely based on the hardened-sources), administration utilites to manage and write strong Gentoo-specific policies. RSBAC works on many different architectures using both the 2.4 or 2.6 Linux kernels. +</p></longdescription> + +<goals><p> +This project aims to make RSBAC available to more users, improve it, and improve it's integration in Gentoo Linux. We are developing a policy for the base system and the common daemons, as well as other popular programs. Currently we are mostly targetting servers, but desktops will also be supported in the future. +The required tool for the policies is still being developped. +</p></goals> + +<extrachapter position="goals"> +<title>What is RSBAC?</title> +<section><body> +<p> + <uri link="http://www.rsbac.org/">RSBAC</uri> (Rule Set Based Access Control) is free Open Source (GPL) Linux kernel security extension. RSBAC's main concept is modularity. It uses <uri link="http://rsbac.org/documentation:different_models">several</uri> well-known and new security models, including MAC, ACLs, PaX and RC among a few others. RSBAC has control over individual users and program network accesses using any combination of the possible security models. It is also as extensible as it is modular: you can write your own models for runtime registration. Finally, RSBAC provides an excellent support for the most newest stable and development Linux kernels.It is in production use from January 2000 and has proven to be very stable. You are also suggested to read the more detailled <uri link="http://www.gentoo.org/proj/en/hardened/rsbac/overview.xml">overview</uri>. +</p> +<p> + However, RSBAC itself is not a complete security solution by itself: it only gives the possibility of applying security models. Fortunately, it works well with other Hardened projects to bring you a complete solution. +</p> +</body></section> +</extrachapter> + + +<extraproject name="x86"> + Support for the x86 architecture. +</extraproject> +<extraproject name="Documentation"> + Full documentation for the RSBAC project. +</extraproject> + +<plannedproject name="Base Policy"> + RSBAC policy for the core system, including users, administrators, and + daemons in the system profile. +</plannedproject> +<plannedproject name="Desktop"> + RSBAC support on desktops. +</plannedproject> + +<resource link="http://www.gentoo.org/proj/en/hardened/rsbac/overview.xml">RSBAC Overview</resource> +<resource link="http://www.gentoo.org/proj/en/hardened/rsbac/quickstart.xml">RSBAC Quickstart</resource> + +<extrachapter position="resources"> +<title>How Do I Use This?</title> +<section> +<body> +<p> + RSBAC can be installed new on a system by following the above install guide + for your architecture. If there is not an install guide for your architecuture + yet, it is still possible to install by following the <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo Handbook</uri>. + When the system is installed, convert it to RSBAC by using the + Quickstart Guide. + It is suggested that you use the Hardened profile or use "hardened pie" as your USE flags during this installation. + +</p> +<p> + Converting a preexisting Gentoo installation to RSBAC can be done by + following the Quickstart Guide. +</p> +</body> +</section> +</extrachapter> + +<extrachapter position="bottom"> +<title>I Want to Participate</title> +<section> +<body> +<p> + To participate in the RSBAC project first join the mailing list at + <c>gentoo-hardened@gentoo.org</c>. Then ask if there are plans to support + something that you are interested in, propose a new subproject that you are + interested in or choose one of the planned subprojects to work on. You may talk + to the developers and users in the IRC channel <c>#gentoo-hardened</c> on + <c>irc.freenode.net</c> for more information or just to chat about the project + or any subprojects. If you don't have the ability to actively help by + contributing work we will always need testers to use and audit the RSBAC + policies. All development, testing, and productive comments and feedback will + be greatly appreciated. + +</p> +</body> +</section> +</extrachapter> + +</project> diff --git a/xml/rsbac/intro.xml b/xml/rsbac/intro.xml new file mode 100644 index 0000000..71e8463 --- /dev/null +++ b/xml/rsbac/intro.xml @@ -0,0 +1,77 @@ +<?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE guide SYSTEM +"/dtd/guide.dtd"> + +<guide link="intro.xml"> + +<title>Rule Set Based Access Control (RSBAC) for Linux - +Introduction</title> + +<author title="Author"> + <mail link="ao@rsbac.org">Amon Ott</mail> +</author> <author title="Editor"> + <mail link="albeiro@gentoo.pl">Michal Purzynski</mail> +</author> <author title="Editor"> + <mail link="kang@gentoo.org">Guillaume Destuynder</mail> +</author> <abstract> This document should introduce you to the RSBAC +access control system. </abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license +--> <!-- See http://creativecommons.org/licenses/by-sa/1.0 --> <license/> + +<version>1.0</version> <date>2 June 2004</date> + +<chapter> <title>Introduction</title> <section> <title>Traditional access +control systems and RSBAC</title> <body> + +<p> Traditional access control systems used to be melted into the system +kernel. The actual security policy was deeply connected to the whole +design of the system and hard-coded into the security part, making +modifications to meet changed requirements a difficult task. </p> + +<p> In this work I used a new proposal by L. J. La Padula, based on the +"Generalized Framework for Access Control", which was developed by +a working group led by Marshall Abrams at MITRE. By division of the +functional components they made it possible to simply configure many +different security policies based on well-known and easily extensible +models. </p> + +</body> </section> <section> <title>Implementation</title> <body> + +<p> For the implementation I choosed the Unix Linux variant of Unix, +thanks to it's freely available source code. It is also very stable and +near to both La Padula's example system and also common Unix standards, +making the results easy to transfer to other systems. The package was +named "Rule Set Based Access Control" (RSBAC). </p> + +<p> Using a Unix like system produced the major goal of extending a +weak, discretionary access control by a new, stronger, more flexible +and mandatory control. Instead of encoding it should make the adaption +of security policies possible by administration of several security +modules. Easy addition of other security modules was to be included +as well. </p> + +<p> In this thesis La Padula's proposal is checked, extended, completed +for a real system and at last implemented in it. </p> + +<p> As a special example for the ability of integration Dr. Simone +Fischer-Huebner's complex Privacy Model was chosen, implementing it for +the first time in a real system. Its adaption to my concept was done +together with Simone Fischer-Huebner. </p> + +<p> Placing a focus on Privacy, the extensive logging is done using +pseudonyms that can be changed and read only by security managers or +data protection managers. </p> + +<p> In the end the gain in security and safety is checked against the +ITSEC funtional criteria, extended by two privacy goals. </p> + +</body> </section> </chapter> + +<chapter> <title>References</title> <section> <body> + +<p> <uri>http://www.cs.kau.se/~simone/</uri> +</p> + +</body> </section> </chapter> + +</guide> diff --git a/xml/rsbac/overview.xml b/xml/rsbac/overview.xml new file mode 100644 index 0000000..e205987 --- /dev/null +++ b/xml/rsbac/overview.xml @@ -0,0 +1,275 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="overview.xml"> + +<title>Rule Set Based Access Control (RSBAC) for Linux - Overview</title> + +<author title="Author"> + <mail link="ao@rsbac.org">Amon Ott</mail> +</author> +<author title="Editor"> + <mail link="albeiro@gentoo.pl">Michal Purzynski</mail> +</author> +<author title="Editor"> + <mail link="kang@gentoo.org">Guillaume Destuynder</mail> +</author> + +<abstract> +This document should give you an overview of RSBAC access control system. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> +<license/> + +<version>1.2</version> +<date>11 October 2005</date> + +<chapter> +<title>Key features</title> + +<section> +<body> + +<ul> +<li>Free Open Source (GPL) Linux kernel security extension</li> +<li>Independent of governments and big companies</li> +<li>Several well-known and new security models, including MAC, ACL and RC</li> +<li>Control over individual users and program network accesses</li> +<li>Any combination of models is possible</li> +<li>Easily extensible: write your own model for runtime registration</li> +<li>Supports all the current kernels</li> +<li>Stable for production use</li> +</ul> + +</body> +</section> +</chapter> + +<chapter> +<title>What is RSBAC?</title> +<section> +<body> + +<p> +RSBAC is a flexible, powerful and fast open source access control +framework for current Linux kernels, which has been in stable production +use since January 2000 (version 1.0.9a). The full developement has been done independentely, and no existing access control code has been reused. +</p> + +<p> +The standard package includes a range of access control models like MAC, +RC, ACL (see below). Furthermore, the runtime registration facility +(REG) makes it easy to implement your own access control model as a kernel +module and get it registered at runtime. +</p> + +<p> +The RSBAC framework is based on the <uri link="http://www.acsac.org/secshelf/book001/09.pdf">Generalized Framework for Access Control (GFAC)</uri> by Abrams and LaPadula. All security relevant system calls +are extended by security enforcement code. This code calls the central +decision component, which in turn calls all active decision modules and +generates a combined decision. This decision is then enforced by the +system call extensions. +</p> + +<p> +Decisions are based on the type of access (request type), the access +target and on the values of attributes attached to the subject calling and +to the target to be accessed. Additional independent attributes can be +used by individual modules, e.g. the privacy module (<uri link="#doc_chap3_sect4">PM</uri>). All attributes +are stored in fully protected directories, one on each mounted device. +Thus changes to attributes require special system calls. +</p> + +<p> +All types of network accesses can be controlled +individually for all users and programs. This gives you full control over +their network behaviour and makes unintended network accesses easier to +prevent and detect. +</p> + +<p> +As all types of access decisions are based on general decision requests, +many different security policies can be implemented as a decision module. +Apart from the builtin models shown below, the optional Module +Registration (REG) allows for registration of additional, individual +decision modules at runtime. +</p> + +</body> +</section> +</chapter> + +<chapter> +<title>Implemented models</title> +<section> +<body> + +<p> +In the RSBAC version 1.2.5, the following modules are included. Please +note that all modules are optional. +</p> + +</body> +</section> + +<section> +<title>MAC</title> +<body> +<p> +Bell-LaPadula Mandatory Access Control +</p> +</body> +</section> + +<section> +<title>UM</title> +<body> +<p> +The User Management in RSBAC is kernel based and complements or totally replace +Linux’s subsystem. +Administration of users is enforced with granularity and flexibility. +</p> +</body> +</section> + +<section> +<title>PM</title> +<body> +<p> +Privacy Model. <uri link="http://www.cs.kau.se/~simone/">Simone Fischer-Huebner</uri>'s Privacy Model in its +first implementation. See RSBAC <uri link="http://rsbac.org/doc/media/niss98.php">paper on PM implementation</uri> +for the National Information Systems Security Conference (NISSC 98) +</p> +</body> +</section> + +<section> +<title>Dazuko</title> +<body> +<p> +This is not really an access control model, but rather a system protection module against +malware. Execution and reading of malware infected files can be prevented. +</p> +</body> +</section> + +<section> +<title>FF</title> +<body> +<p> +File Flags. Provide and use flags for dirs and files, currently +execute_only (files), read_only (files and dirs), search_only +(dirs), secure_delete (files), no_execute (files), add_inherited +(files and dirs), no_rename_or_delete (files and dirs, no +inheritance) and append_only(files and dirs). Only FF security +officers may modify these flags. +</p> +</body> +</section> + +<section> +<title>RC</title> +<body> +<p> +Role Compatibility. Defines roles and types for each target type +(file, dir, dev, ipc, scd, process). For each role, compatibility +to all types and to other roles can be set individually and with +request granularity. For administration there is a fine grained +separation-of-duty. Granted rights can have a time limit. Please +also refer to the <uri link="http://rsbac.org/doc/media/rc-nordsec2002/index.html">Nordsec 2002 RC Paper</uri> for the detailed model +design and specification. +</p> +</body> +</section> + +<section> +<title>AUTH</title> +<body> +<p> +Authorization enforcement. Controls all CHANGE_OWNER requests for +process targets, only programs/processes with general setuid +allowance and those with a capability for the target user ID may +setuid. Capabilities can be controlled by other +programs/processes, e.g. authentication daemons. +</p> +</body> +</section> + +<section> +<title>ACL</title> +<body> +<p> +Access Control Lists. For every object there is an Access Control +List, defining which subjects may access this object with which +request types. Subjects can be of type user, RC role and ACL +group. Objects are grouped by their target type, but have +individual ACLs. If there is no ACL entry for a subject at an +object, rights are inherited from parent objects, restricted by an +inheritance mask. Direct (user) and indirect (role, group) rights +are accumulated. For each object type there is a default ACL on +top of the normal hierarchy. Group management has been added in +version 1.0.9a. Granted rights and group memberships can have a +time limit. +</p> +</body> +</section> + +<section> +<title>CAP</title> +<body> +<p> +Linux Capabilities. For all users and programs you +can define a minimum and a maximum Linux capability set ("set of +root special rights"). This lets you e.g. run server programs as +normal user, or restrict rights of root programs in the standard +Linux way. +</p> +</body> +</section> + +<section> +<title>JAIL</title> +<body> +<p> +Process Jails. This module adds a new system call +rsbac_jail, which is basically a superset of the FreeBSD jail +system call. It encapsulates the calling process and all +subprocesses in a chroot environment with a fixed IP address and a +lot of further restrictions. +</p> +</body> +</section> + +<section> +<title>RES</title> +<body> +<p> +Linux Resources. For all users and programs you can +define a minimum and a maximum Linux process resource set (e.g. +memory size, number of open files, number of processes per user). +Internally, these sets are applied to the standard Linux resource +flags. +</p> +</body> +</section> + +<section> +<body> +<p> +All decision modules are described in detail on the module description +page. +</p> + +<p> +A general goal of RSBAC design has been to some day reach the (obsolete) +Orange Book (TCSEC) B1 level. +</p> + +</body> +</section> +</chapter> + +</guide> + diff --git a/xml/rsbac/quickstart.xml b/xml/rsbac/quickstart.xml new file mode 100644 index 0000000..092f1de --- /dev/null +++ b/xml/rsbac/quickstart.xml @@ -0,0 +1,319 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<guide link="/proj/en/hardened/rsbac/quickstart.xml"> + +<title>Rule Set Based Access Control (RSBAC) for Linux - Quickstart</title> + +<author title="Author"> + <mail link="albeiro@gentoo.pl">Michal Purzynski</mail> +</author> <author title="Editor"> + <mail link="kang@gentoo.org">Guillaume Destuynder</mail> +</author> + +<abstract>This document will guide you through the installation of the +RSBAC on Gentoo Linux</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license +--> <!-- See http://creativecommons.org/licenses/by-sa/1.0 --> <license/> + +<version>1.7</version> +<date>15 February 2006</date> + +<chapter> <title>Introduction</title> <section> <body> + +<p> This guide will help you to install RSBAC on +Gentoo Linux. It is assumed that the users have read +the <uri link="intro.xml">Introduction</uri> and the <uri +link="overview.xml">Overview</uri> already, so that they knows what is +RSBAC and its main concepts. </p> + +</body> </section> </chapter> + +<chapter> <title>Installation of the RSBAC enabled kernel</title> +<section> <title>Emerging the RSBAC kernel</title> <body> + +<p> This step is pretty straight forward, thanks to the way Gentoo +handles kernel installations. Start by emerging the rsbac-sources +kernel from your portage. </p> + +<note> There are two rsbac-sources kernel available: +one is for the 2.4 kernel branch, the other is for the newer 2.6 kernel branch. +</note> + +<pre caption="RSBAC kernel installation (using the default profile and 2.6 kernel)"> +# <i>emerge rsbac-sources</i> +</pre> + +<pre caption="RSBAC kernel installation (using the 2.4 kernel, since Gentoo profile 2005.0)"> +# <i>rm /etc/make.profile</i> +# <i>ln -s /usr/portage/profiles/default-linux/x86/2005.0/2.4/ /etc/make.profile</i> +# <i> echo "sys-kernel/hardened-sources rsbac" >> /etc/portage/package.use</i> +# <i>emerge hardened-sources</i> +</pre> + +<impo> It is advised to enable softmode on your first RSBAC kernel. It +allows you to turn off the RSBAC enforcement in one reboot, for testing +or in case something goes wrong. Only turn it off once you are sure of +what you are doing, or of course, for a production kernel. </impo> + +</body> </section> <section> <title>Configuring the RSBAC kernel</title> +<body> + +<p> We will now configure the kernel. It is recommended that you +enable the following options, in the "Rule Set Based Access Control +(RSBAC)" category: </p> + +<pre caption="Configuring and compiling the RSBAC kernel"> +<comment>Under "General RSBAC options"</comment> +[*] RSBAC proc support +[*] Check on init +[*] Support transactions +[*] Randomize transaction numbers +[*] RSBAC debugging support +(400) RSBAC default security officer user ID + +<comment>Under "User management"</comment> +[*] User management +<comment>Be sure to enable SHA1 in the Crypto API +Under "Cryptographic options" of the general kernel configuration, tick +[*] SHA1 digest algorithm +</comment> +[*] Use Crypto API Digest SHA1 (NEW) + +<comment>Under "RSBAC networking options"</comment> +[*] RSBAC network support +[*] Net device control +[ ] Treat virtual devices as individuals +[*] Individual network device logging +[*] Net object control (sockets) +[*] Control UNIX address family +[*] Also intercept network object read and write +[*] Individual network object logging + +<comment>(Do not turn on "RSBAC Maintenance Kernel", use softmode instead)</comment> + +<comment>Under "Decision module (policy) options"</comment> +[*] Support for Registration of decision modules (REG) +[*] Build REG sample modules +---------------------------- +[*] RSBAC support for DAZuko policy <comment>(For malware/antivirus scanning)</comment> +DAZ Policy Options ---> + (604800) Scanning result lifetime in seconds + +<comment>For each different policy/module you support you should check it's protection for AUTH module +and User Management module</comment> +[*] RSBAC support for FF policy +[*] RSBAC support for RC policy +[*] RSBAC support for AUTH policy +<comment>Please turn learning option off on production kernels. It is only used while setting up your RSBAC system.</comment> +AUTH Policy Options ---> + [*] AUTH learning mode support +[*] RSBAC support for ACL policy +[*] RSBAC support for Linux Caps (CAP) policy +[*] RSBAC support for JAIL policy +[*] RSBAC support for PAX policy +[*] RSBAC support for System Resources (RES) policy + +<comment>Under "Softmode and switching"</comment> +[ ] RSBAC policies switchable +[*] RSBAC soft mode <comment>(Turn that off on production kernels)</comment> +[*] Individual module softmode support + +<comment>Under "Logging": all except "Log to remote UDP network socket" +unless you want to log to remote machine</comment> + +<comment>Under "RSBAC symlink redirection"</comment> +[*] RSBAC symlink redirection +[*] Add remote IP address +[*] Add user ID number +[*] Add RC role number + +<comment>Under "Other RSBAC options"</comment> +[*] Intercept sys_read and sys_write +[*] Intercept Semaphore IPC operations +[*] Control DAC process owner (seteuid, setfsuid) +[*] Hide processes in /proc +[*] Support freezing of RSBAC configuration +[*] RSBAC check sys_syslog +</pre> + +<note> If you plan to run a X Window server (such as X.org or XFree86), +please also enable <c>"[*] X support (normal user MODIFY_PERM access +to ST_ioports)"</c>. +Please also see <uri link="http://www.gentoo.org/proj/en/hardened/hardenedxorg.xml">Using Xorg on Hardened Gentoo</uri></note> + +<p> We will now configure PaX which is a complement of the RSBAC hardened +kernel. It is also recommended that you enable the following options, +in the "Security options ---> PaX" section. </p> + +<pre caption="Configuring PaX kernel options"> +[*] Enable various PaX features +PaX Control ---> + [*] Support soft mode <comment>(Turn that option off on a production kernel)</comment> + [ ] Use legacy ELF header marking + [ ] Use ELF program header marking + Use ELF program header marking MAC system integration (direct) ---> + (X) hook + +Non-executable pages ---> + [*] Enforce non-executable pages (NEW) + [*] Paging based non-executable pages +<comment>(You usually want to select the PAGEEXEC method on x86 since on newer PaXs, +revert to SEGMEXEC if you are having issues)</comment> + [*] Segmentation based non-executable pages (NEW) + [*] Restrict mprotect() + [ ] Disallow ELF text relocations <comment>(This option breaks too much applications as of now)</comment> + +Address Space Layout Randomization ---> + [*] Address Space Layout Randomization + [*] Randomize user stack base + [*] Randomize mmap() base +</pre> + +<note> You should refer to the <uri +link="http://pax.grsecurity.net">PaX</uri> website for more information +about PaX. </note> <note> You must use the RSBAC admin utilities +to manage PaX, instead of chpax or paxctl with your RSBAC kernel. +You will be able to move to the PaX item and set the usual PaX flags. +</note> + +<pre caption="Managing PaX flags"> + # <i>rsbac_fd_menu /path/to/the/target/item</i> + or + # <i>attr_set_file_dir FILE /path/to/the/target/item pax_flags [pmerxs]</i> +</pre> + +<p> You can now compile and install the kernel as you would do with a +normal one concerning the other options. </p> + +<impo> It is strongly suggested to build a second kernel without +the softmode options, neither the AUTH option, in order to use in +a production environment. Only do that once you finished testing and +setting up policies, as it'll remove the possiblity of switching off +the access control system. </impo> + +</body> </section> </chapter> + +<chapter> <title>Installation of the RSBAC admin utilities</title> +<section> <body> + +<p> In order to administrate your RSBAC enabled Gentoo, some userspace +utilites are required. Those are included in the rsbac-admin package +and it needs to be installed. </p> + +<pre caption="Installing the RSBAC admin utilities"> +# <i>emerge rsbac-admin</i> +</pre> + +<p> Once emerged, the package will have created a new user account on your +system (secoff, with uid 400). He will become the security administrator +during the first boot. This is the only user, who is able to change the +RSBAC configuration. He will commonly be called the Security Officer. +</p> + +<impo> Please set-up a <e>secure</e> password for the secoff user. +</impo> + +<pre caption="Setting up a password for the Security Officer"> +# <i>passwd secoff</i> +</pre> + +</body> </section> </chapter> + +<chapter> <title>First boot</title> <section> <body> + +<p> At the first boot, login into the system won't be possible, due to the +AUTH module <e>restricting</e> the programs privileges. To overcome this +problem please boot into softmode using the following kernel parameter +(in your lilo or grub configuration): </p> + +<pre caption="Softmode kernel parameter"> <i>rsbac_softmode</i> </pre> + +<p> The login application is managing user logins on the system. It +needs rights to setuid, which we will now give: </p> <p> Login as the +Security Officer (secoff) and allow logins to be made by enterering the +following command: </p> + +<pre caption="Allowing users to login"> + # <i>rsbac_fd_menu /bin/login</i> + or + # <i>attr_set_fd AUTH FILE auth_may_setuid 1 /bin/login</i> +</pre> + +<p> As an alternative, if softmode isn't enabled, you can also use the +following kernel parameter in order to allow login at boot time: </p> + +<pre caption="Allowing users to login with a kernel parameter"> +<i>rsbac_auth_enable_login</i> +</pre> + +</body> </section> </chapter> + +<chapter> <title>Learning mode and the AUTH module</title> <section> +<title>Creating a policy for OpenSSH</title> <body> + +<p> Because there is almost no policy made yet (except the one generated +during the first boot), the AUTH module does not allows uid changes. +</p> <p> Thanks to the intelligent learning mode there is an easy way to +alleviate this new problem: The AUTH module can automagically generate the +necessary policy by watching services while they start up, and note the +uids they are trying to switch to. For example to teach the AUTH module +about the uids needed by sshd (OpenSSH daemon), do the following: </p> + +<impo>Make sure that sshd or the daemon you will use the learn mode with isn't running already before enabling learn mode.</impo> +<pre caption="Making a policy for sshd, using the learning +mode"> +<comment>Enable the learning mode for sshd</comment> +# <i>attr_set_file_dir AUTH FILE `which sshd` auth_learn 1</i> + +<comment>Start the service</comment> +# <i>/etc/init.d/sshd start</i> + +<comment>Disable the learning mode</comment> +# <i>attr_set_file_dir AUTH FILE `which sshd` auth_learn 0</i> +</pre> + +<note> One should also login to the system before switching the learning +mode off, because sshd will also attempt to change it's uids when the +user will login in. </note> + +<p> Now sshd should be working as expected again, <e>congratulations</e>, +you made your first policy :) The same procedure can be used on every +other daemon you will need. </p> + +<note> As an alternative to enable the learning mode for each daemon +of application you will need, you might want to enable the global +learning mode (which will learn about everything running, globally, +as it name tells). </note> + +<p> You can enable the global learning mode by issuing this kernel +parameter at boot time: </p> + +<pre caption="Enabling the global learning mode"> +<i>rsbac_auth_learn</i> +</pre> + +</body> </section> </chapter> + +<chapter> <title>Further information</title> <section> <body> + +<p> It is also strongly suggested that you subscribe to the <uri +link="http://www.gentoo.org/main/en/lists.xml">gentoo-hardened +mailing-list</uri>. It is generally a low traffic list, +and RSBAC announcements for Gentoo will be available +there. We also recommend you to subscribe to the <uri +link="http://rsbac.org/mailman/listinfo/rsbac/">RSBAC mailing-list</uri>. +Please also check the <uri link="http://www.gentoo.org/proj/en/hardened/hardenedfaq.xml">hardened FAQ</uri> as your questions might already be covered in this document. +</p> + +<table> <tr> + <ti>Links:</ti> + <ti><uri link="http://www.rsbac.org">RSBAC Official site</uri></ti> +</tr> <tr> + <ti>IRC channels:</ti> <ti><uri link="irc://irc.freenode.org/gentoo-hardened">#gentoo-hardened</uri></ti> + <ti><uri link="irc://irc.freenode.org/rsbac">#rsbac</uri></ti> +</tr> </table> + +</body> </section> </chapter> + +</guide> diff --git a/xml/rsbac/transition.xml b/xml/rsbac/transition.xml new file mode 100644 index 0000000..0c372b6 --- /dev/null +++ b/xml/rsbac/transition.xml @@ -0,0 +1,60 @@ +<?xml version='1.0' encoding="UTF-8"?> <!DOCTYPE guide SYSTEM +"/dtd/guide.dtd"> + +<guide link="transition.xml"> + +<title>Rule Set Based Access Control (RSBAC) for Linux - +Transition from rsbac-sources to hardened-sources </title> + +<author title="Author"> + <mail link="kang@gentoo.org">Guillaume Destuynder</mail> +</author> +<abstract> This document will help you transioning from +rsbac-sources to hardened-sources </abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license +--> <!-- See http://creativecommons.org/licenses/by-sa/1.0 --> <license/> + +<version>1.0</version> <date>15 February 2006</date> + +<chapter> +<title>RSBAC</title> +<section> <title>Why ?</title> +<body> + +<note> Currently only the 2.4 kernels are affected </note> + +<p> All hardened patches are currently present in the hardened-sources + kernel. SELinux as well as GrSecurity MAC solutions are also present. + The current RSBAC kernel is simply a copy of this hardened-sources + kernel, with RSBAC patches added and GrSecurity patches disabled. </p> + +<p> When users are looking for the kernel to install, they install + this very one. Most often, they assume the RSBAC kernel is simply not + present because not inside of the "hardened kernel". </p> + +<p> Finally, why having two versions of the almost same kernel when + it can just be one ? </p> + +</body> +</section> +<section> <title>How ?</title> +<body> + +<p> The transition is very simple. In short, you just have to emerge + the hardened-sources kernel instead of the usual rsbac-sources one. + Make sure to also add the rsbac local use flag so that the RSBAC + patches get applied. </p> + +<impo> Make sure you are using the 2.4 kernel. 2.6 kernels have not yet been + transitionned </impo> + +<pre caption="Adding the rsbac local use flag"> + # <i>echo "sys-kernel/hardened-sources rsbac" >> /etc/portage/packages.use</i> + # <i>emerge hardened-sources</i> +</pre> + + +</body> </section> </chapter> + +</guide> diff --git a/xml/selinux/CVS/Entries b/xml/selinux/CVS/Entries new file mode 100644 index 0000000..e9e6593 --- /dev/null +++ b/xml/selinux/CVS/Entries @@ -0,0 +1,16 @@ +/hb-install.xml/1.5/Fri Jun 25 16:07:19 2010// +/hb-selinux-conv-profile.xml/1.10/Fri Jun 25 16:07:19 2010// +/hb-selinux-conv-reboot1.xml/1.11/Wed Oct 6 15:11:15 2010// +/hb-selinux-conv-reboot2.xml/1.11/Fri Jun 25 16:07:19 2010// +/hb-selinux-faq.xml/1.4/Thu Sep 7 10:37:46 2006// +/hb-selinux-howto.xml/1.6/Tue May 20 15:45:43 2008// +/hb-selinux-initpol.xml/1.6/Tue May 20 15:45:43 2008// +/hb-selinux-libsemanage.xml/1.1/Sun Oct 15 20:32:39 2006// +/hb-selinux-localmod.xml/1.1/Sun Oct 15 20:32:39 2006// +/hb-selinux-loglocal.xml/1.7/Tue May 20 15:45:43 2008// +/hb-selinux-logremote.xml/1.7/Tue May 20 15:45:43 2008// +/hb-selinux-overview.xml/1.10/Fri Jun 25 16:07:19 2010// +/hb-selinux-references.xml/1.5/Fri Jun 25 16:07:19 2010// +/index.xml/1.41/Wed Jul 22 13:38:18 2009// +/selinux-handbook.xml/1.9/Fri Jun 25 16:07:19 2010// +D diff --git a/xml/selinux/CVS/Repository b/xml/selinux/CVS/Repository new file mode 100644 index 0000000..9f509b3 --- /dev/null +++ b/xml/selinux/CVS/Repository @@ -0,0 +1 @@ +gentoo/xml/htdocs/proj/en/hardened/selinux diff --git a/xml/selinux/CVS/Root b/xml/selinux/CVS/Root new file mode 100644 index 0000000..da304d3 --- /dev/null +++ b/xml/selinux/CVS/Root @@ -0,0 +1 @@ +:pserver:anonymous@anoncvs.gentoo.org/var/cvsroot diff --git a/xml/selinux/hb-install.xml b/xml/selinux/hb-install.xml new file mode 100644 index 0000000..b259877 --- /dev/null +++ b/xml/selinux/hb-install.xml @@ -0,0 +1,66 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-install.xml,v 1.5 2010/06/25 16:07:19 pebenito Exp $ --> + +<sections> +<version>1.4</version> +<date>2010-06-15</date> + +<section><title>Gentoo SELinux Installation</title> +<subsection> +<body> + +<warn>SELinux is only supported on servers. Workstation support +will happen in the future.</warn> + +<p> +The installation of Gentoo SELinux is the same as regular Gentoo. The regular +install should be followed from the +<uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>, +keeping in mind the following notes. Then the +system should converted to SELinux using the +<uri link="?part=2">SELinux Conversion Guide</uri>. +It is recommended to use the hardened stage 3 tarball if you are building a +hardened Gentoo system (which is also recommended). +</p> + +</body> +</subsection> +</section> + +<section><title>Installation Notes</title> +<subsection><title>Filesystems</title> +<body> +<p> +Only ext2, ext3, ext4, JFS, XFS and Btrfs are supported at this time. Reiserfs + does not provide the necessary XATTR support, and Reiser4 is not well tested. +</p> +<p> +XFS users should use 512 byte inodes (the default is 256). SELinux keeps +file security lables in the extended attributes, which XFS stores in +the inode. If the inode is too small an extra block has to be used, which +wastes a lot of space and incurs performace penalties. +</p> +<pre caption="Example XFS filesystem creation command"> +# <i>mkfs.xfs -i size=512 /dev/hda3</i> +</pre> +</body> +</subsection> + +<subsection><title>Kernel</title> +<body> +<warn>Kernels 2.6.14 and 2.6.15 have broken SELinux XFS support.</warn> +<p> +You can save time by looking ahead to the <uri link="?part=2&chap=2#doc_chap2">kernel options</uri> +required for SELinux, to save compiling the kernel multiple times. +</p> +</body> +</subsection> + +</section> + +</sections> diff --git a/xml/selinux/hb-selinux-conv-profile.xml b/xml/selinux/hb-selinux-conv-profile.xml new file mode 100644 index 0000000..01f5ead --- /dev/null +++ b/xml/selinux/hb-selinux-conv-profile.xml @@ -0,0 +1,107 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-conv-profile.xml,v 1.10 2010/06/25 16:07:19 pebenito Exp $ --> + +<sections> +<version>2.1</version> +<date>2010-06-15</date> + +<section><title>Change Profile</title> +<subsection><body> + +<warn>SELinux is only supported on ext2/3, XFS, JFS, and Btrfs. Other filesystems +lack the complete extended attribute support.</warn> + +<warn>Users should convert from a 2006.1 or newer profile otherwise +there may be unpredictable results.</warn> + +<impo>As always, keep a LiveCD at hand in case things go wrong.</impo> + +<p>First switch your profile to the SELinux profile for your architecture:</p> + +<pre caption="Switch profiles"> +# <i>rm -f /etc/make.profile</i> + + +<comment>x86 (server):</comment> +# <i>ln -sf /usr/portage/profiles/selinux/v2refpolicy/x86/server /etc/make.profile</i> +<comment>x86 (hardened):</comment> +# <i>ln -sf /usr/portage/profiles/selinux/v2refpolicy/x86/hardened /etc/make.profile</i> +<comment>AMD64:</comment> +# <i>ln -sf /usr/portage/profiles/selinux/v2refpolicy/amd64/server /etc/make.profile</i> +<comment>AMD64 (hardened):</comment> +# <i>ln -sf /usr/portage/profiles/selinux/v2refpolicy/amd64/hardened /etc/make.profile</i> +</pre> + +<note>You can also switch profiles with eselect if you have the gentoolkit + package installed. That method is not shown here because the specific options + available and their numbering will vary according to your system + configuration.</note> + +<impo>Do not use any profiles other than the ones listed above, even +if they seem to be out of date. SELinux profiles are not necessarily +created as often as default Gentoo profiles.</impo> + +<impo>The SELinux profile has significanly fewer USE flags asserted than +the default profile. Use <c>emerge info</c> to see if any use flags +need to be reenabled in make.conf.</impo> + +<note>It is not necessary to add selinux to your USE flags in make.conf. +The SELinux profile already does this for you. +</note> + +<note> + You may encounter this message from portage: "!!! SELinux module not found. + Please verify that it was installed." This is normal, and will be fixed + later in the conversion process. +</note> +</body> +</subsection> +</section> + +<section><title>Update Kernel Headers</title> +<subsection><body> +<p> + We will start by updating essential packages. First check which version + of linux-headers is installed. +</p> + +<pre caption="Check linux-headers version"> +# <i>emerge -s linux-headers</i> +<comment>or if you have gentoolkit installed:</comment> +# <i>equery list -i linux-headers</i> +</pre> + +<p> + If the linux-headers version is older than 2.4.20, newer headers must be merged. +</p> + +<pre caption="Merge newer headers"> +# <i>emerge \>=sys-kernel/linux-headers-2.4.20</i> +</pre> +</body> +</subsection> +</section> + +<section><title>Update Glibc</title> +<subsection><body> +<p> + If you have merged new headers, or you are unsure if your glibc was + compiled with newer headers, you must recompile glibc. +</p> + +<pre caption="Recompile glibc"> +# <i>emerge glibc</i> +</pre> + +<impo> + This is a critical operation. Glibc must be compiled with newer linux-headers, + otherwise some operations will malfunction. +</impo> +</body></subsection> +</section> +</sections> diff --git a/xml/selinux/hb-selinux-conv-reboot1.xml b/xml/selinux/hb-selinux-conv-reboot1.xml new file mode 100644 index 0000000..0027f41 --- /dev/null +++ b/xml/selinux/hb-selinux-conv-reboot1.xml @@ -0,0 +1,193 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-conv-reboot1.xml,v 1.11 2010/10/06 15:11:15 pebenito Exp $ --> + +<sections> +<version>2.1</version> +<date>2010-10-06</date> + +<section><title>Merge a SELinux Kernel</title> +<subsection><body> +<p>Merge an appropriate kernel. A 2.6 kernel is required. The + suggested kernel is hardened-sources. +</p> + +<note>2.6.28-r9 is the current hardened release version at the time of this writing, + and all instructions in this document assume at least this version.</note> + +<warn>Kernels 2.6.14 and 2.6.15 should not be used by XFS users as they + have bugs in the SELinux XFS support.</warn> + +<pre caption="Merge an appropriate kernel"> +<comment>Any 2.6 kernel</comment> +# <i>emerge hardened-sources</i> +</pre> +</body></subsection> +</section> + +<section><title>Compile the Kernel with SELinux Options</title> +<subsection><body> +<p>The kernel must be compiled with security module support, SELinux support, +devpts, and extended attribute security labels. Refer to the main installation +guide for futher kernel options.</p> + +<note> +The available options may vary slightly depending on the kernel version +being used. In particular, Btrfs first became available with the 2.6.29 +kernel, and the /dev/pts and tmpfs Extended Attributs and Security Labels +options were obsoleted in kernel 2.6.13 (they are now enabled by default). +"Default Linux Capabilies" under "Security options" was obsoleted in the +2.6.26 kernel (it is now enabled by default). + +XFS always enables security labeling, so there is no additional option +to set for this file system + +Ext4 should work, but is NOT well tested at the time of this writing! + +Any extended attribute options not specifically enabled below should be turned +off. +</note> + +<pre caption="Location and required options under menuconfig"> +<comment>Under "General setup"</comment> +[*] Prompt for development and/or incomplete code/drivers +[*] Auditing support +[*] Enable system-call auditing support + +<comment>Under "File systems"</comment> +<*> Second extended fs support <comment>(If using ext2)</comment> +[*] Ext2 extended attributes +[ ] Ext2 POSIX Access Control Lists +[*] Ext2 Security Labels +[ ] Ext2 Execute in place support +<*> Ext3 journalling file system support <comment>(If using ext3)</comment> +[*] Ext3 extended attributes +[ ] Ext3 POSIX Access Control Lists +[*] Ext3 Security labels +<*> The Extended 4 (ext4) filesystem <comment>(If using ext4)</comment> +[ ] Enable ext4dev compatibility +[*] Ext4 extended attrributes +[ ] Ext4 POSIX Access Control Lists +[*] Ext4 Security Labels +<*> JFS filesystem support <comment>(If using JFS)</comment> +[ ] JFS POSIX Access Control Lists +[*] JFS Security Labels +[ ] JFS debugging +[ ] JFS statistics +<*> XFS filesystem support <comment>(If using XFS)</comment> +[ ] XFS Quota support +[ ] XFS POSIX ACL support +[ ] XFS Realtime subvolume support (EXPERIMENTAL) +[ ] XFS Debugging Support +<*> Btrfs filesystem (EXPERIMENTAL) Unstable disk format <comment>(if +using Btrfs)</comment> +[ ] Btrfs POSIX Access Control Lists (NEW) +<comment>Under "Pseudo filesystems (via "File systems")</comment> +[ ] /dev file system support (EXPERIMENTAL) +[*] /dev/pts Extended Attributes +[*] /dev/pts Security Labels +[*] Virtual memory file system support (former shm fs) +[*] tmpfs Extended Attributes +[*] tmpfs Security Labels + +<comment>Under "Security options"</comment> +[*] Enable different security models +[*] Socket and Networking Security Hooks +<*> Default Linux Capabilities +[*] NSA SELinux Support +[ ] NSA SELinux boot parameter +[ ] NSA SELinux runtime disable +[*] NSA SELinux Development Support +[ ] NSA SELinux AVC Statistics +(1) NSA SELinux checkreqprot default value +[ ] NSA SELinux enable new secmark network controls by default +[ ] NSA SELinux maximum supported policy format version + Default security module (SELinux) ---> +</pre> + +<p> + The extended attribute security labels must be turned on for devpts and + your filesystem(s). Devfs is not usable in SELinux, and should be + turned off. Not all options exist on older 2.6 kernels, + such as Auditing support, and runtime disable. In newer kernels, + the extended attributes support for proc and the virtual memory fs (tmpfs) + are enabled by default; thus, no options will appear in menuconfig. +</p> + +<note>It is recommended to configure PaX if you are using harded-sources (also +recommended). More information about Pax can be found in the <uri link="http://www.gentoo.org/proj/en/hardened/pax-quickstart.xml">Hardened Gentoo +PaX Quickstart Guide</uri>. +</note> + +<warn> + Do not enable the SELinux MLS policy option if its available, as it is + not supported, and will cause your machine to not start. +</warn> + +<p> + Now compile and install the kernel and modules, but do not reboot. +</p> +</body></subsection> +</section> + +<section><title>Update fstab</title> +<subsection><body> +<p> + SElinuxfs must also be enabled to mount at boot. + Add this to /etc/fstab: +</p> +<pre caption="Fstab settings for selinuxfs"> +none /selinux selinuxfs defaults 0 0 +</pre> +</body></subsection> +</section> + +<section><title>Configure Baselayout</title> +<subsection><body> +<p> +SELinux does not support devfs. You must configure baselayout to +use either static device nodes or udev. If using udev, the +device tarball must be disabled. Edit the /etc/conf.d/rc file. +Set RC_DEVICES to static or udev, and RC_DEVICE_TARBALL to no. +If you have several custom device nodes, static is suggested, +otherwise udev is suggested (udev is the default at the time of this writing). +For more information on udev, consult the <uri link="/doc/en/udev-guide.xml">Gentoo UDEV Guide</uri>. +</p> +<pre caption="Init script configuration"> +# Use this variable to control the /dev management behavior. +# auto - let the scripts figure out what's best at boot +# devfs - use devfs (requires sys-fs/devfsd) +# udev - use udev (requires sys-fs/udev) +# static - let the user manage /dev + +RC_DEVICES="<comment>udev</comment>" + +# UDEV OPTION: +# Set to "yes" if you want to save /dev to a tarball on shutdown +# and restore it on startup. This is useful if you have a lot of +# custom device nodes that udev does not handle/know about. + +RC_DEVICE_TARBALL="<comment>no</comment>" +</pre> +</body></subsection> +</section> + +<section><title>Reboot</title> +<subsection><body> +<p> + We need to make some directories before we reboot. +</p> +<pre caption="Making Required Directories"> +# <i>mkdir /selinux</i> +# <i>mkdir /sys</i> +</pre> +<p> + Now reboot. +</p> +</body></subsection> +</section> +</sections> diff --git a/xml/selinux/hb-selinux-conv-reboot2.xml b/xml/selinux/hb-selinux-conv-reboot2.xml new file mode 100644 index 0000000..03be7e9 --- /dev/null +++ b/xml/selinux/hb-selinux-conv-reboot2.xml @@ -0,0 +1,213 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-conv-reboot2.xml,v 1.11 2010/06/25 16:07:19 pebenito Exp $ --> + +<sections> +<version>2.2</version> +<date>2009-12-15</date> + +<section><title>Merge SELinux Packages</title> +<subsection> +<body> +<p>Merge the libraries, utilities and base-policy. The policy version may need + be adjusted, refer to the SELinux Overview + for more information on policy versions. Then load the policy.</p> + +<pre caption="Merge base SELinux packages and policy"> +# <i>emerge -1 checkpolicy policycoreutils</i> +# <i>FEATURES=-selinux emerge -1 selinux-base-policy</i> +</pre> +<note> +The "FEATURES=-selinux" part of the emerge command should only be used on the above command. +It is required to merge selinux-base-policy (only for the first time) as the portage SELinux features require both policycoreutils and selinux-base-policy otherwise portage will fail. +</note> +</body></subsection> +</section> + +<section><title>Choose the policy type</title> +<body> +<p> +New in 2006.1, users now have the choice between the strict policy and the +targeted policy. +</p> +<p> +In the strict policy, all processes are confined. +If you are familiar with pre 2006.1 Gentoo SELinux policy, that policy was a strict policy. +Strict policy is suggested for servers. +Gentoo does not support the strict policy on desktops. +</p> +<p> +The targeted policy differs with strict, as only network-facing services are +confined and local users are unconfined. Gentoo only supports desktops with +the targeted policy. This policy can also be used on servers. +</p> +<p> +Edit the /etc/selinux/config file to set the policy type. +</p> +<pre caption="/etc/selinux/config contents"> +# This file controls the state of SELinux on the system on boot. + +# SELINUX can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +SELINUX=permissive <comment>(This should be set permissive for the remainder of the install)</comment> + +# SELINUXTYPE can take one of these two values: +# targeted - Only targeted network daemons are protected. +# strict - Full SELinux protection. +SELINUXTYPE=strict <comment>(Set this as strict or targeted)</comment> +</pre> +</body> +</section> + +<section><title>Merge SELinux-patched packages</title> +<subsection><body> +<p> + There are several system packages that have SELinux patches. These patches + provide a variety of additional SELinux functionality, such as displaying + file contexts. +</p> +<pre caption="Remerge Packages"> +# <i>emerge -1 sysvinit pam coreutils findutils openssh procps psmisc shadow util-linux python-selinux</i> +</pre> +<note> + If you find that you can't use portage due to a errors like these: + !!! 'module' object has no attribute 'secure_rename' or + AttributeError: 'module' object has no attribute 'getcontext', this is + a portage bug, where it can't handle a missing python-selinux. Merge it + with "FEATURES=-selinux emerge python-selinux" to fix the problem. See + bug <uri link="http://bugs.gentoo.org/show_bug.cgi?id=122517">#122517</uri> + for more information. +</note> +<p>There are other packages that have SELinux patches, but are optional. These +should be remerged if they are already installed, so the SELinux patches are +applied:</p> +<ul> +<li>app-admin/logrotate</li> +<li>sys-apps/fcron</li> +<li>sys-apps/vixie-cron</li> +<li>sys-fs/device-mapper</li> +<li>sys-fs/udev</li> +<li>sys-libs/pwdb</li> +</ul> +<note> + Fcron and Vixie-cron are the only crons with SELinux support. +</note> +<note>The above packages are NOT an exhaustive list; they are only the most +common ones. In general, any package installed on the system which has the +selinux USE flag should be remerged. To see which packages may need to be +merged, you can: +emerge -upDN world + +Since changing to the selinux profile has changed your USE flags, the above +will get everything that is listening to the selinux USE flag. It will +probably also get some other stuff as well. To actually remerge everything, +simply remove the 'p', or manually specify the packages you want to remerge. +</note> +</body></subsection> +</section> + +<section><title>Merge Application Policies</title> +<subsection><body> +<p> + In future, when merging a package, the policy will be set as a dependency so + that it is merged first; however, since the system is being converted, policy + for currently installed packages must be merged. The selinux-base-policy + already covers most packages in the system profile. +</p> +<p> + Look in the <c>/usr/portage/sec-policy</c>, it has several entries, each which + represent a policy. The naming scheme is selinux-PKGNAME, where PKGNAME is + the name of the package that the policy is associated. For example, the + selinux-apache package is the SELinux policy package for net-www/apache. + Merge each of the needed policy packages and then load the policy. + If you are converting a desktop, make sure to include the selinux-desktop policy package. +</p> +<pre caption="Example Merge of Apache and BIND policies"> +# <i>ls /usr/portage/sec-policy</i> +<comment>(many directories listed)</comment> + +# <i>emerge -1 selinux-apache selinux-bind</i> +</pre> +</body></subsection> +</section> + +<section><title>Label Filesystems</title> +<subsection><body> +<p> + Before you can relabel the rest of the filesystems, you need to first relabel + /dev. Strictly speaking, this is only necessary if you aren't using a static + /dev. However, as the vast majority of current and new systems are going to + be built with udev, this probably means you are using udev as well. There + are a lot of different ways to get at this problem, but the steps below are + easy to do and work. +</p> + <pre caption="Relabel /dev"> +<i># mkdir /mnt/gentoo +# mount -o bind / /mnt/gentoo +# setfiles -r /mnt/gentoo /etc/selinux/{strict,targeted}/contexts/files/file_contexts /mnt/gentoo/dev +# umount /mnt/gentoo +</i> + </pre> + <note>Remember to select one of {strict,targeted} above based on your + enforcement mode.</note> +<p> + Now label the filesystems. This gives each of the files in the filesystems + a security label. Keeping these labels consistent is important. +</p> +<pre caption="Label filesystems"> +# <i>rlpkg -a -r</i> +</pre> +<warn> + There is a known issue with older versions of GRUB + not being able to read symlinks that have been labeled. + Please make sure you have at least GRUB 0.94 installed. + Also rerun GRUB and reinstall it into the MBR to ensure + the updated code is in use. + You do have a LiveCD handy, right? +</warn> +<pre caption="Reinstall GRUB on the MBR (GRUB users only)"> +# <i>grub</i> + +grub> root (hd0,0) <comment>(Your boot partition)</comment> +grub> setup (hd0) <comment>(Where the boot record is installed; here, it is the MBR)</comment> +</pre> +<p> + If you've installed Gentoo using the hardened sources, then you'll need to + tell SELinux that you are using the hardened tool-chain with ssp. You do + this by setting an SELinux global boolean +</p> +<pre caption="SELinux global_ssp"> +<i>setsebool -P global_ssp on</i> +</pre> +<note>Make sure you use the -P flag, or the setting won't survive the reboot, +and you'll likely see a lot of errors relating to /dev/null and /dev/random +</note> +</body></subsection> +</section> + +<section><title>Final reboot</title> +<subsection><body> +<p>Reboot. Log in, then relabel again to ensure all files +are labeled correctly (some files may have been created during shutdown and +reboot)</p> +<pre caption="Relabel"> +# <i>rlpkg -a -r</i> +</pre> +<note> + It is strongly suggested to <uri link="http://www.gentoo.org/main/en/lists.xml">subscribe</uri> + to the gentoo-hardened mail list. It is generally a low traffic list, and + SELinux announcements are made there. +</note> +<p> + SELinux is now installed! +</p> +</body></subsection> +</section> + +</sections> diff --git a/xml/selinux/hb-selinux-faq.xml b/xml/selinux/hb-selinux-faq.xml new file mode 100644 index 0000000..dc35969 --- /dev/null +++ b/xml/selinux/hb-selinux-faq.xml @@ -0,0 +1,154 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-faq.xml,v 1.4 2006/09/07 10:37:46 neysx Exp $ --> + +<sections> +<version>1.3</version> +<date>2006-05-01</date> + +<section><title>SELinux features</title> +<subsection><title>Does SELinux enforce resource limits?</title> +<body> +<p> + No, resource limits are outside the scope of an access control system. If you + are looking for this type of support, GRSecurity and RSBAC are better choices. +</p> +</body></subsection> +</section> + +<section><title>SELinux and other hardened projects</title> +<subsection><title>Can I use SELinux and GRSecurity (and PaX)?</title> +<body> +<p> + Yes, SELinux can be used with GRSecurity and/or PaX with no problems; however, + it is suggested that GRACL should not be used, since it would be redundant + to SELinux's access control. +</p> +</body></subsection> +<subsection><title>Can I use SELinux and the hardened compiler (PIE-SSP)?</title> +<body> +<p> + Yes. It is also suggested that PaX be used to take full advantage + of the PIE features of the compiler. +</p> +</body></subsection> +<subsection><title>Can I use SELinux and RSBAC?</title> +<body> +<p> + Unknown. Please report your results if you try this combination. +</p> +</body></subsection> +</section> + +<section><title>SELinux and filesystems</title> +<subsection><title>Can I use SELinux with my primary filesystems?</title> +<body> +<p> + SELinux can be used with ext2, ext3, JFS, and XFS. Reiserfs (Reiser3) has + extended attributes, but the support was never complete, and has been broken + since 2.6.14. Reiser4 is not supported. +</p> +</body></subsection> +<subsection><title>Can I use SELinux with my ancillary filesystems?</title> +<body> +<p> + Yes, SELinux can mount ancillary filesystems, such as vfat and iso9660 + filesystems, with an important caveat. All files in each filesystem will + have the same SELinux type, since the filesystems do not support extended + attributes. Tmpfs is the only ancillary filesystem with complete extended + attribute support, which allows it to behave like a primary filesystem. +</p> +</body></subsection> +<subsection><title>Can I use SELinux with my network filesystems?</title> +<body> +<p> + Yes, SELinux can mount network filesystems, such as NFS and CIFS + filesystems, with an important caveat. All files in each filesystem will + have the same SELinux type, since the filesystems do not support extended + attributes. In the future, hopefully network filesystems will begin to + support extended attributes, then they will work like a primary filesystem. +</p> +</body></subsection> +</section> + +<section><title>Portage error messages</title> +<subsection><title>I get a missing SELinux module error when using emerge:</title> +<body> +<pre caption="Portage message"> +!!! SELinux module not found. Please verify that it was installed. +</pre> +<p> + This indicates that the portage SELinux module is missing or damaged. + Also python may have been upgraded to a new version which requires + python-selinux to be recompiled. Remerge dev-python/python-selinux. + If packages have been merged under this condition, they must be relabed + after fixing this condition. If the packages needing to be remerged cannot + be determined, a full relabel may be required. +</p> +</body></subsection> +</section> + +<section><title>SELinux kernel error messages</title> +<subsection><title>I get a register_security error message when booting:</title> +<body> +<pre caption="Kernel message"> +There is already a security framework initialized, register_security failed. +Failure registering capabilities with the kernel +selinux_register_security: Registering secondary module capability +Capability LSM initialized +</pre> +<p> + This means that the Capability LSM module couldn't register as the primary + module, since SELinux is the primary module. The third message means that it + registers with SELinux as a secondary module. This is normal. +</p> +</body></subsection> +</section> + +<section><title>Setfiles error messages</title> +<subsection><title>When I try to relabel, it fails with invalid contexts:</title><body> +<pre caption="Invalid contexts example"> +# make relabel +/usr/sbin/setfiles file_contexts/file_contexts `mount | awk '/(ext[23]| xfs).*rw/{print $3}'` +/usr/sbin/setfiles: read 559 specifications +/usr/sbin/setfiles: invalid context system_u:object_r:default_t on line number 39 +/usr/sbin/setfiles: invalid context system_u:object_r:urandom_device_t on line number 120 +/usr/sbin/setfiles: invalid context system_u:object_r:fonts_t on line number 377 +/usr/sbin/setfiles: invalid context system_u:object_r:fonts_t on line number 378 +/usr/sbin/setfiles: invalid context system_u:object_r:krb5_conf_t on line number 445 +/usr/sbin/setfiles: invalid context system_u:object_r:system_cron_spool_t on line number 478 +/usr/sbin/setfiles: invalid context system_u:object_r:system_cron_spool_t on line number 479 +/usr/sbin/setfiles: invalid context system_u:object_r:system_cron_spool_t on line number 492 +/usr/sbin/setfiles: invalid context system_u:object_r:system_cron_spool_t on line number 493 +/usr/sbin/setfiles: invalid context system_u:object_r:system_cron_spool_t on line number 494 +Exiting after 10 errors. +make: *** [relabel] Error 1 +</pre> +<p> + First ensure that /selinux is mounted. If selinuxfs is not mounted, setfiles + cannot validate any contexts, causing it to believe all contexts are + invalid. If /selinux is mounted, then most likely there is new policy that + has not yet been loaded; therefore, the contexts have not yet become valid. +</p> +</body></subsection> +</section> + + +<!-- always keep this one as the bottom FAQ :) --> +<!-- comment out since the demo machine is down for an indefinite period of time +<section><title>Gentoo SELinux Demonstration Machine</title> +<subsection><body> +<p> + This machine is not running user-mode linux, or in a chroot, it has SELinux + mandatory access control. No, you cannot install psybnc or an irc bot on the + machine, unless you break the SELinux security and gain higher priviledge. +</p> +</body></subsection> +</section> +--> +<!-- dont put anything below here, this demo machine faq should be the last one --> +</sections> diff --git a/xml/selinux/hb-selinux-howto.xml b/xml/selinux/hb-selinux-howto.xml new file mode 100644 index 0000000..b8f7db0 --- /dev/null +++ b/xml/selinux/hb-selinux-howto.xml @@ -0,0 +1,250 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-howto.xml,v 1.6 2008/05/20 15:45:43 pebenito Exp $ --> + +<sections> +<version>2.0</version> +<date>2006-10-14</date> + +<section><title>Load policy into a running SELinux kernel</title> +<subsection><body> +<p> + This requires you to be in the <c>sysadm_r</c> role. +</p> +<pre caption="Semodule command"> +# <i>semodule -B</i> +</pre> +</body></subsection> +</section> + +<section><title>Change roles</title> +<subsection><body> +<p> + This requires your user have access to the target role. This example + is for changing to the <c>sysadm_r</c> role. +</p> +<pre caption="Newrole"> +# <i>newrole -r sysadm_r</i> +</pre> +</body></subsection> +</section> + +<section><title>Specify available roles for a user</title> +<subsection><body> +<p> + There is a mapping of linux users to SELinux identities. The policy has + generic SELinux users for relevant configurations of roles. For example, to + map the user <c>pebenito</c> to the SELinux identity <c>staff_u</c>, run: +</p> +<pre caption="Map pebenito to staff_u"> +# <i>semanage login -a -s staff_u pebenito</i> +</pre> +<p> + The policy does not need to be reloaded. If the user is logged in, it + must log out and log in again to take effect. +</p> +</body></subsection> +</section> + +<section><title>Relabel filesystems</title> +<subsection><body> +<p> + This requires you to be in the <c>sysadm_r</c> role. +</p> +<pre caption="Relabel"> +# <i>rlpkg -a</i> +</pre> +</body></subsection> +</section> + +<section><title>Relabel an individual package</title> +<subsection><body> +<p> + In addition to relabeling entire filesystems, individual portage packages + can be relabeled. This requires you to be in the <c>sysadm_r</c> role. +</p> +<pre caption="rlpkg example"> +# <i>rlpkg shadow sash</i> +</pre> +<p> + The script rlpkg is used, and any number of packages can be specified + on the command line. +</p> +</body></subsection> +</section> + +<section><title>Scan for libraries with text relocations</title> +<subsection><body> +<p> + SELinux has improved memory protections. One feature supported is + the permission for ELF text relocations. The libraries with text relocations + have a special label, and the <c>rlpkg</c> tool has an option to scan for + these libraries. +</p> +<pre caption="TEXTREL Scan"> +# <i>rlpkg -t</i> +</pre> +<p> + This will also be done by automatically after a full relabel. +</p> +</body></subsection> +</section> + +<section><title>Start daemons in the correct domain</title> +<subsection><body> +<p> + Controlling daemons that have init scripts in /etc/init.d is slightly + different in SELinux. The <c>run_init</c> command must be used to run + the scripts, to ensure they are ran in the correct domain. The command + can be ran normally, except the command is prefixed with <c>run_init</c>. + This requires you to be in the <c>sysadm_r</c> role. +</p> +<pre caption="run_init examples"> +# <i>run_init /etc/init.d/ntpd start</i> +# <i>run_init /etc/init.d/apache2 restart</i> +# <i>run_init /etc/init.d/named stop</i> +</pre> +</body></subsection> +<subsection><title>Gentoo run_init integration</title><body> +<p> + <c>run_init</c> has been integrated into Gentoo's init script system. With + SELinux installed, services can be started and stopped as usual, but will + now authenticate the user. +</p> +<pre caption="Integrated run_init example"> +# <i>/etc/init.d/sshd restart</i> +Authenticating root. +Password: + * Stopping sshd... [ ok ] + * Starting sshd... [ ok ] +</pre> +</body></subsection> +</section> + +<section><title>Switch between enforcing and permissive modes</title> +<subsection><body> +<p> + Switching between modes in SELinux is very simple. Write a 1 for + enforcing, or 0 for permissive to /selinux/enforce to set the mode. + The current mode can be queried by reading /selinux/enforce; 0 means + permissive mode, and 1 means enforcing mode. If the kernel option + "NSA SELinux Development Support" is turned off, the system will always + be in enforcing mode, and cannot be switched to permissive mode. +</p> +<pre caption=""> +<comment>Query current mode</comment> +# <i>cat /selinux/enforce</i> +<comment>Switch to enforcing mode</comment> +# <i>echo 1 > /selinux/enforce</i> +<comment>Switch to permissive mode</comment> +# <i>echo 0 > /selinux/enforce</i> +</pre> +<p> + A machine with development support turned on can be started in enforcing + mode by adding <c>enforcing=1</c> to the kernel command line, in the + bootloader (GRUB, lilo, etc). +</p> +</body></subsection> + +<subsection><title>Managed policy</title><body> +<p> + In addition to the above kernel options, the mode at boot can be + set by the <c>/etc/selinux/config</c> file. +</p> +<pre caption="/etc/selinux/config"> +# SELINUX can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +SELINUX=<comment>permissive</comment> +</pre> +<p> + The setting in this file will be overridden by the kernel command line + options described above. +</p> +</body></subsection> +</section> + +<section><title>Understand sestatus output</title> +<subsection><body> +<p> + The <c>sestatus</c> tool can be used to determine detailed SELinux-specific + status information about the system. The <c>-v</c> option provides extra + detail about the context of processes and files. The output will be + divided into four sections. Sestatus only provides complete information + for a user logged in as root (or su/sudo), in the <c>sysadm_r</c> role. +</p> +<pre caption="Status example"> +SELinux status: enabled +SELinuxfs mount: /selinux +Current mode: enforcing +Policy version: 18 +</pre> +<p> + The main status information is provided in the first section. The first + line shows if SELinux kernel functions exists and are enabled. If the + status is disabled, either the kernel does not have SELinux support, or + the policy is not loaded. The second line shows the mount point for + the SELinux filesystem. During the normal use, the filesystem should be + mounted at the default location of <c>/selinux</c>. The third line + shows the current SELinux mode, either enforcing or permissive. The fourth + line shows the policy database version supported by the currently running + kernel. +</p> +<pre caption="Booleans example"> +Policy booleans: +secure_mode inactive +ssh_sysadm_login inactive +user_ping inactive +</pre> +<p> + The second section displays the status of the conditional policy booleans. The + left column is the name of boolean. The right column is the status of the + boolean, either active, or inactive. This section will not be shown on + policy version 15 kernels, as they do not support conditional policy. +</p> +<pre caption="Process context example"> +Process contexts: +Current context: pebenito:sysadm_r:sysadm_t +Init context: system_u:system_r:init_t +/sbin/agetty system_u:system_r:getty_t +/usr/sbin/sshd system_u:system_r:sshd_t +</pre> +<p> + The third section displays the context of the current process, and of several + key processes. If a process is running in the incorrect context, it will not + function correctly. +</p> +<pre caption="File context example"> +File contexts: +Controlling term: pebenito:object_r:sysadm_devpts_t +/sbin/init system_u:object_r:init_exec_t +/sbin/agetty system_u:object_r:getty_exec_t +/bin/login system_u:object_r:login_exec_t +/sbin/rc system_u:object_r:initrc_exec_t +/sbin/runscript.sh system_u:object_r:initrc_exec_t +/usr/sbin/sshd system_u:object_r:sshd_exec_t +/sbin/unix_chkpwd system_u:object_r:chkpwd_exec_t +/etc/passwd system_u:object_r:etc_t +/etc/shadow system_u:object_r:shadow_t +/bin/sh system_u:object_r:bin_t -> system_u:object_r:shell_exec_t +/bin/bash system_u:object_r:shell_exec_t +/bin/sash system_u:object_r:shell_exec_t +/usr/bin/newrole system_u:object_r:newrole_exec_t +/lib/libc.so.6 system_u:object_r:lib_t -> system_u:object_r:shlib_t +/lib/ld-linux.so.2 system_u:object_r:lib_t -> system_u:object_r:shlib_t +</pre> +<p> + The fourth section displays the context of the current process's controlling + terminal, and of several key files. For symbolic links, the context of + the link and then the context of the link target is displayed. If a file has + an incorrect context, the file may be inaccessable or have incorrect + permissions for a particular process. +</p> +</body></subsection> +</section> +</sections> diff --git a/xml/selinux/hb-selinux-initpol.xml b/xml/selinux/hb-selinux-initpol.xml new file mode 100644 index 0000000..b13a0de --- /dev/null +++ b/xml/selinux/hb-selinux-initpol.xml @@ -0,0 +1,48 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-initpol.xml,v 1.6 2008/05/20 15:45:43 pebenito Exp $ --> + +<sections> +<version>1.3</version> +<date>2004-11-16</date> + +<section><title>Verify Available Policy</title> +<subsection><body> +<p> + You must be in <c>sysadm_r</c> to perform this action. +</p> +<p> + A binary policy must be available in + /etc/selinux/{strict,targeted}/policy. If it is missing, then install + the policy. +</p> +<pre caption="Install policy"> +# <i>semodule -n -B</i> +</pre> +</body> +</subsection> +</section> + +<section><title>Verify Init Can Load the Policy</title> +<subsection><body> +<p> + The final check is to ensure init can load the policy. Run <c>ldd</c> on + init, and if libselinux is not in the output, remerge sysvinit. +</p> +<pre caption=""> +# <i>ldd /sbin/init</i> + linux-gate.so.1 => (0xffffe000) + <comment>libselinux.so.1 => /lib/libselinux.so.1 (0x40025000)</comment> + libc.so.6 => /lib/libc.so.6 (0x40035000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) +</pre> +<p> + Now reboot so init gains the correct context, and loads the policy. +</p> +</body></subsection> +</section> +</sections> diff --git a/xml/selinux/hb-selinux-libsemanage.xml b/xml/selinux/hb-selinux-libsemanage.xml new file mode 100644 index 0000000..a441f29 --- /dev/null +++ b/xml/selinux/hb-selinux-libsemanage.xml @@ -0,0 +1,246 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-libsemanage.xml,v 1.1 2006/10/15 20:32:39 pebenito Exp $ --> + +<sections> +<version>1.0</version> +<date>2006-10-15</date> + +<section><title>SELinux Management Infrastructure</title> +<subsection><body> +<p> + The SElinux management infrastructure manages several aspects of SELinux + policy. These management tools are based on the core library libsemanage. + There are several management programs to to various tasks, including + <c>semanage</c> and <c>semodule</c>. They allow you to configure aspects + of the policy without requiring the policy sources. +</p> +</body></subsection> +</section> + +<section><title>SELinux Policy Module Management</title> +<subsection><title>What is a policy module?</title><body> +<p> + SELinux supports a modular policy. This means several pieces of policy + are brought together to form one complete policy to be loaded in the + kernel. This is a similar structure as the kernel itself and kernel modules. + There is a main kernel image that is loaded, and various kernel modules can + be added (assuming their dependencies are met) and removed on a running + system without restarting. Similarly each policy has a base module and + zero or more policy modules, all used to create a policy. + Modules are built by compiling a piece of policy, and creating a policy + package (*.pp) with that compiled policy, and optionally file contexts. +</p> +<p> + The base module policy package (base.pp) contains the basic requirements of + the policy. All modular policies must have a base module at minimum. + In Gentoo we have these plus policies for all parts of the system profile. + This is contained in the selinux-base-policy ebuild. The other policy ebuilds + in portage have one or more policy modules. +</p> +<p> + For more information on writing a policy module, in particular for managing + your local customizations to the policy, please see the + <uri link="selinux-handbook.xml?part=3&chap=5">policy module guide</uri>. +</p> +</body></subsection> + +<subsection><title>The SELinux module store</title><body> +<p> + When a policy module is inserted or removed, modules are copied into or + removed from the module store. This repository has a copy of the + modules that were used to create the current policy, in addition to several + auxilliary files. This repository is stored in the + /etc/selinux/{strict,targeted}/modules. You should never need to directly + access the contents of the module store. A libsemanage-based tool should be + used instead. +</p> +<p> + Libsemanage handles the module store transactionally. This means that if + a set of operations (a transaction) is performed on the store and one part + fails, the entire transaction is aborted. This keeps the store in a + consistent state. +</p> +<p> + Managing the module store is accomplished with the <c>semodule</c> command. + Listing the contents of the module store is done with the <c>-l</c> option. +</p> +<pre caption=""> +# semodule -l +distcc 1.1.1 +</pre> +<p> + Since the base module is required in all cases, and is not versioned, it will + not be shown in the list. All other modules will be listed, along with their + versions. +</p> +</body></subsection> + +<subsection><title>Inserting a policy module</title><body> +<p> + The module should be referenced by its file name. +</p> +<pre caption=""> +# <i>semodule -i module.pp</i> +</pre> +<p> + This will insert the module into module store for the currently configured + policy as specified in /etc/selinux/config. If the insert succeeds, the + policy will be loaded, unless the <c>-n</c> option is used. To insert the + module into an alternate module store, the <c>-s</c> option. +</p> +<pre caption=""> +# <i>semodule -s targeted -i module.pp</i> +</pre> +<p> + Since this refers to an alternate module store, the policy will not be loaded. +</p> +</body></subsection> + +<subsection><title>Removing a policy module</title><body> +<p> + The module is referenced by its name in the module store. +</p> +<pre caption=""> +# <i>semodule -r module</i> +</pre> +<p> + This will remove the module into module store for the currently configured + policy as specified in /etc/selinux/config. If the remove succeeds, the + policy will be loaded, unless the <c>-n</c> option is used. The remove + command also respects the <c>-s</c> option. +</p> +</body></subsection> +</section> + +<section><title>Configuring User Login Mappings</title> +<subsection><body> +<p> + The current method of assigning sets of roles to a user is by setting + up a mapping between linux users and SELinux identities. When a user + logs in, the login program will set the SELinux identity based on the + this map. If there is no explicit map, the <c>__default__</c> map is + used. +</p> +<p> + Managing the SELinux user login map is accomplished with the <c>semanage</c> + tool. +</p> +<pre caption="SELinux login user map"> +# <i>semanage login -l</i> +Login Name SELinux User + +__default__ user_u +root root +</pre> +</body></subsection> + +<subsection><title>Add a user login mapping</title><body> +<p> + To map the linux user <c>pebenito</c> to the SELinux identity <c>staff_u</c>: +</p> +<pre caption=""> +# <i>semanage login -a -s staff_u pebenito</i> +</pre> +<p> + For descriptions on the available SELinux identities, see the + <uri link="selinux-handbook.xml?part=3&chap=1#doc_chap3">SELinux Overview</uri>. +</p> +</body></subsection> + +<subsection><title>Remove a user login mapping</title><body> +<p> + To remove a login map for the linux user <c>pebenito</c>: +</p> +<pre caption=""> +# <i>semanage login -d pebenito</i> +</pre> +<note> + User login maps specified by the policy (not by the management infrastructure) + cannot be removed. +</note> +</body></subsection> +</section> + +<section><title>Configuring Initial Boolean States</title> +<subsection><body> +<p> + The <c>setsebool</c> program is now a libsemanage tool. This tool's basic + function is to set the state of a Boolean. However, if the machine is + restarted, the Booelans will be set using the initial state as specified in + the policy. To set the Boolean state, and make that the new initial state + in the policy, the <c>-P</c> option of <c>setsebool</c> is used. +</p> +<pre caption="Set Boolean default state"> +# <i>setsebool -P fcron_crond 1</i> +</pre> +<p> + This will set the fcron_crond Boolean to true and also make the initial state + for the Boolean true. +</p> +</body></subsection> +</section> + +<section><title>Configuring SELinux Identities</title> +<subsection><body> +<p> + Generally SELinux identities need not be added to the policy, as user + login mappings are sufficient. However, one reason to add them is for + improved auditing, since the SELinux identity is part of the scontext of a + denial message. +</p> +<p> + Managing the SELinux identities is accomplished with the <c>semanage</c> tool. +</p> +<pre caption="SELinux identity list"> +# <i>semanage user -l</i> +SELinux User SELinux Roles + +root sysadm_r staff_r +staff_u sysadm_r staff_r +sysadm_u sysadm_r +system_u system_r +user_u user_r +</pre> +</body></subsection> + +<subsection><title>Add a SELinux identity</title><body> +<p> + In addition to specifying the roles for an identity, a prefix must + also be specified. This prefix should match a role, for example + <c>staff</c> or <c>sysadm</c>, and it is used for home directory + entries. So if <c>staff</c> is used for the prefix, linux users that + are mapped to this identity will have their home directory labeled + <c>staff_home_dir_t</c>. +</p> +<p> + To add the <c>test_u</c> identity with the roles <c>staff_r</c> and + <c>sysadm_r</c> with the prefix <c>staff</c>: +</p> +<pre caption=""> +# <i>semanage user -a -R 'staff_r sysadm_r' -P staff test_u</i> +</pre> +<note> + To use the SELinux identity, a user login map still must be added. +</note> +</body></subsection> + +<subsection><title>Remove a SELinux user identity</title><body> +<p> + To remove the test_u SELinux identity: +</p> +<pre caption=""> +# <i>semanage user -d test_u</i> +</pre> +<note> + SELinux identities specified by the policy (not by the management + infrastructure) cannot be removed. +</note> +</body></subsection> +</section> + +</sections> diff --git a/xml/selinux/hb-selinux-localmod.xml b/xml/selinux/hb-selinux-localmod.xml new file mode 100644 index 0000000..8674b9f --- /dev/null +++ b/xml/selinux/hb-selinux-localmod.xml @@ -0,0 +1,134 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-localmod.xml,v 1.1 2006/10/15 20:32:39 pebenito Exp $ --> + +<sections> +<version>1.0</version> +<date>2006-10-15</date> + +<section><title>Introduction</title> +<subsection><body> +<p> + This guide discusses how to set up a policy module for local additions + of rules to the policy. +</p> +</body></subsection> +</section> + +<section><title>Preparation</title> +<subsection><body> +<p> + Copy the example Makefile from the selinux-base-policy doc directory to the + directory that will be used for building the policy. It is suggested that + /root be used. The places that the <c>semodule</c> tool can read policy + modules includes sysadm home directories. +</p> +<pre caption=""> +# <i>zcat /usr/share/doc/selinux-base-policy-20061008/Makefile.example.gz > /root/Makefile</i> +</pre> +</body></subsection> +</section> + +<section><title>Write a TE file</title> +<subsection><body> +<p> + In a policy module, most policy statements are usable in modules. + There are a few extra statements that must be added for proper operation. +</p> +<pre caption="Example local.te"> +policy_module(local,1.0) + +require { + type sysadm_su_t, newrole_t; +} +allow sysadm_su_t newrole_t:process sigchld; +</pre> +<p> + In addition to the basic allow rule, it has a couple statements required + by policy modules. The first is a policy_module() macro that has the + name of the module, and the module's version. It also has a require + block. This block specifies all types that are required for this module + to function. All types used in the module must either be declared in the + module or required by this module. +</p> +</body></subsection> +</section> + +<section><title>Write a FC File (optional)</title> +<subsection><body> +<p> + The file contexts file is optional and has the same syntax as as always. +</p> +<pre caption="Example local.fc"> +/opt/myprogs/mybin -- system_u:object_r:bin_t +</pre> +<p> + Types used in the file context file should be required or declared in + the TE file. +</p> +</body></subsection> +</section> + +<section><title>Compile Policy Modules</title> +<subsection><body> +<p> + Simply run <c>make</c> to build all modules in the directory. The module + will be compiled for the current policy as specified by /etc/selinux/config. +</p> +<pre caption=""> +# <i>make</i> +Compiling strict local module +/usr/bin/checkmodule: loading policy configuration from tmp/local.tmp +/usr/bin/checkmodule: policy configuration loaded +/usr/bin/checkmodule: writing binary representation (version 6) to tmp/local.mod +Creating strict local.pp policy package +</pre> +<p> + To build the module for a policy other than the configured policy, use the + <c>NAME=</c> option. +</p> +<pre caption=""> +# <i>make NAME=targeted</i> +Compiling targeted local module +/usr/bin/checkmodule: loading policy configuration from tmp/local.tmp +/usr/bin/checkmodule: policy configuration loaded +/usr/bin/checkmodule: writing binary representation (version 6) to tmp/local.mod +Creating targeted local.pp policy package +</pre> +</body></subsection> +</section> + +<section><title>Load the Modules</title> +<subsection><body> +<p> + The modules can be loaded into the currently configured policy simply + by using the load target of the Makefile. +</p> +<pre caption=""> +# <i>make load</i> +</pre> +<p> + The load target also respects the <c>NAME=</c> option. Alternatively, + the <c>semodule</c> command can be used to load individual modules. +</p> +<pre caption=""> +# <i>semodule -i local.pp</i> +</pre> +</body></subsection> +</section> + +<section><title>Building Reference Policy Modules</title> +<subsection><body> +<p> +The new Gentoo policy is based on the <uri link="http://oss.tresys.com/projects/refpolicy">SELinux Reference Policy</uri>. +For more information on building a complete Reference Policy module, see the +<uri link="http://oss.tresys.com/projects/refpolicy/wiki/GettingStarted">Reference Policy Wiki</uri>. +</p> +</body></subsection> +</section> + +</sections> diff --git a/xml/selinux/hb-selinux-loglocal.xml b/xml/selinux/hb-selinux-loglocal.xml new file mode 100644 index 0000000..7cc5506 --- /dev/null +++ b/xml/selinux/hb-selinux-loglocal.xml @@ -0,0 +1,166 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-loglocal.xml,v 1.7 2008/05/20 15:45:43 pebenito Exp $ --> + +<sections> +<version>1.4</version> +<date>2004-11-16</date> + +<section><title>Begin Here</title> +<subsection><body> +<p> + You must be in <c>sysadm_r</c> to perform these actions. +</p> +<p> + Run <c>sestatus -v</c>. Click the first context that doesn't match: +</p> +<table> +<tr><th>Process</th><th>Context</th></tr> +<tr><ti>Init context</ti><ti><uri link="#doc_chap2">system_u:system_r:init_t</uri></ti></tr> +<tr><ti>/sbin/agetty</ti><ti><uri link="#doc_chap3">system_u:system_r:getty_t</uri></ti></tr> +<tr><th>File</th><th>Context</th></tr> +<tr><ti>/bin/login</ti><ti><uri link="#doc_chap4">system_u:object_r:login_exec_t</uri></ti></tr> +<tr><ti>/sbin/unix_chkpwd</ti><ti><uri link="#doc_chap5">system_u:object_r:chkpwd_exec_t</uri></ti></tr> +<tr><ti>/etc/passwd</ti><ti><uri link="#doc_chap6">system_u:object_r:etc_t</uri></ti></tr> +<tr><ti>/etc/shadow</ti><ti><uri link="#doc_chap6">system_u:object_r:shadow_t</uri></ti></tr> +<tr><ti>/bin/bash</ti><ti><uri link="#doc_chap7">system_u:object_r:shell_exec_t</uri></ti></tr> +</table> +</body></subsection> +</section> + +<section><title>Incorrect Init Context</title> +<subsection><title>Verify Init Label</title> +<body> +<p> + There are several possible reasons why init may have the wrong context. + First, verify that init is labeled correctly, refer to the sestatus's output + for /sbin/init. If it is not <c>system_u:object_r:init_exec_t</c>, relabel sysvinit. +</p> +<pre caption="Fix init context"> +# <i>rlpkg sysvinit</i> +</pre> +</body></subsection> +<subsection><title>Verify Available Policy</title><body> +<p> + You must be in <c>sysadm_r</c> to perform this action. +</p> +<p> + A binary policy must be available in /etc/selinux/{strict,targeted}/policy. + If it is missing, then install the policy. +</p> +<pre caption="Install binary policy"> +# <i>semodule -n -B</i> +</pre> +</body> +</subsection> + +<subsection><title>Verify Init Can Load the Policy</title><body> +<p> + The final check is to ensure init can load the policy. Run <c>ldd</c> on + init, and if libselinux is not in the output, remerge sysvinit. +</p> +<pre caption="Check init linking"> +# <i>ldd /sbin/init</i> + linux-gate.so.1 => (0xffffe000) + <comment>libselinux.so.1 => /lib/libselinux.so.1 (0x40025000)</comment> + libc.so.6 => /lib/libc.so.6 (0x40035000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) +</pre> +<p> + Now reboot so init gains the correct context, and loads the policy. +</p> +</body></subsection> +</section> + +<section><title>Incorrect agetty Context</title> +<subsection><body> +<p> + Verify that agetty is labeled correctly. Refer to the sestatus's output + for /sbin/agetty. If it is not <c>system_u:object_r:getty_exec_t</c>, relabel + util-linux. Then restart all gettys. +</p> +<pre caption="Fix agetty context"> +# <i>rlpkg util-linux</i> +# <i>killall agetty</i> <comment>(they will respawn)</comment> +</pre> +<p> + All of the agettys should now be in the correct <c>system_u:object_r:getty_exec_t</c> + context. Try logging in again. +</p> +</body> +</subsection> +</section> + +<section><title>Incorrect Login Context</title> +<subsection><body> +<p> + The login program (/bin/login) is not labeled correctly. Relabel shadow. +</p> +<pre caption="Relabel shadow"> +# <i>rlpkg shadow</i> +</pre> +<p> + /bin/login should now be <c>system_u:object_r:login_exec_t</c>. + Try logging in again. +</p> +</body> +</subsection> +</section> + +<section><title>Incorrect PAM Context</title> +<subsection><body> +<p> + Sshd must be able to use PAM for authenticating the user. The PAM password + checking program (/sbin/unix_chkpwd) must be labeled correctly so + sshd can transition to the password checking context. Relabel PAM. +</p> +<pre caption="Fix unix_chkpwd context"> +# <i>rlpkg pam</i> +</pre> +<p> + The password checking program should now be <c>system_u:object_r:chkpwd_exec_t</c>. + Try loggin in again. +</p> +</body></subsection> +</section> + +<section><title>Incorrect Password File Contexts</title> +<subsection><body> +<p> + The password file (/etc/passwd), and the shadow file (/etc/shadow) must + be labeled correctly, otherwise PAM will not be able to + authenticate your user. Relabel the files. +</p> +<pre caption="Fix shadow context"> +# <i>restorecon /etc/passwd /etc/shadow</i> +</pre> +<p> + The password and shadow files should now be <c>system_u:object_r:etc_t</c> + and <c>system_u:object_r:shadow_t</c>, respectively. Try logging in again. +</p> +</body> +</subsection> +</section> + +<section><title>Incorrect Bash File Context</title> +<subsection><body> +<p> + Bash must be labeled correctly so the user can transition into the user + domain when logging in. Relabel bash. +</p> +<pre caption="Fix bash context"> +# <i>rlpkg bash</i> +</pre> +<p> + Bash (/bin/bash) should now be <c>system_u:object_r:shell_exec_t</c>. + Try logging in again. +</p> +</body> +</subsection> +</section> + +</sections> diff --git a/xml/selinux/hb-selinux-logremote.xml b/xml/selinux/hb-selinux-logremote.xml new file mode 100644 index 0000000..1a95f7b --- /dev/null +++ b/xml/selinux/hb-selinux-logremote.xml @@ -0,0 +1,177 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-logremote.xml,v 1.7 2008/05/20 15:45:43 pebenito Exp $ --> + +<sections> +<version>1.4</version> +<date>2004-11-16</date> + +<section><title>Begin Here</title> +<subsection><body> +<p> + You must be in <c>sysadm_r</c> to perform these actions. +</p> +<p> + Run <c>sestatus -v</c>. Click the first context that doesn't match: +</p> +<table> +<tr><th>Process</th><th>Context</th></tr> +<tr><ti>Init context</ti><ti><uri link="#doc_chap2">system_u:system_r:init_t</uri></ti></tr> +<tr><ti>/usr/sbin/sshd</ti><ti><uri link="#doc_chap3">system_u:system_r:sshd_t</uri></ti></tr> +<tr><th>File</th><th>Context</th></tr> +<tr><ti>/sbin/unix_chkpwd</ti><ti><uri link="#doc_chap4">system_u:object_r:chkpwd_exec_t</uri></ti></tr> +<tr><ti>/etc/passwd</ti><ti><uri link="#doc_chap5">system_u:object_r:etc_t</uri></ti></tr> +<tr><ti>/etc/shadow</ti><ti><uri link="#doc_chap5">system_u:object_r:shadow_t</uri></ti></tr> +<tr><ti>/bin/bash</ti><ti><uri link="#doc_chap6">system_u:object_r:shell_exec_t</uri></ti></tr> +</table> +</body></subsection> +</section> + +<section><title>Incorrect Init Context</title> +<subsection><title>Verify Init Label</title> +<body> +<p> + There are several possible reasons why init may have the wrong context. + First, verify that init is labeled correctly, refer to the sestatus's output + for /sbin/init. If it is not <c>system_u:object_r:init_exec_t</c>, relabel sysvinit. +</p> +<pre caption=""> +# <i>rlpkg sysvinit</i> +</pre> +</body></subsection> + +<subsection><title>Verify Available Policy</title><body> +<p> + You must be in <c>sysadm_r</c> to perform this action. +</p> +<p> + A binary policy must be available in + /etc/selinux/{strict,targeted}/policy. If it is missing, then install + the policy. +</p> +<pre caption="Install policy"> +# <i>semodule -n -B</i> +</pre> +</body> +</subsection> + +<subsection><title>Verify Init Can Load the Policy</title><body> +<p> + The final check is to ensure init can load the policy. Run <c>ldd</c> on + init, and if libselinux is not in the output, remerge sysvinit. +</p> +<pre caption=""> +# <i>ldd /sbin/init</i> + linux-gate.so.1 => (0xffffe000) + <comment>libselinux.so.1 => /lib/libselinux.so.1 (0x40025000)</comment> + libc.so.6 => /lib/libc.so.6 (0x40035000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000) +</pre> +<p> + Now reboot so init gains the correct context, and loads the policy. +</p> +</body></subsection> +</section> + +<section><title>Incorrect sshd Context</title> +<subsection><body> +<p> + Another possibility is sshd is not labeled correctly, meaning it is not running + in the right context. Relabel openssh, then restart sshd. +</p> +<pre caption=""> +# <i>rlpkg openssh</i> +# <i>/etc/init.d/sshd restart</i> +</pre> +</body></subsection> +</section> + +<section><title>Incorrect PAM Context</title> +<subsection><body> +<p> + Sshd must be able to use PAM for authenticating the user. The PAM password + checking program (/sbin/unix_chkpwd) must be labeled correctly so + sshd can transition to the password checking context. Relabel PAM. +</p> +<pre caption=""> +# <i>rlpkg pam</i> +</pre> +<p> + The password checking program should now be <c>system_u:object_r:chkpwd_exec_t</c>. + Try loggin in again. +</p> +</body></subsection> +</section> + +<section><title>Incorrect Password File Contexts</title> +<subsection><body> +<p> + The password file (/etc/passwd), and the shadow file (/etc/shadow) must + be labeled correctly, otherwise PAM will not be able to + authenticate your user. Relabel the files. +</p> +<pre caption=""> +# <i>restorecon /etc/passwd /etc/shadow</i> +</pre> +<p> + The password and shadow files should now be <c>system_u:object_r:etc_t</c> + and <c>system_u:object_r:shadow_t</c>, respectively. Try logging in again. +</p> +</body> +</subsection> +</section> + +<section><title>Incorrect Bash File Context</title> +<subsection><body> +<p> + Bash must be labeled correctly so the user can transition into the user + domain when logging in. Relabel bash. +</p> +<pre caption=""> +# <i>rlpkg bash</i> +</pre> +<p> + Bash (/bin/bash) should now be <c>system_u:object_r:shell_exec_t</c>. + Try logging in again. +</p> +</body> +</subsection> +</section> + +<section><title>Other sshd Issues</title> +<subsection><title>Valid Shell</title><body> +<p> + First, make sure the user has a valid shell. +</p> +<pre caption=""> +# <i>grep</i> <comment>username</comment> <i>/etc/passwd | cut -d: -f7</i> +/bin/bash <comment>(or your shell of choice)</comment> +</pre> +<p> + If the above command does not return anything, or the shell is wrong, + set the user's shell. +</p> +<pre caption=""> +# <i>usermod -s /bin/bash</i> <comment>username</comment> +</pre> +</body></subsection> +<subsection><title>PAM enabled</title><body> +<p> + PAM also must be enabled in sshd. Make sure this line + in <c>/etc/ssh/sshd_config</c> is uncommented: +</p> +<pre caption=""> +UsePAM yes +</pre> +<p> + SELinux currently only allows PAM and a select few programs direct access + to <c>/etc/shadow</c>; therefore, openssh must now + use PAM for password authentication (public key still works). +</p> +</body></subsection> +</section> +</sections> diff --git a/xml/selinux/hb-selinux-overview.xml b/xml/selinux/hb-selinux-overview.xml new file mode 100644 index 0000000..d02943d --- /dev/null +++ b/xml/selinux/hb-selinux-overview.xml @@ -0,0 +1,521 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-overview.xml,v 1.10 2010/06/25 16:07:19 pebenito Exp $ --> + +<sections> +<version>1.5</version> +<date>2009-07-13</date> + +<!-- +<section><title>Mandatory Access Control</title> +<subsection><body> +<p> + Security Enhanced Linux is an implementation of mandatory access control + (MAC) using type enforcement. In Linux, the regular security permissions + are a discretionary access control system (DAC). In DAC, the permissions + for a particular object, such as a file, are set at the discrection of the + owner and can be changed at any time by the owner. In MAC, the access a + process or user has to an object is defined by the operating system + security policy, and cannot be bypassed. +!!! still need to update other links in the handbook +</p> +</body></subsection> +</section> +--> +<section><title>SELinux Types</title> +<subsection><body> +<p> + A type is a security attribute given to objects such as files, and network + ports, etc. The type of a process is commonly referred to as its domain. + The SELinux policy is primarily composed of type enforcement rules, which + describe how domains are allowed to interact with objects, and how domains + are allowed to interact with other domains. A type is generally suffixed + with a '_t', such as <c>sysadm_t</c>. This is the most important + attribute for a process or object, as most policy decisions are based on + the source and target types. +</p> +</body></subsection> +</section> + +<section><title>SELinux Roles</title> +<subsection><body> +<p> + SELinux is type enforcement, so the SELinux role is not the same as those + in a role-based access control system. Permissions are not given to roles. + A role describes the set of types a user can use. For example, a system + administrator that is using the system for regular user tasks should be + in the <c>staff_r</c> role. If they need to administrate the system, then + a role change to <c>sysadm_r</c> is required. In SELinux terms, the + domains that a user can be in is determined by their role. If a role is not + allowed to have a certain domain, a transition to that domain will be denied, + even if the type enforcement rules allow the domain transition. A role is + generally suffixed with a '_r', such as <c>system_r</c>. +</p> +</body></subsection> +</section> + +<section><title>SELinux Identities</title> +<subsection><title>What is a SELinux Identity?</title><body> +<p> + The SELinux identity is similar to a Linux username. The change of identity + should be limited to very specific cases, since the role-based access control + relies on the SELinux identity. Therfore, in general, a user’s SELinux + identity will not change during a session. The user ID in Linux can be + changed by set(e)uid, making it inappropriate for a SELinux identity. + If a user is given a SELinux identity, it must match the Linux username. Each + SELinux identity is allowed a set of roles. +</p> +</body></subsection> + +<subsection><title>Configure SELinux Identity Mapping</title><body> +<p> + The SELinux policy has several generic SELinux identities that should + be sufficient for all users. This mapping only needs to be configured + on the strict policy. The identity mapping for the targeted policy + need not be configured, as the default identity (user_u) is sufficient + in all cases. +</p> +<p> + When a user logs in, the SELinux identity used is determined by this mapping. +</p> +<table> +<tr><th>SELinux Identity</th> + <th>Roles</th> + <th>Description</th></tr> +<tr><ti>system_u</ti> + <ti>system_r</ti> + <ti>System (non-interactive) processes. Should not be used on users.</ti></tr> +<tr><ti>user_u</ti> + <ti>user_r</ti> + <ti>Generic unprivileged users. The default identity mapping.</ti></tr> +<tr><ti>staff_u</ti> + <ti>staff_r, sysadm_r</ti> + <ti>System administrators that also log in to do regular user activties.</ti></tr> +<tr><ti>sysadm_u</ti> + <ti>sysadm_r</ti> + <ti>System administrators that only log in to do administrative tasks. It is not suggested that this identity is used.</ti></tr> +<tr><ti>root</ti> + <ti>staff_r, sysadm_r</ti> + <ti>Special identity for root. Other users should use staff_u instead.</ti></tr> +</table> +<p> + See the <uri link="selinux-handbook.xml?part=3&chap=2#doc_chap3">SELinux HOWTO</uri> + for semanage syntax for configuring SELinux identity mappings. +</p> +</body></subsection> + +</section> + +<section><title>SELinux Contexts</title> +<subsection><body> +<p> + Using the above three security models together is called a SELinux + context. A context takes the form <c>identity</c>:<c>role</c>:<c>type</c>. + The SELinux context is the most important value for determining access. +</p> +</body></subsection> + +<subsection><title>Object Contexts</title><body> +<p> + A typical <c>ls -Z</c> may have an output similar to this: +</p> +<pre caption="Example ls -Z output"> +drwxr-xr-x root root system_u:object_r:bin_t bin +drwxr-xr-x root root system_u:object_r:boot_t boot +drwxr-xr-x root root system_u:object_r:device_t dev +drwxr-xr-x root root system_u:object_r:etc_t etc +</pre> +<p> + The first three columns are the typical linux permissions, user and group. + The fourth column is the file or directory's security context. Objects + are given the generic <c>object_r</c> role. From the other two fields of + the context, it can be seen that the files are in the system identity, + and have four different types, <c>bin_t</c>, <c>boot_t</c>, <c>device_t</c>, + and <c>etc_t</c>. +</p> +</body></subsection> + +<subsection><title>Process Contexts</title><body> +<p> + A typical <c>ps ax -Z</c> may have an output similar to this: +</p> +<pre caption="Example ps ax -Z output"> + PID CONTEXT COMMAND + 1 system_u:system_r:init_t [init] + 2 system_u:system_r:kernel_t [keventd] + 3 system_u:system_r:kernel_t [ksoftirqd_CPU0] + 4 system_u:system_r:kernel_t [kswapd] + 5 system_u:system_r:kernel_t [bdflush] + 6 system_u:system_r:kernel_t [kupdated] + 706 system_u:system_r:syslogd_t [syslog-ng] + 712 system_u:system_r:httpd_t [apache] + 791 system_u:system_r:sshd_t [sshd] + 814 system_u:system_r:crond_t [cron] + 826 system_u:system_r:getty_t [agetty] + 827 system_u:system_r:getty_t [agetty] + 828 system_u:system_r:getty_t [agetty] + 829 system_u:system_r:getty_t [agetty] + 830 system_u:system_r:getty_t [agetty] + 831 system_u:system_r:httpd_t [apache] + 832 system_u:system_r:httpd_t [apache] + 833 system_u:system_r:httpd_t [apache] +23093 system_u:system_r:sshd_t [sshd] +23095 user_u:user_r:user_t [bash] +23124 system_u:system_r:sshd_t [sshd] +23126 user_u:user_r:user_t [bash] +23198 system_u:system_r:sshd_t [sshd] +23204 user_u:user_r:user_t [bash] +23274 system_u:system_r:sshd_t [sshd] +23275 pebenito:staff_r:staff_t [bash] +23290 pebenito:staff_r:staff_t ps ax -Z +</pre> +<p> + In this example, the typical process information is displayed, in addition + to the process's context. By inspection, all of the system's kernel + processes and daemons run under the <c>system_u</c> identity, and + <c>system_r</c> role. The individual domains depend on the program. + There are a few users logged in over ssh, using the generic <c>user_u</c> + identity. Finally there is a user with the identity <c>pebenito</c> logged in + with the <c>staff_r</c> role, running in the <c>staff_t</c> domain. +</p> +</body></subsection> + +</section> + +<section> +<title>SELinux Policy Files</title> +<subsection><body> +<p> + The SELinux policy source files are no longer installed onto the system. + In the <c>/usr/share/selinux/{strict,targeted}</c> directory there are a + collection of policy packages and headers for building local modules. + The policy files are processed by m4, and then the policy compiler <c>checkmodule</c> + verifies that there are no syntactic errors, and a policy module is created. + Then a policy package is created with with the <c>semodule_package</c> + program, using the policy module and the module file contexts. + The policy packaged then can be loaded into a running SELinux kernel + by inserting it into the module store. +</p> +</body></subsection> + +<subsection><title>*.pp</title><body> +<p> + Policy packages for this policy. These must be inserted into the module + store so they can be loaded into the policy. Inside the package + there is a loadable policy module, and optionally a file context file. +</p> +</body></subsection> + +<subsection><title>include/</title><body> +<p> + Policy headers for this policy. +</p> +</body></subsection> + +</section> + +<section> +<title>Binary Policy Versions</title> +<subsection><body> +<p> + When compiling the policy, the resultant binary policy is versioned. + The first version that was merged into 2.6 was version 15. + The version number is only incremented generally when new features are added that require changes to the structure of the compiled policy. + For example, in 2.6.5, conditional policy extensions were added. + This required the policy version to be incremented to version 16. +</p> +</body></subsection> +<subsection><title>What Policy Version Does My Kernel Use?</title> +<body> +<p> + The policy version of a running kernel can be determined by executing + <c>sestatus</c> or <c>policyvers</c>. Current kernels can load + the previous version policy for compatibility. For example a version 17 + kernel can also load a version 16 policy. However, this compatibility + code may be removed in the future. +</p> +<note> + The policy management infrastructure (libsemanage) will automatically + create and use the correct version policies. No extra steps need be taken. +</note> +</body></subsection> +<subsection><title>Policy Versions</title> +<body> +<p> + The following table contains the policy versions in 2.6 kernels. +</p> +<table> +<tr><th>Version</th> + <th>Description</th> + <th>Kernel Versions</th></tr> +<tr><ti>12</ti> + <ti>"Old API" SELinux (deprecated).</ti></tr> +<tr><ti>15</ti> + <ti>"New API" SELinux merged into 2.6.</ti> + <ti>2.6.0 - 2.6.4</ti></tr> +<tr><ti>16</ti> + <ti>Conditional policy extensions added.</ti> + <ti>2.6.5</ti></tr> +<tr><ti>17</ti> + <ti>IPV6 support added.</ti> + <ti>2.6.6 - 2.6.7</ti></tr> +<tr><ti>18</ti> + <ti>Fine-grained netlink socket support added.</ti> + <ti>2.6.8 - 2.6.11</ti></tr> +<tr><ti>19</ti> + <ti>Enhanced multi-level security.</ti> + <ti>2.6.12 - 2.6.13</ti></tr> +<tr><ti>20</ti> + <ti>Access vector table size optimizations.</ti> + <ti>2.6.14 - 2.6.18</ti></tr> +<tr><ti>21</ti> + <ti>Object classes in range transitions.</ti> + <ti>2.6.19 - 2.6.24</ti></tr> +<tr><ti>22</ti> + <ti>Policy capabilities (features).</ti> + <ti>2.6.25</ti></tr> +<tr><ti>23</ti> + <ti>Per-domain permissive mode.</ti> + <ti>2.6.26 - 2.6.27</ti></tr> +<tr><ti>24</ti> + <ti>Explicit hierarchy (type bounds).</ti> + <ti>2.6.28 - current</ti></tr> +</table> +</body></subsection> +</section> + +<section> +<title>Conditional Policy Extensions</title> +<subsection><body> +<p> + The conditional policy extensions allow the enabling and disabling of policy + rules at runtime, without loading a modified policy. Using policy booleans + and expressions, policy rules can be conditionally applied. +</p> +</body></subsection> + +<subsection><title>Determine Boolean Values</title> +<body> +<p> + The status of policy booleans in the current running policy can be determined + two ways. The first is by using <c>sestatus</c>. +</p> +<pre caption="Example sestatus output"> +# sestatus +SELinux status: enabled +SELinuxfs mount: /selinux +Current mode: enforcing +Policy version: 17 + +Policy booleans: +user_ping inactive +</pre> +<p> + The second is <c>getsebool</c> which is a simple tool that displays + the status of policy booleans, and if a value change is pending. +</p> +<pre caption="Example getsebool command"> +# getsebool -a +user_ping --> active: 0 pending: 0 +</pre> +</body></subsection> + +<subsection><title>Changing Boolean Values</title> +<body> +<p> + The value of a boolean can be toggled by using the <c>togglesebool</c> + command. Multiple booleans can be specified on the command line. The + new value of the boolean will be displayed. +</p> +<pre caption="Example togglesebool command"> +# togglesebool user_ping +user_ping: active +</pre> +<p> + The value of a boolean can be set specifically by using the <c>setsebool</c> + command. +</p> +<pre caption="Example setsebool command"> +# setsebool user_ping 0 +</pre> +<p> + To set the value of a boolean, and make it the devault value, use the <c>-P</c> option. +</p> +<pre caption="Change default value"> +# setsebool -P user_ping 1 +</pre> +</body></subsection> +</section> + +<section> +<title>Policy Kernel Messages</title> +<subsection><body> +<p> + While a system is running, a program or user may attempt to do something + that violates the security policy. If the system is enforcing the policy, + the access will be denied, and there will be a message in the kernel log. + If the system is not enforcing (permissive mode), the access will be allowed, + but there will still be a kernel message. +</p> +</body></subsection> + +<subsection><title>AVC Messages</title><body> +<p> + Most kernel messages from SELinux come from the access vector cache (AVC). + Understanding denials is important to understand if an attack is happening, + or if the program is requiring unexpected accesses. An example denial + may look like this: +</p> + +<pre caption="Example AVC Message"> +avc: denied { read write } for pid=3392 exe=/bin/mount dev=03:03 ino=65554 +scontext=pebenito:sysadm_r:mount_t tcontext=system_u:object_r:tmp_t tclass=file +</pre> + +<p> + While most AVC messages are denials, occasionally there might be an audit + message for an access that was granted: +</p> +<pre caption="Example AVC Message 2"> +avc: granted { load_policy } for pid=3385 exe=/usr/sbin/load_policy +scontext=pebenito:sysadm_r:load_policy_t tcontext=system_u:object_r:security_t tclass=security +</pre> +<p> + In this case, the ability to load the policy was granted. This is a critical + security event, and thus is always audited. Another event that is always + audited is switching between enforcing and permissive modes. +</p> + +<p> + SELinux will supress logging of denials if many are received in a short + amount of time. However, This does not always imply there is an attack + in progress. A program may be doing something that could cause + many denials in a short time, such as doing a stat() on device nodes in + /dev. To protect from filling up the system logs, SELinux has rate limiting + for its messages: +</p> + +<pre caption="Example AVC Message 3"> +AVC: 12 messages suppressed. +</pre> + +<p> + The policy would have to be modified to not audit these accesses if they + are normal program behavior, but still need to be denied. +</p> + +</body></subsection> + +<subsection><title>Other kernel messages</title> +<body> +<pre caption="inode_doinit_with_dentry"> +inode_doinit_with_dentry: context_to_sid(system_u:object_r:bar_t) returned 22 for dev=hda3 ino=517610 +</pre> +<p> + This means that the file on /dev/hda3 with inode number 517610 has the context + system_u:object_r:bar_t, which is invalid. Objects with an invalid context + are treated as if they had the system_u:object_r:unlabeled_t context. +</p> +</body></subsection> + +</section> + +<section><title>Dissecting a Denial</title> +<subsection><body> +<p> + Denials contain varying amounts of information, depending on the access type. +</p> + +<pre caption="Example Denials"> +avc: denied { lock } for pid=28341 exe=/sbin/agetty path=/var/log/wtmp dev=03:03 ino=475406 +scontext=system_u:system_r:getty_t tcontext=system_u:object_r:var_log_t tclass=file + +avc: denied { create } for pid=20909 exe=/bin/ls scontext=pebenito:sysadm_r:mkinitrd_t +tcontext=pebenito:sysadm_r:mkinitrd_t tclass=unix_stream_socket + +avc: denied { setuid } for pid=3170 exe=/usr/bin/ntpd capability=7 +scontext=system_u:system_r:ntpd_t tcontext=system_u:system_r:ntpd_t tclass=capability + +</pre> + +<p> + The most common denial relates to access of files. For better understanding, + the first denial message will be broken down: +</p> +<table> +<tr><th>Component</th><th>Description</th></tr> +<tr><ti>avc: denied</ti> + <ti>SELinux has denied this access.</ti></tr> +<tr><ti>{ lock }</ti> + <ti>The attempted access is a lock.</ti></tr> +<tr><ti>pid=28341</ti> + <ti>The process ID performing this access is 28341.</ti></tr> +<tr><ti>exec=/sbin/agetty</ti> + <ti>The full path and name of the process's executable is /sbin/agetty.</ti></tr> +<tr><ti>path=/var/log/wtmp</ti> + <ti>The path and name of the target object is /var/log/wtmp. Note: a complete + path is not always available.</ti></tr> +<tr><ti>dev=03:03</ti> + <ti>The target object resides on device 03:03 (major:minor number). + On 2.6 kernels this may resolve to a name, hda3 in this example.</ti></tr> +<tr><ti>ino=475406</ti> + <ti>The inode number of the target object is 475406.</ti></tr> +<tr><ti>scontext=system_u:system_r:getty_t</ti> + <ti>The context of the program is system_u:system_r:getty_t.</ti></tr> +<tr><ti>tcontext=system_u:object_r:var_log_t</ti> + <ti>The context of the target object is system_u:object_r:var_log_t.</ti></tr> +<tr><ti>tclass=file</ti> + <ti>The target object is a normal file.</ti></tr> +</table> + +<p> + Not all AVC messages will have all of these fields, as shown in the other + two denials. The fields vary depending on the target object's class. + However, the most important fields: access type, source and target contexts, + and the target object's class will always be in an AVC message. +</p> +</body></subsection> + +<subsection><title>Understanding the Denial</title><body> +<p> + Denials can be very confusing since they can be triggered for several reasons. + The key to understanding what is happening is to know the behavior of the + program, and to correctly interpret the denial message. The target is not + limited to files; it could also be related to network sockets, + interprocess communications, or others. +</p> +<p> + In the above example, the agetty is denied locking of a file. The file's type + is var_log_t, therefore it is implied that the target file is in /var/log. + With the extra information from the path= field in the denial message, it is + confirmed to be the file /var/log/wtmp. If path information was unavailable, + this could be further confirmed by searching for the inode. Wtmp is a file that has + information about users currently logged in, and agetty handles logins on + ttys. It can be concluded that this is an expected access of agetty, for + updating wtmp. However, why is this access being denied? Is there a flaw + in the policy by not allowing agetty to update wtmp? It turns out that wtmp + has the incorrect context. It should be system_u:object_r:wtmp_t, rather + than system_u:object_r:var_log_t. +</p> +<p> + If this access was not understood, an administrator might mistakenly allow getty_t + read/write access to var_log_t files, which would be incorrect, since agetty + only needs to modify /var/log/wtmp. This underscores how critical keeping + file contexts consistent is. +</p> +</body></subsection> +</section> + +<section><title>References</title> +<subsection><body> +<p> + <uri link="http://www.nsa.gov/selinux">U.S. National Security Agency</uri>, + SELinux Policy README +</p> +</body></subsection> +</section> +</sections> diff --git a/xml/selinux/hb-selinux-references.xml b/xml/selinux/hb-selinux-references.xml new file mode 100644 index 0000000..5bceac4 --- /dev/null +++ b/xml/selinux/hb-selinux-references.xml @@ -0,0 +1,111 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/hb-selinux-references.xml,v 1.5 2010/06/25 16:07:19 pebenito Exp $ --> + +<sections> +<version>1.2</version> +<date>2006-05-07</date> + + +<section><title>Background</title> +<subsection><body> +<ul> +<li> + <uri link="http://www.nsa.gov/research/_files/selinux/papers/inevit-abs.shtml">The Inevitability of Failure: + The Flawed Assumption of Security in Modern Computing Environments</uri> + explains the need for mandatory access controls.</li> +<li> + <uri link="http://www.nsa.gov/research/_files/selinux/papers/flask-abs.shtml">The Flask Security Architecture: + System Support for Diverse Security Policies</uri> + explains the security architecture of Flask, the architecture used by SELinux.</li> +<li> + <uri link="http://www.nsa.gov/research/_files/selinux/papers/module-abs.shtml">Implementing SELinux as a Linux Security Module</uri> + has specifics about SELinux access checks in the kernel.</li> +</ul> +</body> +</subsection> +</section> + +<section><title>Policy</title> +<subsection><body> +<ul> +<li> + <uri link="http://www.nsa.gov/research/_files/selinux/papers/policy2-abs.shtml">Configuring the SELinux Policy</uri></li> +<li> + <uri link="http://oss.tresys.com/projects/refpolicy">SELinux Reference Policy</uri></li> +<li> + SELinux <uri link="http://www.selinuxproject.org/page/ObjectClassesPerms">Object Classes and Permissions</uri> + Overview</li> +</ul> +</body> +</subsection> +</section> + +<section><title>Books</title> +<subsection><body> +<ul> +<li> + <c>SELinux by Example: Using Security Enhanced Linux</c>, Frank Mayer, + Karl MacMillan, and David Caplan, Prentice Hall, 2006; ISBN 0131963694</li> +<li> + <c>SELinux: NSA's Open Source Security Enhanced Linux</c>, Bill McCarty, + O'Reilly Media, 2004; ISBN 0596007167</li> +</ul> +</body> +</subsection> +</section> + +<section><title>Meeting Notes</title> +<subsection><body> +<ul> +<li> + <uri link="http://www.selinux-symposium.org/2006/summit.php">March 3rd, 2006 SELinux Developer Summit</uri></li> +<li> + <uri link="http://www.selinux-symposium.org/meeting.php">May 6th, 2004 Informal Meeting</uri></li> +</ul> +</body> +</subsection> +</section> + +<section><title>Presentations</title> +<subsection><title>2006 SELinux Symposium</title><body> +<ul> +<li> + <uri link="http://www.nsa.gov/selinux/papers/selsymp2006-abs.cfm">SELinux Year in Review</uri>, + Stephen Smalley, National Security Agency</li> +<li> + <uri link="http://www.selinux-symposium.org/2006/slides/03-refpolicy-slides.pdf">Reference Policy for Security Enhanced Linux</uri>, + Karl MacMillan, Tresys Technology (<uri link="http://www.selinux-symposium.org/2006/papers/05-refpol.pdf">Paper</uri>)</li> +</ul> +</body> +</subsection> +<subsection><title>2005 SELinux Symposium</title><body> +<ul> +<li> + <uri link="http://www.nsa.gov/research/selinux/index.shtml">SELinux Overview</uri>, + NSA</li> +<li> + <uri link="http://www.selinux-symposium.org/2005/presentations/session3/3-2-macmillan.pdf">Core Policy Management Infrastructure for SELinux</uri>, + Karl MacMillan, Tresys Technology</li> +<li> + <uri link="http://www.selinux-symposium.org/2005/presentations/session4/4-1-walsh.pdf">Targeted vs. Strict Policy History and Strategy</uri>, + Dan Walsh, Red Hat</li> +<li> + <uri link="http://www.selinux-symposium.org/2005/presentations/session4/4-4-mayer.pdf">Tresys SETools: Tools and Libraries for Policy Analysis and Management</uri>, + Frank Mayer, Tresys Technology</li> +<li> + <uri link="http://www.selinux-symposium.org/2005/presentations/session5/5-3-macmillan.pdf">Information Flow Analysis for Type Enforcement Policies</uri>, + Karl MacMillan, Tresys Technology</li> +<li> + <uri link="http://www.selinux-symposium.org/2005/presentations/session6/6-2-mayer.pdf">SELinux Policy Analysis Concepts and Techniques</uri>, + David Caplan, Frank Mayer, Tresys Technology</li> +</ul> +</body> +</subsection> +</section> + +</sections> diff --git a/xml/selinux/index.xml b/xml/selinux/index.xml new file mode 100644 index 0000000..888caf1 --- /dev/null +++ b/xml/selinux/index.xml @@ -0,0 +1,146 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?> +<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> +<!DOCTYPE project SYSTEM "/dtd/project.dtd"> +<!--$Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/index.xml,v 1.41 2009/07/22 13:38:18 pebenito Exp $--> +<project> + +<name>SELinux</name> +<longname>SELinux</longname> + +<description> + SELinux is a system of mandatory access controls. SELinux can enforce + the security policy over all processes and objects in the system. +</description> + +<longdescription><p> + This project manages SELinux support in Gentoo. This includes providing + kernels with SELinux support, providing patches to userland utilities, writing + strong Gentoo-specific default profiles, and deploying policies from Portage. +</p></longdescription> + +<goals><p> + The intention of the project is to make SELinux available to more users, and + improving its integration. + Policy should be available for common daemons, and files merged in from Portage + should have the correct file context. Currently we only work on servers, but + desktops will be supported in the future. +</p></goals> + +<extrachapter position="goals"> +<title>What is SELinux?</title> +<section><body> +<p> + <uri link="http://www.nsa.gov/selinux">Security-Enhanced Linux</uri> (SELinux) + is a system of mandatory access control using type enforcement and role-based + access control. It is implemented as a + <uri link="http://lsm.immunix.org/">Linux Security Module</uri> (LSM). + In addition to the kernel portion, SELinux consists of a library (libselinux) + and userland utilities for compiling policy (checkpolicy), and loading policy + (policycoreutils), in addition to other user programs. +</p> +<p> + One common misconception is that SELinux is a complete security solution, + however, it is not. SELinux only provides one piece of a security + solution. It can work well with other Hardened projects, such as PaX, + for a more complete solution. +</p> +</body></section> +</extrachapter> + +<dev role="lead" description="Policy, x86, AMD64">pebenito</dev> + +<extraproject name="Base Policy" lead="pebenito"> + SELinux policy for the core system, including users, administrators, and + daemons in the system profile. +</extraproject> +<extraproject name="Daemon Policy"> + SELinux policies for common daemons. +</extraproject> +<extraproject name="x86" lead="pebenito"> + Support for the x86 architecture. +</extraproject> +<extraproject name="AMD64" lead="pebenito"> + Support for the AMD64 (x86-64) architecture. +</extraproject> + +<plannedproject name="non-x86 Support"> + Profiles, installation guides, and support for non-x86 architectures. +</plannedproject> +<plannedproject name="Desktop"> + SELinux support on destktops. This involves enhancements to XFree's + security, and accompanying policy. +</plannedproject> + +<!-- +<resource link="http://selinux.dev.gentoo.org">SELinux Demonstration Machine</resource> +--> +<resource link="http://www.gentoo.org/proj/en/hardened/selinux/selinux-handbook.xml">Gentoo SELinux Handbook</resource> + +<extrachapter position="resources"> +<title>How Do I Use This?</title> +<section> +<body> +<p> + SELinux can be installed on a new system by following the above install guide. +</p> +</body> +</section> +</extrachapter> + +<extrachapter position="bottom"> +<title>I Want to Participate</title> +<section> +<body> +<p> + To participate in the SELinux project first join the mailing list at + <c>gentoo-hardened@gentoo.org</c>. Then ask if there are plans to support + something that you are interested in, propose a new subproject that you are + interested in or choose one of the planned subprojects to work on. You may talk + to the developers and users in the IRC channel <c>#gentoo-hardened</c> on + <c>irc.freenode.net</c> for more information or just to chat about the project + or any subprojects. If you don't have the ability to actively help by + contributing work we will always need testers to use and audit the SELinux + policies. All development, testing, feedback, and productive comments will + be greatly appreciated. +</p> +</body> +</section> +<section><title>Policy Submissions</title> +<body> +<p> + The critical component of a SELinux system is having a strong policy. The + team does its best to support as many daemons as possible. However, we cannot + create policies for daemons with which we are unfamiliar. But we are happy + to receive policy submissions for consideration. There are a few requirements: +</p> +<ul> +<li> + Make comments (in the policy and/or bug), so we can understand changes + from the NSA example policy. +</li> +<li> + The policy should cover common installations. Please do not submit policies + for odd or nonstandard daemon configurations. +</li> +<li> + We need to know if the policy is dependent on another policy (for example + rpcd is dependent on portmap) other than base-policy. +</li> +<li> + An ebuild for the policy can also be submitted to help the developers + integrate the policy into Portage more quickly, if it is accepted. + See current daemon policies in Portage for example uses of the + selinux-policy eclass. +</li> +</ul> +<p> + The policy should be submitted on <uri link="http://bugs.gentoo.org/">bugzilla</uri>. + Please attach the .te and .fc files separately to the bug, not as a tarball. + The bug should be assigned to <c>selinux@gentoo.org</c>. +</p> +</body> +</section> +</extrachapter> + +</project> diff --git a/xml/selinux/selinux-handbook.xml b/xml/selinux/selinux-handbook.xml new file mode 100644 index 0000000..0a11e4f --- /dev/null +++ b/xml/selinux/selinux-handbook.xml @@ -0,0 +1,151 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE book SYSTEM "/dtd/book.dtd"> + +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/hardened/selinux/selinux-handbook.xml,v 1.9 2010/06/25 16:07:19 pebenito Exp $ --> + +<book link="selinux-handbook.xml"> +<title>Gentoo SELinux Handbook</title> + +<author title="Author"> + <mail link="pebenito@gentoo.org">Chris PeBenito</mail> +</author> + +<author title="Author"> + Chris Richards +</author> + +<abstract> +This is the Gentoo SELinux Handbook. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> +<license/> + +<version>2.00</version> +<date>2006-10-15</date> + +<part> +<title>Installing Gentoo SELinux</title> +<abstract> +In this part you learn how to install Gentoo SELinux on your system. +</abstract> + +<chapter> +<title>Gentoo SELinux Installation</title> +<abstract> +How to do a fresh installation of Gentoo SELinux. +</abstract> + <include href="hb-install.xml"/> +</chapter> +</part> + +<part> +<title>Converting to Gentoo SELinux</title> +<abstract> +SELinux alternatively can be installed on current Linux installations. This +Chapter deals with converting a prexisting Gentoo install to SELinux. +</abstract> +<chapter> +<title>Initial preparations</title> +<abstract> +A few preparations must be done before installing SELinux packages. +</abstract> + <include href="hb-selinux-conv-profile.xml"/> +</chapter> +<chapter> +<title>Boot SELinux Kernel</title> +<abstract> +Install and boot a SELinux kernel. +</abstract> + <include href="hb-selinux-conv-reboot1.xml"/> +</chapter> +<chapter> +<title>Install SELinux Userland</title> +<abstract> +Install SELinux packages and policy, and label filesystems. +</abstract> + <include href="hb-selinux-conv-reboot2.xml"/> +</chapter> +</part> + +<part> +<title>Working with SELinux</title> +<abstract> +Learn how to work with SELinux +</abstract> +<chapter> +<title>SELinux Overview</title> +<abstract> +SELinux has many parts to understand. This chapter discusses SELinux's +important concepts and policy. +</abstract> + <include href="hb-selinux-overview.xml"/> +</chapter> +<chapter> +<title>SELinux HOWTO</title> +<abstract> +This chapter deals with how to common operations in SELinux. +</abstract> + <include href="hb-selinux-howto.xml"/> +</chapter> +<chapter> +<title>SELinux FAQ</title> +<abstract> +This chapter deals with frequently asked questions in SELinux. +</abstract> + <include href="hb-selinux-faq.xml"/> +</chapter> +<chapter> +<title>SELinux Management Infrastructure</title> +<abstract> +The chapter deals with managing SELinux using the management infrastructure. +</abstract> + <include href="hb-selinux-libsemanage.xml"/> +</chapter> +<chapter> +<title>Local Policy Modules</title> +<abstract> +The chapter deals with adding rules and new modules to your policy. +</abstract> + <include href="hb-selinux-localmod.xml"/> +</chapter> +<chapter> +<title>SELinux Reference Materials</title> +<abstract> +This has a list of external references on SELinux. +</abstract> + <include href="hb-selinux-references.xml"/> +</chapter> +</part> + +<part> +<title>Troubleshooting SELinux</title> +<abstract> +When encountering problems on a machine, SELinux can add extra difficulty +in fixing the problem. This chapter walks through fixing common problems. +</abstract> +<chapter> +<title>Policy Not Loaded on Boot</title> +<abstract> +This chapter deals with the problem of the policy not being loaded on boot. +</abstract> + <include href="hb-selinux-initpol.xml"/> +</chapter> +<chapter> +<title>Trouble Logging in Locally</title> +<abstract> +This chapter deals with problems logging in locally at the console. +</abstract> + <include href="hb-selinux-loglocal.xml"/> +</chapter> +<chapter> +<title>Trouble Logging in Remotely</title> +<abstract> +This chapter deals with problems logging in remotely by ssh. +</abstract> + <include href="hb-selinux-logremote.xml"/> +</chapter> +</part> + +</book> diff --git a/xml/tmpas b/xml/tmpas new file mode 100644 index 0000000..4f04d7d --- /dev/null +++ b/xml/tmpas @@ -0,0 +1 @@ +]&~o#MTV^"ZG:<nxeNg4cM0K^C"}Qi~:TXcBFl!nq=0x( rer\?o_'KwZutkp# diff --git a/xml/toolchain-upgrade-guide.xml b/xml/toolchain-upgrade-guide.xml new file mode 100644 index 0000000..6fb7fa4 --- /dev/null +++ b/xml/toolchain-upgrade-guide.xml @@ -0,0 +1,275 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> + +<guide link="/proj/en/hardened/toolchain-upgrade-guide.xml" lang="en" disclaimer="draft"> +<title>GCC-4/GLIBC-2.5 Hardened Toolchain Overview and Upgrade Guide (EARLY DRAFT)</title> + +<author title="Author"> +<mail link="kevquinn@gentoo.org">Kevin F. Quinn</mail> +</author> + +<abstract> +Guide for upgrading from hardened gcc-3/glibc-2.3/binutils-2.16 to gcc-4/glibc-2.5/binutils-2.17. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> +<license/> + +<version>1.0</version> +<date>2007-02-22</date> + + +<chapter id="Introduction"> +<title>Introduction</title> + +<section id="Rationale"> +<title>Rationale for re-working the hardened toolchain.</title> +<body> + +<p> +The gcc-3/glibc-2.3 toolchain has been working reasonably well for +<uri link="/proj/en/hardened/">Hardened Gentoo</uri> +for a few years now. However while it has gained in maturity, there are a +number of known issues that have proven unresolvable so far. Most issues are +relatively minor and only show up in rare circumstances, however it has become +increasingly clear that the Stack Smash Protector (SSP) implementation in gcc-3 +that was developed at IBM has some serious issues most especially with code +constructs of C++ (and also C, where gcc permits some C++ idioms to be used also +in C). +</p> + +<p> +In gcc-4, Richard Henderson and others at RedHat +<uri link="http://gcc.gnu.org/ml/gcc-patches/2005-05/msg01193.html">completely re-implemented</uri> +the stack smash protector, making a number of improvements in the process. +Internally to GCC, the implementation is significantly different, although the +end result and the behaviour of the generated object code is much the same. +Unfortunately, the re-implementation did not retain binary compatibility with +the implementation we used previously, so we could not just simply bump our +patches to support the newer toolchain without doing some work. +</p> + +<p> +It was also clear that migrating to gcc-4 was not going to be trivial for the +standard Gentoo product, let alone Hardened Gentoo. Other changes to gcc (the +reason it gained a major version number increment) highlighted much code that +worked on gcc-3 often for the wrong reasons, but failed with gcc-4. Thus it +seemed like the ideal opportunity to re-examine the hardened toolchain +modifications to see if it could be done better and more consistently, since it +was apparent it would be some time before gcc-4 could be considered practical. +While the overall concepts for the hardened toolchain are largely the same, a +significant amount of work has gone into this task leading to hopefully a more +reliable and maintainable product. Hopefully it was worth it! +</p> +</body> +</section> + +<section id="overview"> +<title>Overview of the gcc-4/glibc-2.5/binutils-2.17 toolchain for Hardened Gentoo</title> +<body> + +<p> +As mentioned above, the SSP implementation has changed substantially. Changes +to the interfaces used by gcc to handle stack overflows, and changes to the +semantics of the stack-protector compiler switches, have lead to modifications +of glibc so that it can support both the old and new interfaces, and +modifications to the way the SSP compiler switches are managed to avoid having +to modify ebuilds. +</p> + +<p> +The other major plank of the hardened toolchain with respect to gcc, Position +Independent Executables (PIEs) has not changed; the support in gcc-4 is no +different from the support in gcc-3 which has been maintained upstram. However, +in order to support the default-PIE some changes have been made which should +mean that building executables will always use a consistent set of startfiles +and libraries. Previously there were occasions where odd results were observed; +particularly when building "-static". Static builds now result in a static/PIE +hybrid executable that should be stable on all architectures. +</p> + +<p> +The other two elements of the hardened toolchain, RELRO and BIND_NOW, are +effectively no different than they were before. +</p> + +<p> +In addition to the support changes necessary for SSP and the PIE cleanup, the +way compiler "specs" are handled ("specs" are configuration text used by the +compiler driver to control how the various components; the C compiler, C++ +compiler, linker, assembler etc are invoked) has been reworked. Previously we +patched the compiler driver code significantly to inject our altered default +specs, and did so repeatedly in various combinations to get us the several +variants of the hardened compiler that are provided. The new approach still +patches the compiler driver, but once only and much, much less intrusively, +adding "call-outs" to "mini-specs" that are by default defined to behave as the +vanilla compiler does, but can be easily overridden to achieve the hardened +toolchain behaviour we desire. The altered specs are managed by appending +re-definitions of these "mini-specs" to the standard specs, overriding the +defaults in a much less architecture-dependent way. +</p> + +<p> +A detailed description of the new toolchain modifications can be found in the +<uri link="hardened-toolchain.xml">Technical Description of the Gentoo Hardened Toolchain</uri>. +</p> +</body> +</section> +</chapter> + + +<chapter id="UpgradeGuide"> +<title>Upgrade Guide</title> +<section id="Dependencies"> +<title>Dependencies</title> +<body> + +<p> +There are a number of build and run-time dependencies between the various toolchain +elements. A brief elaboration of these will make it clear why the recommended +upgrade path is as it is. +</p> + +<ul> +<li>Hardened gcc-4 requires glibc-2.5 for ssp support functions</li> +<li>The new reliable "static PIE" support means hardened glibc-2.5 must be built with hardened gcc-4</li> +<li>"static PIE" support requires binutils-2.17</li> +</ul> + +<p> +Of particular note, is the circular dependency between hardened gcc-4 and hardened glibc-2.5. +Note that these dependencies are only relevant when hardened. +</p> +</body> +</section> +<section id="Sequence"> +<title>Upgrade Sequence</title> +<body> + +<p> +The upgrade path is quite simple really. Upgrade to binutils-2.17 if necessary, +and ensure it is selected. Then, using the vanilla compiler, build both glibc +and gcc non-hardened - this installs all the support necessary to build them +hardened. Next, switch to the new compiler -hardened variant, rebuild glibc +and gcc. Ensure the hardened compiler is selected (reselect to be sure). +</p> + +<p> +Switch off distcc and ccache if you're using them, to be sure you don't get mixed +results from previous compilations (especially if you have tried earlier versions +of the toolchain upgrade from overlays). +</p> + +<p> +In detail, the steps are: +</p> + +<p> +Ensure sys-devel/binutils-2.17 is installed: +</p> + +<pre caption="Check binutils version"> +binutils-config -l +</pre> + +<p> +If the version selected (highlighted with '*') is 2.17, that's enough. If 2.17 is +installed but not selected, select it with <c>binutils-config</c> - otherwise merge it: +</p> + +<pre caption="Merge binutils-2.17"> +emerge --oneshot =sys-devel/binutils-2.17 +</pre> + +<p> +and switch to it if necessary using <c>binutils-config</c>. Next, switch to the vanilla gcc: +</p> + +<pre caption="Select vanilla gcc"> +gcc-config -l +gcc-config <current gcc>-vanilla +source /etc/profile +</pre> + +<p> +replacing <current gcc> with the current compiler name (or just choose the right number from the list). +</p> + +<p> +Merge vanilla glibc-2.5 and gcc-4: +</p> + +<pre caption="Merging vanilla toolchain"> +USE="-hardened" emerge --oneshot =sys-libs/glibc-2.5 +USE="-hardened" emerge --oneshot =sys-devel/gcc-4.1.2 +</pre> + +<p> +There are a number of known test failures with both glibc and gcc on a hardened +system. The glibc build will stop after the test failures. Complete the glibc +build either using ebuild (if you know what you're doing) or do the build again +with <c>FEATURES="-test"</c>. The gcc build will carry on regardless, it'll +install and merge despite the failures. Once both are installed, switch to +the hardened gcc: +</p> + +<pre caption="Select hardened gcc"> +gcc-config -l +gcc-config <new gcc>-hardened +source /etc/profile +</pre> + +<p> +replacing <new gcc> with the new compiler name. +</p> + +<p> +Merge hardened glibc-2.5 and gcc-4: +</p> + +<pre caption="5: Merging hardened toolchain"> +emerge --oneshot =sys-libs/glibc-2.5 +emerge --oneshot =sys-devel/gcc-4.1.2 +</pre> + +<p> +Rebuild world with the new toochain: +</p> + +<pre caption="6: Rebuilding world"> +emerge -e world +</pre> + +<p> +That last - rebuilding world - does not have to be done immediately; existing +binaries should continue to run correctly against the upgraded glibc, and +portage should have left your previous compile in place since it's a major +revision change. It is probably a good idea to rebuild binutils with the new +toolchain (repeat 2.2) at least. See also the standard +<uri link="/doc/en/gcc-upgrading.xml">Gentoo GCC Upgrade Guide</uri> +advice on common GCC upgrade pitfalls. +</p> +</body> +</section> +</chapter> + + +<chapter id="references"> +<title>References</title> + +<section id="gentoorefs"> +<title>Other Gentoo Documentation</title> +<body> + +<ul> +<li><uri link="/proj/en/hardened/hardened-toolchain.xml"> +Technical Description of the Gentoo Hardened Toolchain</uri></li> +<li><uri link="/doc/en/gcc-upgrading.xml">Standard Gentoo GCC Upgrade Guide</uri></li> +</ul> + +</body> +</section> + +</chapter> +</guide> |