Linux: LibreSSL


LibreSSL is the best thing that ever happened to the OpenSSL project since its inception. The purpose of LibreSSL is to make sure that the worst thing that happened so far to OpenSSL will not happen again. The security history of LibreSSL since the first public release of its portable version on July 11th, 2014 shows that its users are considerably more secure than the ones of OpenSSL (almost twofold, as the raw bug counting goes).

In addition, LibreSSL is distributed with a new library, libtls which greatly simplifies development of programs using the TLS protocol, both client and servers, featuring both blocking and non-blocking I/O. In addition to simplicity, libtls (gently) holds the programmer and the user by the hand while preventing them from using insecure versions of TLS, insecure ciphersuites, or insecure options of LibreSSL as long as the library is upgraded regularly. It is a no-nonsense, compact, clear, and consistent API that I certainly recommend for new projects that require TLS.

Unfortunately, none of the major Linux distributions provides LibreSSL packages. Unless the user's platform is among a handful of systems, the installation must be performed from the source code.

Answers to Expected Questions

Before I explain how to install LibreSSL on Linux, there are several expected questions that I would like to provide answers for:

When installed, can LibreSSL co-exist with OpenSSL side-by-side on the same machine?
Yes! A very pleasant fact indeed: while LibreSSL and OpenSSL use the same names of libraries (libcrypto and libssl), they use different schemes for versioning of shared objects. Compare this:
ldd /usr/bin/openssl
        linux-vdso.so.1 (0x00007fff29b07000)
        libssl.so.1.0.0 => /usr/lib/x86_64-linux-gnu/libssl.so.1.0.0 (0x00007f46fca2f000)
        libcrypto.so.1.0.0 => /usr/lib/x86_64-linux-gnu/libcrypto.so.1.0.0 (0x00007f46fc634000)
        libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f46fc430000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f46fc087000)
        /lib64/ld-linux-x86-64.so.2 (0x00007f46fcc8f000)
and that:
ldd ~/opt/libressl/bin/openssl
	linux-vdso.so.1 (0x00007fff87f67000)
	libresolv.so.2 => /lib/x86_64-linux-gnu/libresolv.so.2 (0x00007fc71f3ce000)
	libssl.so.37 => /home/vadimp/opt/libressl/lib/libssl.so.37 (0x00007fc71f173000)
	libcrypto.so.36 => /home/vadimp/opt/libressl/lib/libcrypto.so.36 (0x00007fc71ed92000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fc71e9e9000)
        /lib64/ld-linux-x86-64.so.2 (0x00007fc71f5e5000)
Very roughly, it works as follows: when a programmer builds a shared library, the link editor ld(1) places the name of the shared object (programmers call it a SONAME which is found in the dynamic section of an ELF file of a shared library) into the output file. When an application program is linked with a dynamic library, ld(1) extracts the name of the shared object from the library and copies it into the output file—the binary executable of the program. When the program is executed, the dynamic loader ld.so(8) extracts the name of the shared object from the executable file of the program and searches for a library that has this name as its shared object name. As it can be seen from the output above, LibreSSL and OpenSSL use different SONAMEs, which makes system-wide installation of LibreSSL alongside OpenSSL possible: programs linked with OpenSSL depend on SONAMEs of the form libcrypto.<major version>.<minor version>.<age> and libssl.<major version>.<minor version>.<age> while programs linked with LibreSSL depend on SONAMEs of the form libcrypto.so.<version>, libssl.so.<version> and libtls.so.<version>.

I am a user of a Linux distribution, can I remove OpenSSL and install LibreSSL?
Do not do that. There are tens, as a gross underestimation, of packages that depend on OpenSSL; by default, removal of OpenSSL will cause your package manager to un-install the dependent packages as well. Probably the most important of these packages is OpenSSH, which provides remote access to your system—you will not be able to access it from afar anymore.

I am a programmer, can I have LibreSSL installed in my home directory for developmemt?
Yes, see the instructions below.

