diff --git a/guides/libressl.md b/guides/libressl.md new file mode 100644 index 0000000..22101e5 --- /dev/null +++ b/guides/libressl.md @@ -0,0 +1,113 @@ +## Introduction + +If you care about the upmost security, you should probably be using the +LibreSSL TLS crypto stack. + +This is an SSL library forked from OpenSSL by the OpenBSD team around 2014 +with improving the codebase, improving security, and applying the best +development practices. + +This guide focuses on Gentoo GNU/Linux, as it needs a few more steps to get +working than other distros. + +# Getting started + +You will need Gentoo installed on your computer obvoiously, and some +patience, espesially if you have a bunch of applications installed. + +Keep in mind if you have a bunch of packages, be prepared to recompile, and +debug any of them along the way if they fail to work or compile. + +# Adding the overlay + +First thing you will NEED TO DO is add the LibreSSL ebuild overlay to your +system. + +This supplies the LibreSSL ebuild itself and patches for other applications +to get working under LibreSSL. Please do the following in a terminal: + +~~~ emerge eselect-repository eselect repository enable libressl emaint +sync -r libressl ~~~ + +After doing this, you should have the overlay synced and installed, you can +check this by running + +~~~ ls /var/db/repos/libressl ~~~ + +If files appear, you have it installed. + +# make.conf settings + +You will have to set some flags in your make.conf for specific apps to use +LibreSSL instaid of OpenSSL. + +In your make.conf please find the USE="" paramater and put in the +following: + +~~~ USE="-openssl -system-ssl" ~~~ + +For apps with these USE flags, they will ignore specific OpenSSL support. +**system-ssl** is known to cause problems for nodejs users, so I reccomend +disabiling it here. + +Another thing that the migration does is installs and OpenSSL dummy +package. Due to gentoo removing LibreSSL from their overlay. + +This package is needed for packages to build correctly, dont worry, they +still bind to LibreSSL. + +To be sure this dummy package is the only one allowed to be merged, please +open this file in a text editor + +**/etc/portage/package/package.mask**. + +If this is a directory, not a file, then do + +**/etc/portage/package/package.mask/openssl**. + +And insert the following + +~~~ +# OpenSSL mask +dev-libs/openssl::gentoo + +# OpenSSL package mask +app-crypt/qca::gentoo dev-lang/python::gentoo ~~~ + +This will mask OpenSSL from being merged, and cause the other packages +listed to only build from the LibreSSL overlay. + +# Migration time + +Time for the big thing, we are going to migrate from OpenSSL to Libressl. +The first part is removing OpenSSL from your system, and fetcing needed +packages for the migration. please run: + +~~~ emerge -f wget curl python libressl emerge -Cq dev-libs/openssl ~~~ + +After doing this, please merge LibreSSL, this will take a minute so please +be patient. + +~~~ emerge -1q dev-libs/libressl::libressl ~~~ + +You're almost done! To test that you are actually using LibreSSL, you can +run somthing like + +**openssl version** + +and if it returns somthing like + +**LibreSSL x.x.x** + +you're using LibreSSL. + +# Finishing touches + +Time to update and rebind everything to use LibreSSL, you may have noticed +emerge will complain about libraries needing to be rebuilt, this will fix +that. Please run: + +~~~ emerge -vquDN @world emerge @preserved-rebuild ~~~ + +And if everything compiles fine, congratulations! You are now using a +LibreSSL based Gentoo system. I hope you enjoyed this guide. -itZzenXX