Project:Hardened uClibc

All modern operating systems are comprised of a kernel and userland layer. While the kernel deals directly with hardware resources at the highest privilege level, userland deals with the end user and operates at the lowest level. The two layers communicate with one another via system calls (or "syscalls" for short), which userland issues to the kernel. While any userland application can issue syscalls directly (eg. in x86 ISA, via an INT 0x80), almost all userland syscalls on a typical UNIX system are channeled via one central library referred to as the C standard library. Along with the compiler and other utilities to manipulate executable binaries (eg. binutils), it forms an integral part of the toolchain, and remains a runtime dependency of nearly every dynamically linking object in the system. By far, the most popular is "The GNU C library", or glibc for short; but, for embedded systems uClibc is the standard library of choice, although there are other competitors (see musl ). uClibc (where the "u" is sometimes written as the Greek µ for "micro") is much smaller than glibc, less bloated, much faster, and very configurable.

Continued developments in uClibc have made it increasingly suitable for systems like Lilblue, our security-enhanced, fully featured XFCE4 desktop, amd64 system built on uClibc. The recent addition of the native POSIX thread library (see nptl) meant that we could finally implement our complete complement of tool chain hardening from glibc:


 * Stack Smashing Protection (SSP), which came with nptl;
 * Position Independent Execution (PIE);
 * Bind now and relro, linker hardening to protect the global offset table

These are augmented by the kernel hardening, especially PaX's enhanced Address Space Layout Randomization (ASLR).

So, this sub-project aims to port both tool chain and kernel hardening to uClibc based systems for a variety of architectures, treating uClibc more as a drop in alternative to glibc, and not necessarily as "embedded". Embedded systems aim to produce kernels and user lands with tiny footprints, and so tend to use busybox as their "Swiss Army Knife" of common UNIX utilities. While not excluding this possibility, we aim at making most (all?) of Gentoo's packages both hardened and uClibc compatible.

Migration to uClibc-ng
At the time of this writing, September 2016, uClibc has not pushed out a release since May 2012 and has not committed a change since June 2015. For all intents and purposes, it is a dead project. However, the codebase has been forked and a new project uClibc-ng is being actively maintained. So, on Oct 1, 2016, we will be migrating over all stage3’s to uClibc-ng. For users starting from fresh, you should not notice any changes. But for users who have production systems running uClibc, you will have to migrate over. Unfortunately, there is no simple migration path, but the following mini HOWTO should work. It is recommended that you back up everything before proceeding and be prepared to boot into a rescue environment where you can chroot into your system to do repairs should something go wrong.


 * Before you begin, make sure your file is to your liking, or make sure the correct USE flags are enabled.  The config file provided in the stage3’s and on the releng overlay for your architecture should work.  For example, for hardened amd64, you can use this config.  In particular, if UCLIBC_HAS_OBSTACK is off when upgrading, you can expect catastrophic failure!


 * First build sys-libs/uclibc-ng, and install it in, but don’t merge it onto the root file system. Both sys-libs/uclibc and uclibc-ng hard block one another, so you can't just .  Even if you could, it would break your system since portage removes sys-libs/uclibc from the system completely before it installs sys-libs/uclibc-ng.  This is not an atomic operation, so as soon as uclibc is off, every ELF object linking against libc.so breaks.  So we will be merging the package onto the root file system manually:


 * Make a copy of in case we need to restore our system!


 * Next carefully move all the contents of to .  You probably could do a direct copy from, but it might be a good idea use a copy on the same filesystem as , in case you have NFS running or something.  The  needs to be an atomic operation, or at least near atomic.  Be careful with this step because this is where you might break your system.


 * Now let’s make sure that when we copied the files over from we clobbered the old sym links and that they are pointing to the correct files.

You should find that, or whatever version of sys-libs/uclibc-ng you’re working with. If it still ponits to a version like 0.9.33.2, then you're still using the old uclibc .so's.


 * At this point, we can clean out of the old uclibc files.  We’ll move them out of the way rather than delete them, just in case we might need them again.


 * Congratulations, your system has been converted to sys-libs/uclibc-ng, but portage still thinks you have sys-libs/uclibc installed. We have to manually delete portage’s records of uclibc and emerge sys-libs/uclibc-ng at least once, although twice is better.

The first time you emerge, you’ll get a bunch of file collisions reported by portage. These are the files you put on the file system when you copied over your libraries from above. They are harmless and portage will overwrite those files with the same files again. The second emerge should go smoothly. Again, you could skip that step, but it doesn’t hurt as a check that emerging uclibc-ng now works smoothly.


 * You're done, and you should be able to continue working with uclibc-ng as your libc provider. Although it shouldn't happen, you might find that something wants to pull in uclibc instead of uclibc-ng.  If so, just hard mask uclibc in.

Goals
The project goals can be best summarized by the following chart:

Participation
To participate in the Hardened uClibc project join the mailing list at [mailto:gentoo-hardened@gentoo.org gentoo-hardened@gentoo.org] and visit our online IRC channel at on Freenode.

Resources
The Hardened uClibc project provides the following resources:


 * Lilblue, a hardened uClibc XFCE desktop