From 6d44728858fbb98c2aac85b732081b2d51e4da9b Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 7 Oct 2015 14:50:50 +0100 Subject: Document building static wheels on Linux. --- docs/installation.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) (limited to 'docs') diff --git a/docs/installation.rst b/docs/installation.rst index 1456b724..cdee29c5 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -58,6 +58,8 @@ to include the proper locations. For example: C:\> pip install cryptography +.. _build-on-linux: + Building cryptography on Linux ------------------------------ @@ -115,6 +117,58 @@ You'll also need to generate your own ``openssl.ld`` file. For example:: You should replace the version string on the first line as appropriate for your build. +Static Wheels +~~~~~~~~~~~~~ + +Cryptography ships statically-linked wheels for OS X and Windows, ensuring that +these platforms can always use the most-recent OpenSSL, regardless of what is +shipped by default on those platforms. As a result of various difficulties +around Linux binary linking, Cryptography cannot do the same on Linux. + +However, you can build your own statically-linked wheels that will work on your +own systems. This will allow you to continue to use relatively old Linux +distributions (such as LTS releases), while making sure you have the most +recent OpenSSL available to your Python programs. + +To do so, you should find yourself a machine that is as similar as possible to +your target environment (e.g. your production environment): for example, spin +up a new cloud server running your target Linux distribution. On this machine, +install the Cryptography dependencies as mentioned in :ref:`build-on-linux`. +Please also make sure you have `virtualenv`_ installed: this should be +available from your system package manager. + +Then, run the following shell script. Feel free to adjust the OpenSSL version +if you'd like to use something more recent or you have specific version +requirements. + +When this shell script is complete, you'll find a collection of wheel files in +a directory called ``wheelhouse``. These wheels can be installed by a +sufficiently-recent version of ``pip``. The Cryptography wheel in this +directory contains a statically-linked OpenSSL binding, which ensures that you +have access to the most-recent OpenSSL releases without corrupting your system +dependencies. + +.. code-block:: console + + set -e + + OPENSSL_VERSION="1.0.2d" + CWD=$(pwd) + + virtualenv env + . env/bin/activate + pip install -U setuptools + pip install -U wheel pip + curl -O https://openssl.org/source/openssl-${OPENSSL_VERSION}.tar.gz + tar xvf openssl-${OPENSSL_VERSION}.tar.gz + cd openssl-${OPENSSL_VERSION} + ./config no-shared no-ssl2 -fPIC --prefix=${CWD}/openssl + make && make install + cd .. + CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel cryptography + +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ + Building cryptography on OS X ----------------------------- -- cgit v1.2.3 From ba8f638886bf2266ec859e8805f1e83496dd5fbd Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 7 Oct 2015 15:07:47 +0100 Subject: Move link to bottom of docs page. --- docs/installation.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/installation.rst b/docs/installation.rst index cdee29c5..967e86c1 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -167,8 +167,6 @@ dependencies. cd .. CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel cryptography -.. _virtualenv: https://virtualenv.pypa.io/en/latest/ - Building cryptography on OS X ----------------------------- @@ -255,3 +253,4 @@ information, consult `Greg Wilson's blog post`_ on the subject. .. _`64-bit`: https://jenkins.cryptography.io/job/openssl-win64-release/ .. _`bug in conda`: https://github.com/conda/conda-recipes/issues/110 .. _`Greg Wilson's blog post`: http://software-carpentry.org/blog/2014/04/mr-biczo-was-right.html +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ -- cgit v1.2.3 From 8078184e38fa790ffc31bf1a43e5d023e00d7861 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 7 Oct 2015 15:07:57 +0100 Subject: Don't accidentally use out-of-date OpenSSLs. --- docs/installation.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/installation.rst b/docs/installation.rst index 967e86c1..9793ac21 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -137,9 +137,10 @@ install the Cryptography dependencies as mentioned in :ref:`build-on-linux`. Please also make sure you have `virtualenv`_ installed: this should be available from your system package manager. -Then, run the following shell script. Feel free to adjust the OpenSSL version -if you'd like to use something more recent or you have specific version -requirements. +Then, paste the following into a shell script. You'll need to populate the +``OPENSSL_VERSION`` variable. To do that, visit `openssl.org`_ and find the +latest non-FIPS release version number, then set the string appropriately. For +example, for OpenSSL 1.0.2d, use ``OPENSSL_VERSION="1.0.2d"``. When this shell script is complete, you'll find a collection of wheel files in a directory called ``wheelhouse``. These wheels can be installed by a @@ -152,7 +153,7 @@ dependencies. set -e - OPENSSL_VERSION="1.0.2d" + OPENSSL_VERSION="VERSIONGOESHERE" CWD=$(pwd) virtualenv env -- cgit v1.2.3 From 3ed8b81b42a8e2f32e408068afe74742abfa3041 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 7 Oct 2015 15:18:12 +0100 Subject: Missing OpenSSL.org link. --- docs/installation.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/installation.rst b/docs/installation.rst index 9793ac21..5d629e9f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -255,3 +255,4 @@ information, consult `Greg Wilson's blog post`_ on the subject. .. _`bug in conda`: https://github.com/conda/conda-recipes/issues/110 .. _`Greg Wilson's blog post`: http://software-carpentry.org/blog/2014/04/mr-biczo-was-right.html .. _virtualenv: https://virtualenv.pypa.io/en/latest/ +.. _openssl.org: https://openssl.org/source/ -- cgit v1.2.3 From 301d56b4bd22f613093b2f2d14741882a6b5a354 Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Wed, 7 Oct 2015 15:29:47 +0100 Subject: FIPS is a real word! --- docs/spelling_wordlist.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index da05a843..adb9186c 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -28,6 +28,7 @@ Django Encodings fernet Fernet +FIPS hazmat indistinguishability initialisms -- cgit v1.2.3