As a user, can I trick an existing program into using LibreSSL instead of OpenSSL?
It depends on the way this program loads shared objects. If the loading is implicit, i.e. this program was originally linked against OpenSSL and the loading is effectively performed by ld.so(8) then the answer is no, unless you specifically build LibreSSL to mimic OpenSSL. While that is possible with some manual work, it is not supported by existing releases of LibreSSL and it is not recommended in general—it is easy to break existing programs unless you are very accurate. If the loading is explicit, i.e. it is performed by the program itself using dlopen(3), substitution of LibreSSL in place of OpenSSL can be achieved as long as you either control that part of the file system where this program expects to find executables of OpenSSL or the program provides appropriate configuration options.

I am an integrator, I build all of my Linux system from the source, can I try LibreSSL as a replacement for OpenSSL?
Apparently it worked for OpenELEC and it worked for The Void, it should work for you too.

I am an integrator, can I build a system where OpenSSL or LibreSSL can be used interchangeably?
Both OpenSSL and LibreSSL build their shared objects while explicitly setting SONAMEs. OpenSSL uses for that a custom Makefile, Makefile.shared, while LibreSSL uses the GNU Libtool. You should modify both methods to either build shared objects without SONAMEs or to build shared objects having SONAMEs without version information (i.e. libssl.so).

Installing LibreSSL

  1. Decide in which directory you want to install LibreSSL. If you have or plan to have OpenSSL installed on the same machine, do not install LibreSSL in the same directory with OpenSSL. The reason for this is simple: since LibreSSL is source-compatible with OpenSSL, it uses the same names for its include files. In addition, the GNU Libtool creates symbolic links libcrypto.so and libssl.so pointing to libraries that are being installed. These two operations will overwrite OpenSSL's files having the same names. Usually, choosing /opt/libressl as the location for a system-wide installation is safe. The instructions below assume that you are installing LibreSSL to "${HOME}/opt/libressl", that is to the sub-directory opt/libressl of your home directory.

  2. Fetch the portability layer of the LibreSSL's source tree into the directory libressl:
    git clone https://github.com/libressl-portable/portable.git libressl
  3. Prepare the source for local use (among other things, this will fetch remaining parts of the LibreSSL's source):
    cd libressl && sh autogen.sh
  4. Configure the LibreSSL source tree:
    ./configure --prefix="${HOME}/opt/libressl"
  5. Compile LibreSSL:
    make
  6. Install LibreSSL:

    1. If you are performing a system-wide installation of LibreSSL:
      sudo make install
    2. If you are installing LibreSSL somewhere under your home directory:
      make install
  7. Optionally, if you are performing a system-wide installation of LibreSSL, inform ld.so(8) about the location of LibreSSL's libraries. The following assumes that LibreSSL is installed under /opt/libressl:
    echo '/opt/libressl' | sudo tee /etc/ld.so.conf.d/libressl.conf
    sudo ldconfig

Linking C Programs With LibreSSL

Inform the compiler about the location of LibreSSL's include files and libraries using environment variables. The following assumes that LibreSSL is installed under /opt/libressl:

C_INCLUDE_PATH="/opt/libressl/include" LIBRARY_PATH="/opt/libressl/lib" cc -o foo foo.c -ltls

Running C Programs Linked With LibreSSL

If you have a system-wide installation of LibreSSL, running programs linked with it is not different from running any other program. If you installed LibreSSL in a location that ld.so(8) is not aware of (for instance, somewhere under your home directory), you must inform ld.so(8) about the location of LibreSSL's libraries. The following assumes that LibreSSL is installed under /opt/libressl:

LD_LIBRARY_PATH="/opt/libressl/lib" ./foo

Vadim Penzin, October 10th, 2015


I hereby place this article into the public domain.
You are welcome to contact me by writing to howto at this domain.
I publish this information in the hope that it will be useful, but without ANY WARRANTY.
You are responsible for any and all consequences that may arise as the result of using this information.