Project:LibreSSL

LibreSSL
Description	LibreSSL is a fork of, and drop in replacement for OpenSSL. Primary development is done in OpenBSD, but it is ported to Linux as well. The LibreSSL project aims to bring support for this alternative SSL provider to Gentoo Linux.
Project email	libressl@gentoo.org
IRC channel	#gentoo-dev
Lead(s)	Anthony G. Basile (blueness) Developer Last elected: 2016/05/15
Member(s)	Aaron Bauman (bman) Developer David Seifert (soap) Developer Jason A. Donenfeld (zx2c4) Developer
Subproject(s) (and inherited member(s))	(none)
Parent Project	Gentoo
Project listing

LibreSSL is a fork of, and drop-in replacement for OpenSSL. It was originally a response to the infamous heartbleed vulnerability, which was a serious security flaw in one of the most popular SSL providers in use. So, some OpenBSD developers decided that they would fork in order to "modernize the codebase, improve security, and apply best practice development processes." While LibreSSL has not been without its own vulnerabilities (see below), some of which it shared with OpenSSL, there has been improvements with its emphasis on security. For example, the LibreSSL team's response to the POODLE vulnerability was to disable the use of SSL 3.0 by default.

LibreSSL is not without its criticisms, however. Despite the fact that LibreSSL has as a stated goal complete API compatibility with OpenSSL, as a fork, its ABI may diverge over time, creating subtle incompatibility as a simple drop-in replacement. This is worse than some package simply not build against LibreSSL. Rather, a package built against OpenSSL may later link and run against LibreSSL, should one library be replaced with the other, but that package may misbehave. The size of some struct be off by a few bytes, or the parameters of some function might not align in the same way. This in turn can lead to unpredictable behavior, crashes or worse, exploits. So LibreSSL has been criticized for using the same library file name and even the same SONAME as OpenSSL.

So the project of porting LibreSSL to Gentoo must not be ignorant of the possible (inevitable?) ABI incompatibilities between the two. We cannot support a system where one can just switch between OpenSSL and LibreSSL without subsequently rebuilding their dependencies to make sure any ABI incompatibilities are addressed. https://github.com/gentoo/libressl

Migration to the Gentoo Repository - Direction for developers

Much of the preliminary work has been done on GitHub. There an overlay has been set up to test ebuilds for difficult packages before they land in the tree. For most packages, migration is as simple as just replacing the openssl atom with a choice between openssl and libressl. Here are some examples:

CODE

ssl? ( dev-libs/openssl:0 )

with

CODE

ssl? (
    !libressl? ( dev-libs/openssl:0= )
    libressl? ( dev-libs/libressl:0= )
)

Notice that we add the sub-slot operator for both libressl and openssl.

Or in some cases, we may need to expand this as follows:

CODE

ssl? (
   gnutls? ( net-libs/gnutls )
   !gnutls? (dev-libs/openssl:0= )
)

with

CODE

ssl? (
    gnutls? ( net-libs/gnutls )
    !gnutls? (
        !libressl? ( dev-libs/openssl:0= )
        libressl? ( dev-libs/libressl:0= )
    )
)

some maintainers also use REQUIRED_USE constructs for packages supporting a whole array of SSL implementations:

CODE

REQUIRED_USE="ssl? ( ^^ ( openssl polarssl gnutls nettle ) )"

ssl? (
    openssl? (
        !libressl? ( dev-libs/openssl:0= )
        libressl? ( dev-libs/libressl:0= )
    )
    polarssl? ( net-libs/mbedtls:= )
    gnutls? ( net-libs/gnutls:= )
    nettle? ( dev-libs/nettle:= )
)

Either the former prioritised USE clauses or REQUIRED_USE constructs are permissible. The important point to note is that USE=libressl acts as a discriminating flag between OpenSSL and LibreSSL. As such, it is not a pure implementation USE flag and is analogous to USE=libav. That is, USE=libressl is never mutually exclusive to any other USE flag and should therefore never appear in REQUIRED_USE.

To keep track of what packages have been migrated and which haven't there is a list on GitHub. After making changes, please remove the package(s) from that list so we know what's remaining.

Migration from openssl to libressl - Direction for users

