diff options
Diffstat (limited to 'docs/installation.rst')
| -rw-r--r-- | docs/installation.rst | 249 |
1 files changed, 176 insertions, 73 deletions
diff --git a/docs/installation.rst b/docs/installation.rst index 1c25ff78..a9b0f3af 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -10,90 +10,117 @@ You can install ``cryptography`` with ``pip``: Supported platforms ------------------- -Currently we test ``cryptography`` on Python 2.6, 2.7, 3.3, 3.4 and PyPy -on these operating systems. - -* x86-64 CentOS 7.x, 6.4 and CentOS 5.x -* x86-64 FreeBSD 10 -* OS X 10.10 Yosemite, 10.9 Mavericks, 10.8 Mountain Lion, and 10.7 Lion -* x86-64 Ubuntu 12.04 LTS -* x86-64 Debian Wheezy (7.x) and Jessie (8.x) -* 32-bit Python on 64-bit Windows Server 2008 -* 64-bit Python on 64-bit Windows Server 2012 +Currently we test ``cryptography`` on Python 2.7, 3.5+, +PyPy 7.1+, and PyPy3 7.0 on these operating systems. + +* x86-64 CentOS 7.x +* x86-64 Fedora (latest) +* macOS 10.15 Catalina +* x86-64 Ubuntu 16.04 and rolling +* x86-64 Debian Stretch (9.x), Buster (10.x), Bullseye (11.x), and Sid + (unstable) +* x86-64 Alpine (latest) +* 32-bit and 64-bit Python on 64-bit Windows Server 2019 We test compiling with ``clang`` as well as ``gcc`` and use the following OpenSSL releases: -* ``OpenSSL 0.9.8e-fips-rhel5`` (``RHEL/CentOS 5``) -* ``OpenSSL 0.9.8k`` -* ``OpenSSL 0.9.8za`` -* ``OpenSSL 1.0.0-fips`` (``RHEL/CentOS 6.4``) -* ``OpenSSL 1.0.1`` -* ``OpenSSL 1.0.1e-fips`` (``RHEL/CentOS 7``) -* ``OpenSSL 1.0.1j-freebsd`` -* ``OpenSSL 1.0.1-latest`` (The most recent 1.0.1 release) -* ``OpenSSL 1.0.2`` +* ``OpenSSL 1.0.2-latest`` +* ``OpenSSL 1.1.0-latest`` +* ``OpenSSL 1.1.1-latest`` -On Windows ----------- +Building cryptography on Windows +-------------------------------- The wheel package on Windows is a statically linked build (as of 0.5) so all -dependencies are included. Just run +dependencies are included. To install ``cryptography``, you will typically +just run .. code-block:: console $ pip install cryptography If you prefer to compile it yourself you'll need to have OpenSSL installed. -There are `pre-compiled binaries`_ available. If your installation is in an -unusual location set the ``LIB`` and ``INCLUDE`` environment variables to -include the corresponding locations.For example: +You can compile OpenSSL yourself as well or use `a binary distribution`_. +Be sure to download the proper version for your architecture and Python +(VC2010 works for Python 2.7 while VC2015 is required for 3.5 and above). +Wherever you place your copy of OpenSSL you'll need to set the ``LIB`` and ``INCLUDE`` +environment variables to include the proper locations. For example: .. code-block:: console C:\> \path\to\vcvarsall.bat x86_amd64 - C:\> set LIB=C:\OpenSSL\lib\VC\static;C:\OpenSSL\lib;%LIB% - C:\> set INCLUDE=C:\OpenSSL\include;%INCLUDE% + C:\> set LIB=C:\OpenSSL-win64\lib;%LIB% + C:\> set INCLUDE=C:\OpenSSL-win64\include;%INCLUDE% C:\> pip install cryptography -You can also choose to build statically or dynamically using the -``PYCA_WINDOWS_LINK_TYPE`` variable. Allowed values are ``static`` (default) -and ``dynamic``. +As of OpenSSL 1.1.0 the library names have changed from ``libeay32`` and +``ssleay32`` to ``libcrypto`` and ``libssl`` (matching their names on all other +platforms). ``cryptography`` links against the new 1.1.0 names by default. If +you need to compile ``cryptography`` against an older version then you **must** +set ``CRYPTOGRAPHY_WINDOWS_LINK_LEGACY_OPENSSL`` or else installation will fail. -.. code-block:: console +If you need to rebuild ``cryptography`` for any reason be sure to clear the +local `wheel cache`_. - C:\> \path\to\vcvarsall.bat x86_amd64 - C:\> set LIB=C:\OpenSSL\lib\VC\static;C:\OpenSSL\lib;%LIB% - C:\> set INCLUDE=C:\OpenSSL\include;%INCLUDE% - C:\> set PYCA_WINDOWS_LINK_TYPE=dynamic - C:\> pip install cryptography +.. _build-on-linux: Building cryptography on Linux ------------------------------ -``cryptography`` should build very easily on Linux provided you have a C -compiler, headers for Python (if you're not using ``pypy``), and headers for -the OpenSSL and ``libffi`` libraries available on your system. +``cryptography`` ships ``manylinux`` wheels (as of 2.0) so all dependencies +are included. For users on pip 8.1 or above running on a ``manylinux1`` or +``manylinux2010`` compatible distribution (almost everything except Alpine) +all you should need to do is: + +.. code-block:: console + + $ pip install cryptography + +If you are on Alpine or just want to compile it yourself then +``cryptography`` requires a compiler, headers for Python (if you're not +using ``pypy``), and headers for the OpenSSL and ``libffi`` libraries +available on your system. + +Alpine +~~~~~~ -For Debian and Ubuntu, the following command will ensure that the required -dependencies are installed: +Replace ``python3-dev`` with ``python-dev`` if you're using Python 2. .. code-block:: console - $ sudo apt-get install build-essential libssl-dev libffi-dev python-dev + $ sudo apk add gcc musl-dev python3-dev libffi-dev openssl-dev -For Fedora and RHEL-derivatives, the following command will ensure that the -required dependencies are installed: +If you get an error with ``openssl-dev`` you may have to use ``libressl-dev``. + +Debian/Ubuntu +~~~~~~~~~~~~~ + +Replace ``python3-dev`` with ``python-dev`` if you're using Python 2. .. code-block:: console - $ sudo yum install gcc libffi-devel python-devel openssl-devel + $ sudo apt-get install build-essential libssl-dev libffi-dev python3-dev -You should now be able to build and install cryptography with the usual +RHEL/CentOS +~~~~~~~~~~~ .. code-block:: console - $ pip install cryptography + $ sudo yum install redhat-rpm-config gcc libffi-devel python-devel \ + openssl-devel + + +Building +~~~~~~~~ + +You should now be able to build and install cryptography. To avoid getting +the pre-built wheel on ``manylinux`` compatible distributions you'll need to +use ``--no-binary``. + +.. code-block:: console + + $ pip install cryptography --no-binary cryptography Using your own OpenSSL on Linux @@ -117,7 +144,7 @@ this when configuring OpenSSL: You'll also need to generate your own ``openssl.ld`` file. For example:: - OPENSSL_1.0.1F_CUSTOM { + OPENSSL_1.1.0E_CUSTOM { global: *; }; @@ -125,52 +152,128 @@ 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. -Using your own OpenSSL on OS X +Static Wheels +~~~~~~~~~~~~~ + +Cryptography ships statically-linked wheels for macOS, Windows, and Linux (via +``manylinux``). This allows compatible environments to use the most recent +OpenSSL, regardless of what is shipped by default on those platforms. Some +Linux distributions (most notably Alpine) are not ``manylinux`` compatible so +we cannot distribute wheels for them. + +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, 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.2k, use ``OPENSSL_VERSION="1.0.2k"``. + +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="VERSIONGOESHERE" + CWD=$(pwd) + + virtualenv env + . env/bin/activate + pip install -U setuptools + pip install -U wheel pip + curl -O https://www.openssl.org/source/openssl-${OPENSSL_VERSION}.tar.gz + tar xvf openssl-${OPENSSL_VERSION}.tar.gz + cd openssl-${OPENSSL_VERSION} + ./config no-shared no-ssl2 no-ssl3 -fPIC --prefix=${CWD}/openssl + make && make install + cd .. + CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel --no-binary :all: cryptography + +Building cryptography on macOS ------------------------------ -To link cryptography against a custom version of OpenSSL you'll need to set -``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via -`Homebrew`_ or `MacPorts`_: +.. note:: + + If installation gives a ``fatal error: 'openssl/aes.h' file not found`` + see the :doc:`FAQ </faq>` for information about how to fix this issue. + +The wheel package on macOS is a statically linked build (as of 1.0.1) so for +users with pip 8 or above you only need one step: + +.. code-block:: console + + $ pip install cryptography + +If you want to build cryptography yourself or are on an older macOS version, +cryptography requires the presence of a C compiler, development headers, and +the proper libraries. On macOS much of this is provided by Apple's Xcode +development tools. To install the Xcode command line tools (on macOS 10.9+) +open a terminal window and run: + +.. code-block:: console + + $ xcode-select --install + +This will install a compiler (clang) along with (most of) the required +development headers. + +You'll also need OpenSSL, which you can obtain from `Homebrew`_ or `MacPorts`_. +Cryptography does **not** support Apple's deprecated OpenSSL distribution. + +To build cryptography and dynamically link it: `Homebrew`_ .. code-block:: console - $ brew install openssl - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + $ brew install openssl@1.1 + $ env LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" CFLAGS="-I$(brew --prefix openssl@1.1)/include" pip install cryptography -or `MacPorts`_: +`MacPorts`_: .. code-block:: console $ sudo port install openssl - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography - -Building cryptography with conda --------------------------------- + $ env LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography -Because of a `bug in conda`_, attempting to install cryptography out of the box -will result in an error. This can be resolved by setting the library path -environment variable for your platform. +You can also build cryptography statically: -On OS X: +`Homebrew`_ .. code-block:: console - $ env DYLD_LIBRARY_PATH="$HOME/anaconda/lib" pip install cryptography + $ brew install openssl@1.1 + $ env CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1 LDFLAGS="$(brew --prefix openssl@1.1)/lib/libssl.a $(brew --prefix openssl@1.1)/lib/libcrypto.a" CFLAGS="-I$(brew --prefix openssl@1.1)/include" pip install cryptography -and on Linux: +`MacPorts`_: .. code-block:: console - $ env LD_LIBRARY_PATH="$HOME/anaconda/lib" pip install cryptography + $ sudo port install openssl + $ env CRYPTOGRAPHY_SUPPRESS_LINK_FLAGS=1 LDFLAGS="/opt/local/lib/libssl.a /opt/local/lib/libcrypto.a" CFLAGS="-I/opt/local/include" pip install cryptography -You will need to set this variable every time you start Python. For more -information, consult `Greg Wilson's blog post`_ on the subject. +If you need to rebuild ``cryptography`` for any reason be sure to clear the +local `wheel cache`_. -.. _`Homebrew`: http://brew.sh -.. _`MacPorts`: http://www.macports.org -.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html -.. _`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 +.. _`Homebrew`: https://brew.sh +.. _`MacPorts`: https://www.macports.org +.. _`a binary distribution`: https://wiki.openssl.org/index.php/Binaries +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ +.. _openssl.org: https://www.openssl.org/source/ +.. _`wheel cache`: https://pip.pypa.io/en/stable/reference/pip_install/#caching |