![LibreSSL image](https://www.libressl.org/images/libressl.jpg)
## Official portable version of [LibreSSL](https://www.libressl.org) ##

[![Build Status](https://travis-ci.org/libressl-portable/portable.svg?branch=master)](https://travis-ci.org/libressl-portable/portable) [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/libressl.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:libressl)

LibreSSL is a fork of [OpenSSL](https://www.openssl.org) 1.0.1g developed by the
[OpenBSD](https://www.openbsd.org) project.  Our goal is to modernize the codebase,
improve security, and apply best practice development processes from OpenBSD.

## Compatibility with OpenSSL: ##

LibreSSL is API compatible with OpenSSL 1.0.1, but does not yet include all
new APIs from OpenSSL 1.0.2 and later. LibreSSL also includes APIs not yet
present in OpenSSL. The current common API subset is OpenSSL 1.0.1.

LibreSSL is not ABI compatible with any release of OpenSSL, or necessarily
earlier releases of LibreSSL. You will need to relink your programs to
LibreSSL in order to use it, just as in moving between major versions of OpenSSL.
LibreSSL's installed library version numbers are incremented to account for
ABI and API changes.

## Compatibility with other operating systems: ##

While primarily developed on and taking advantage of APIs available on OpenBSD,
the LibreSSL portable project attempts to provide working alternatives for
other operating systems, and assists with improving OS-native implementations
where possible.

At the time of this writing, LibreSSL is known to build and work on:

* Linux (kernel 3.17 or later recommended)
* FreeBSD (tested with 9.2 and later)
* NetBSD (7.0 or later recommended)
* HP-UX (11i)
* Solaris (11 and later preferred)
* Mac OS X (tested with 10.8 and later)
* AIX (5.3 and later)

LibreSSL also supports the following Windows environments:
* Microsoft Windows (Windows 7 / Windows Server 2008r2 or later, x86 and x64)
* Wine (32-bit and 64-bit)
* Mingw-w64, Cygwin, and Visual Studio

Official release tarballs are available at your friendly neighborhood
OpenBSD mirror in directory
[LibreSSL](https://ftp.openbsd.org/pub/OpenBSD/LibreSSL/),
although we suggest that you use a [mirror](https://www.openbsd.org/ftp.html).

The LibreSSL portable build framework is also
[mirrored](https://github.com/libressl-portable/portable) in Github.

Please report bugs either to the public libressl@openbsd.org mailing list,
or to the github
[issue tracker](https://github.com/libressl-portable/portable/issues)

Severe vulnerabilities or bugs requiring coordination with OpenSSL can be
sent to the core team at libressl-security@openbsd.org.

# Building LibreSSL #

## Prerequisites when building from a Git checkout ##

If you have checked this source using Git, or have downloaded a source tarball
from Github, follow these initial steps to prepare the source tree for
building. _Note: Your build will fail if you do not follow these instructions! If you cannot follow these instructions (e.g. Windows system using CMake) or cannot meet these prerequistes, please download an official release distribution from https://ftp.openbsd.org/pub/OpenBSD/LibreSSL/ instead. Using official releases is strongly advised if you are not a developer._

1. Ensure you have the following packages installed:
   automake, autoconf, git, libtool, perl
2. Run `./autogen.sh` to prepare the source tree for building or
   run `./dist.sh` to prepare a tarball.

## Steps that apply to all builds ##

Once you have a source tree, either by downloaded using git and having
run the `autogen.sh` script above, or by downloading a release distribution from
an OpenBSD mirror, run these commands to build and install the package on most
systems:

```sh
./configure   # see ./configure --help for configuration options
make check    # runs builtin unit tests
make install  # set DESTDIR= to install to an alternate location
```

If you wish to use the CMake build system, use these commands:

```sh
mkdir build
cd build
cmake ..
make
make test
```

For faster builds, you can use Ninja as well:

```sh
mkdir build-ninja
cd build-ninja
cmake -G"Ninja" ..
ninja
ninja test
```

### OS specific build information: ###

#### HP-UX (11i) ####

Set the UNIX_STD environment variable to `2003` before running `configure`
in order to build with the HP C/aC++ compiler. See the "standards(5)" man
page for more details.

```sh
export UNIX_STD=2003
./configure
make
```

#### Windows - Mingw-w64 ####

LibreSSL builds against relatively recent versions of Mingw-w64, not to be
confused with the original mingw.org project.  Mingw-w64 3.2 or later
should work. See README.windows for more information

#### Windows - Visual Studio ####

LibreSSL builds using the CMake target "Visual Studio 12 2013" and newer. To
generate a Visual Studio project, install CMake, enter the LibreSSL source
directory and run:

```sh
 mkdir build-vs2013
 cd build-vs2013
 cmake -G"Visual Studio 12 2013" ..
```

Replace "Visual Studio 12 2013" with whatever version of Visual Studio you
have installed. This will generate a LibreSSL.sln file that you can incorporate
into other projects or build by itself.

#### Cmake - Additional Options ####

| Option Name | Default | Description
| ------------ | -----: | ------
|  LIBRESSL_SKIP_INSTALL | OFF | allows skipping install() rules.  Can be specified from command line using <br>```-DLIBRESSL_SKIP_INSTALL=ON``` |
|  LIBRESSL_APPS | ON | allows skipping application builds. Apps are required to run tests |
|  LIBRESSL_TESTS | ON | allows skipping of tests. Tests are only available in static builds |
|  BUILD_SHARED_LIBS | OFF | CMake option for building shared libraries. |
|  ENABLE_ASM | ON | builds assembly optimized rules. |
|  ENABLE_EXTRATESTS | OFF | Enable extra tests that may be unreliable on some platforms |
|  ENABLE_NC | OFF | Enable installing TLS-enabled nc(1) |
|  OPENSSLDIR | Blank | Set the default openssl directory.  Can be specified from command line using <br>```-DOPENSSLDIR=<dirname>``` |

# Using LibreSSL #

## CMake ##

Make a new folder in your project root (where your main CMakeLists.txt file is located) called CMake. Copy the FindLibreSSL.cmake file to that folder, and add the following line to your main CMakeLists.txt:

```cmake
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/CMake;${CMAKE_MODULE_PATH}")
```

After your **add_executable** or **add_library** line in your CMakeLists.txt file add the following:

```cmake
find_package(LibreSSL REQUIRED)
```

It will tell CMake to find LibreSSL and if found will let you use the following 3 interfaces in your CMakeLists.txt file:

* LibreSSL::Crypto
* LibreSSL::SSL
* LibreSSL::TLS

If you for example want to use the LibreSSL TLS library in your test program, include it like so (SSL and Cryto are required by TLS and included automatically too):

```cmake
target_link_libraries(test LibreSSL::TLS)
```

Full example:

```cmake
cmake_minimum_required(VERSION 3.10.0)

set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/CMake;${CMAKE_MODULE_PATH}")

project(test)

add_executable(test Main.cpp)

find_package(LibreSSL REQUIRED)

target_link_libraries(test LibreSSL::TLS)
```

#### Linux ####

Following the guide in the sections above to compile LibreSSL using make and running "sudo make install" will install LibreSSL to the /usr/local/ folder, and will found automatically by find_package. If your system installs it to another location or you have placed them yourself in a different location, you can set the CMake variable LIBRESSL_ROOT_DIR to the correct path, to help CMake find the library.

#### Windows ####

Placing the library files in C:/Program Files/LibreSSL/lib and the include files in C:/Program Files/LibreSSL/include should let CMake find them automatically, but it is recommended that you use CMake-GUI to set the paths. It is more convenient as you can have the files in any folder you choose.

# Building

For Windows systems, LibreSSL supports the mingw-w64 toolchain, which can use
GCC or Clang as the compiler. Contrary to its name, mingw-w64 supports both
32-bit and 64-bit build environments. If your project already uses mingw-w64,
then LibreSSL should integrate very nicely. Old versions of the mingw-w64
toolchain, such as the one packaged with Ubuntu 12.04, may have trouble
building LibreSSL. Please try it with a recent toolchain if you encounter
troubles. Cygwin provides an easy method of installing the latest mingw-w64
cross compilers on Windows.

To configure and build LibreSSL for a 32-bit system, use the following
build steps:

 CC=i686-w64-mingw32-gcc CPPFLAGS=-D__MINGW_USE_VC2005_COMPAT \
 ./configure --host=i686-w64-mingw32
 make
 make check

For 64-bit builds, use these instead:

 CC=x86_64-w64-mingw32-gcc ./configure --host=x86_64-w64-mingw32
 make
 make check

# Why the -D__MINGW_USE_VC2005_COMPAT flag on 32-bit systems?

An ABI change introduced with Microsoft Visual C++ 2005 (also known as
Visual C++ 8.0) switched time_t from 32-bit to 64-bit. It is important to
build LibreSSL with 64-bit time_t whenever possible, because 32-bit time_t
is unable to represent times past 2038 (this is commonly known as the
Y2K38 problem).

If LibreSSL is built with 32-bit time_t, when verifying a certificate whose
expiry date is set past 19 January 2038, it will be unable to tell if the
certificate has expired or not, and thus take the safe stance and reject it.

In order to avoid this, you need to build LibreSSL (and everything that links
with it) with the -D__MINGW_USE_VC2005_COMPAT flag. This tells mingw-w64 to
use the new ABI.

64-bit systems always have a 64-bit time_t and are not affected by this
problem.

# Using Libressl with Visual Studio

A script for generating ready-to-use .DLL and static .LIB files is included in
the source repository at
https://github.com/libressl-portable/portable/blob/master/dist-win.sh

This script uses mingw-w64 to build LibreSSL and then uses Visual Studio tools
to generate compatible library import files ready-to-use with Visual
Studio projects. Static and dynamic libraries are included. The script uses
cv2pdb to generate Visual Studio and windbg compatible debug files. cv2pdb is a
tool developed for the D language and can be found here:
https://github.com/rainers/cv2pdb

Pre-built Windows binaries are available with LibreSSL releases if you do not
have a mingw-w64 build environment. Mingw-w64 code is largely, but not 100%,
compatible with code built from Visual Studio. Notably, FILE * pointers cannot
be shared between code built for Mingw-w64 and Visual Studio.

As of LibreSSL 2.2.2, Visual Studio Native builds can be produced using CMake.
This produces ABI-compatible libraries for linking with native code generated
by Visual Studio.