282 lines
9.4 KiB
ReStructuredText
282 lines
9.4 KiB
ReStructuredText
Installation
|
|
============
|
|
|
|
You can install ``cryptography`` with ``pip``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install cryptography
|
|
|
|
Supported platforms
|
|
-------------------
|
|
|
|
Currently we test ``cryptography`` on Python 2.7, 3.6+,
|
|
PyPy 7.3.1, and PyPy3 7.3.1 on these operating systems.
|
|
|
|
* x86-64 CentOS 7.x
|
|
* x86-64 & AArch64 CentOS 8.x
|
|
* x86-64 Fedora (latest)
|
|
* x86-64 macOS 10.15 Catalina
|
|
* x86-64 & AArch64 Ubuntu 18.04, 20.04
|
|
* x86-64 Ubuntu 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 1.1.0-latest``
|
|
* ``OpenSSL 1.1.1-latest``
|
|
|
|
|
|
Building cryptography on Windows
|
|
--------------------------------
|
|
|
|
The wheel package on Windows is a statically linked build (as of 0.5) so all
|
|
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.
|
|
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.6 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-win64\lib;%LIB%
|
|
C:\> set INCLUDE=C:\OpenSSL-win64\include;%INCLUDE%
|
|
C:\> pip install cryptography
|
|
|
|
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.
|
|
|
|
If you need to rebuild ``cryptography`` for any reason be sure to clear the
|
|
local `wheel cache`_.
|
|
|
|
.. _build-on-linux:
|
|
|
|
Building cryptography on Linux
|
|
------------------------------
|
|
|
|
``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
|
|
~~~~~~
|
|
|
|
Replace ``python3-dev`` with ``python-dev`` if you're using Python 2.
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo apk add gcc musl-dev python3-dev libffi-dev openssl-dev
|
|
|
|
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 apt-get install build-essential libssl-dev libffi-dev python3-dev
|
|
|
|
RHEL/CentOS
|
|
~~~~~~~~~~~
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Python links to OpenSSL for its own purposes and this can sometimes cause
|
|
problems when you wish to use a different version of OpenSSL with cryptography.
|
|
If you want to use cryptography with your own build of OpenSSL you will need to
|
|
make sure that the build is configured correctly so that your version of
|
|
OpenSSL doesn't conflict with Python's.
|
|
|
|
The options you need to add allow the linker to identify every symbol correctly
|
|
even when multiple versions of the library are linked into the same program. If
|
|
you are using your distribution's source packages these will probably be
|
|
patched in for you already, otherwise you'll need to use options something like
|
|
this when configuring OpenSSL:
|
|
|
|
.. code-block:: console
|
|
|
|
$ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
|
|
|
|
You'll also need to generate your own ``openssl.ld`` file. For example::
|
|
|
|
OPENSSL_1.1.0E_CUSTOM {
|
|
global:
|
|
*;
|
|
};
|
|
|
|
You should replace the version string on the first line as appropriate for your
|
|
build.
|
|
|
|
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
|
|
------------------------------
|
|
|
|
.. 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.10+)
|
|
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@1.1
|
|
$ env LDFLAGS="-L$(brew --prefix openssl@1.1)/lib" CFLAGS="-I$(brew --prefix openssl@1.1)/include" pip install cryptography
|
|
|
|
`MacPorts`_:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo port install openssl
|
|
$ env LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography
|
|
|
|
You can also build cryptography statically:
|
|
|
|
`Homebrew`_
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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
|
|
|
|
`MacPorts`_:
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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
|
|
|
|
If you need to rebuild ``cryptography`` for any reason be sure to clear the
|
|
local `wheel cache`_.
|
|
|
|
|
|
.. _`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
|