Since this is still work in progress, converting a full blown system from openssl to libressl can be quite involved. Eventually the process should be as easy as just adding USE=libressl to your make.conf file and then doing an emerge -uvNDq world. Right now, however, libressl is marked ~arch in the tree as are many packages that depend on it. Our recommendation for now is that you start with a fresh stage3 and migrate it first before building up your system. We'll guide you through that migration below. These steps should work on any stage3, for any arch or flavor. They will also give you some idea of how to proceed with a full blown system if you should want to brave it!

Download your stage3 of choice, unpack it, chroot, etc., until you have a working environment. To start with, let's make sure everything is up to date so we can isolate and identify any new emerges that are triggered due to changes we make in /etc/portage as we migrate to libressl. We'll then emerge gentoolkit for equery so we get a list of packages that depend on openssl and/or libressl:

root #

emerge -uvNDq world

root #

emerge gentoolkit

root #

equery d openssl

root #

equery d libressl

At this point you should have a list that looks something like this:

CODE

* These packages depend on openssl:
dev-lang/python-2.7.10-r1 (ssl ? dev-libs/openssl)
dev-lang/python-3.4.3-r1 (ssl ? dev-libs/openssl)
net-misc/iputils-20121221-r1 (!gnutls ? dev-libs/openssl:0)
                             (!gnutls ? dev-libs/openssl:0[static-libs(+)])
net-misc/openssh-7.1_p2 (!libressl ? >=dev-libs/openssl-0.9.8f:0[bindist=])
                        (!libressl ? dev-libs/openssl:0)
                        (!libressl ? dev-libs/openssl:0[static-libs(+)])
net-misc/wget-1.16.3-r1 (!gnutls ? dev-libs/openssl:0)
                        (!gnutls ? dev-libs/openssl:0[static-libs(+)])

and

CODE

* These packages depend on libressl:
net-misc/openssh-7.1_p2 (libressl ? dev-libs/libressl)
                        (libressl ? dev-libs/libressl[static-libs(+)])

Note, =net-misc/openssh-7.1_p2 is already poised to switch between openssl and libressl, so we'll need to unmask USE=libressl for stable ebuilds (use.stable.mask). The others only depend on openssl, but there are ~arch versions of python, wget and iputils that do depend on libressl and we'll need to keyword those in our packages.accept_keywords file as well as a couple other ebuilds that these pull in. Keep in mind that this is the situation as I write this, but it may have changed by the time you do your migration, so you'll have to recheck my work!

We begin by adding USE=libressl system wide and unmasking it for stable ebuilds. We'll also mask dev-libs/openssl and keyword dev-libs/libressl-2.2.x. (We'll skip libressl-2.3.x for now since it drops SSLv3 support which man packages still use. If you want to do testing with 2.3.x then keyword it instead below.)

root #

echo 'USE="${USE} libressl"' >> /etc/portage/make.conf

root #

mkdir -p /etc/portage/profile

root #

echo "-libressl" >> /etc/portage/profile/use.stable.mask

root #

echo "dev-libs/openssl" >> /etc/portage/package.mask

root #

echo "=dev-libs/libressl-2.2*" >> /etc/portage/package.accept_keywords

At this point we remove openssl and replace it by libressl. The system may break during this transition, so we'll need to fix it as soon as possible. In particular, ssh and wget depend on openssl, so those could fail meaning you'll loose remote connection or the ability to download packages! In testing, just dropping in libressl in openssl's place works, but we still want to rebuild everything linking against openssl to address and ABI mismatches. Let's first fetch the libressl tarball in case wget breaks!

root #

emerge -f libressl

root #

emerge -C openssl

root #

emerge -1q libressl

We can now proceed to rebuild packages which need no further keywording/unmaskings:

root #emerge -1q openssh wget python:2.7 python:3.4 iputils

Finally, if emerge ends complaining existing preserved libs found, end the conversion by doing

root #emerge -q @preserved-rebuild

At this point, you're system is completely migrated over and everything that links against libressl has been compiled against it for a consistent system. As you proceed to build stable packages that only depend on openssl, you'll need to look if there are any ~arch packages that have libressl support and keyword those. Hopefully your package will have libressl support in some ~arch ebuild, but if not, you'll need to bug one of us to get it in there for you!