1Frequently asked questions 2========================== 3 4``cryptography`` failed to install! 5----------------------------------- 6 7If you are having issues installing ``cryptography`` the first troubleshooting 8step is to upgrade ``pip`` and then try to install again. For most users this will 9take the form of ``pip install -U pip``, but on Windows you should do 10``python -m pip install -U pip``. If you are still seeing errors after upgrading 11and trying ``pip install cryptography`` again, please see the :doc:`/installation` 12documentation. 13 14How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)? 15-------------------------------------------------------------------------------- 16 17While ``cryptography`` and `NaCl`_ both share the goal of making cryptography 18easier, and safer, to use for developers, ``cryptography`` is designed to be a 19general purpose library, interoperable with existing systems, while NaCl 20features a collection of hand selected algorithms. 21 22``cryptography``'s :ref:`recipes <cryptography-layout>` layer has similar goals 23to NaCl. 24 25If you prefer NaCl's design, we highly recommend `PyNaCl`_, which is also 26maintained by the PyCA team. 27 28Why use ``cryptography``? 29------------------------- 30 31If you've done cryptographic work in Python before you have likely encountered 32other libraries in Python such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In 33building ``cryptography`` we wanted to address a few issues we observed in the 34legacy libraries: 35 36* Extremely error prone APIs and insecure defaults. 37* Use of poor implementations of algorithms (i.e. ones with known side-channel 38 attacks). 39* Lack of maintenance. 40* Lack of high level APIs. 41* Lack of PyPy and Python 3 support. 42* Absence of algorithms such as 43 :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and 44 :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. 45 46Compiling ``cryptography`` on macOS produces a ``fatal error: 'openssl/aes.h' file not found`` error 47---------------------------------------------------------------------------------------------------- 48 49This happens because macOS 10.11 no longer includes a copy of OpenSSL. 50``cryptography`` now provides wheels which include a statically linked copy of 51OpenSSL. You're seeing this error because your copy of pip is too old to find 52our wheel files. Upgrade your copy of pip with ``pip install -U pip`` and then 53try install ``cryptography`` again. 54 55If you are using PyPy, we do not currently ship ``cryptography`` wheels for 56PyPy. You will need to install your own copy of OpenSSL -- we recommend using 57Homebrew. 58 59``cryptography`` raised an ``InternalError`` and I'm not sure what to do? 60------------------------------------------------------------------------- 61 62Frequently ``InternalError`` is raised when there are errors on the OpenSSL 63error stack that were placed there by other libraries that are also using 64OpenSSL. Try removing the other libraries and see if the problem persists. 65If you have no other libraries using OpenSSL in your process, or they do not 66appear to be at fault, it's possible that this is a bug in ``cryptography``. 67Please file an `issue`_ with instructions on how to reproduce it. 68 69error: ``-Werror=sign-conversion``: No option ``-Wsign-conversion`` during installation 70--------------------------------------------------------------------------------------- 71 72The compiler you are using is too old and not supported by ``cryptography``. 73Please upgrade to a more recent version. If you are running OpenBSD 6.1 or 74earlier the default compiler is extremely old. Use ``pkg_add`` to install a 75newer ``gcc`` and then install ``cryptography`` using 76``CC=/path/to/newer/gcc pip install cryptography``. 77 78Installing ``cryptography`` fails with ``Invalid environment marker: python_version < '3'`` 79------------------------------------------------------------------------------------------- 80 81Your ``pip`` and/or ``setuptools`` are outdated. Please upgrade to the latest 82versions with ``pip install -U pip setuptools`` (or on Windows 83``python -m pip install -U pip setuptools``). 84 85Installing cryptography with OpenSSL 0.9.8 or 1.0.0 fails 86--------------------------------------------------------- 87 88The OpenSSL project has dropped support for the 0.9.8 and 1.0.0 release series. 89Since they are no longer receiving security patches from upstream, 90``cryptography`` is also dropping support for them. To fix this issue you 91should upgrade to a newer version of OpenSSL (1.0.2 or later). This may require 92you to upgrade to a newer operating system. 93 94Why are there no wheels for Python 3.5+ on Linux or macOS? 95---------------------------------------------------------- 96 97Our Python3 wheels, for macOS and Linux, are ``abi3`` wheels. This means they 98support multiple versions of Python. The Python 3.4 ``abi3`` wheel can be used 99with any version of Python greater than or equal to 3.4. Recent versions of 100``pip`` will automatically install ``abi3`` wheels. 101 102``ImportError``: ``idna`` is not installed 103------------------------------------------ 104 105``cryptography`` deprecated passing :term:`U-label` strings to various X.509 106constructors in version 2.1 and in version 2.5 moved the ``idna`` dependency 107to a ``setuptools`` extra. If you see this exception you should upgrade your 108software so that it no longer depends on this deprecated feature. If that is 109not yet possible you can also install ``cryptography`` with 110``pip install cryptography[idna]`` to automatically install the missing 111dependency. This workaround will be available until the feature is fully 112removed. 113 114Why can't I import my PEM file? 115------------------------------- 116 117PEM is a format (defined by several RFCs, but originally :rfc:`1421`) for 118encoding keys, certificates and others cryptographic data into a regular form. 119The data is encoded as base64 and wrapped with a header and footer. 120 121If you are having trouble importing PEM files, make sure your file fits 122the following rules: 123 124* has a one-line header like this: ``-----BEGIN [FILE TYPE]-----`` 125 (where ``[FILE TYPE]`` is ``CERTIFICATE``, ``PUBLIC KEY``, ``PRIVATE KEY``, 126 etc.) 127 128* has a one-line footer like this: ``-----END [FILE TYPE]-----`` 129 130* all lines, except for the final one, must consist of exactly 64 131 characters. 132 133For example, this is a PEM file for a RSA Public Key: :: 134 135 -----BEGIN PUBLIC KEY----- 136 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7CsKFSzq20NLb2VQDXma 137 9DsDXtKADv0ziI5hT1KG6Bex5seE9pUoEcUxNv4uXo2jzAUgyRweRl/DLU8SoN8+ 138 WWd6YWik4GZvNv7j0z28h9Q5jRySxy4dmElFtIRHGiKhqd1Z06z4AzrmKEzgxkOk 139 LJjY9cvwD+iXjpK2oJwNNyavvjb5YZq6V60RhpyNtKpMh2+zRLgIk9sROEPQeYfK 140 22zj2CnGBMg5Gm2uPOsGDltl/I/Fdh1aO3X4i1GXwCuPf1kSAg6lPJD0batftkSG 141 v0X0heUaV0j1HSNlBWamT4IR9+iJfKJHekOqvHQBcaCu7Ja4kXzx6GZ3M2j/Ja3A 142 2QIDAQAB 143 -----END PUBLIC KEY----- 144 145 146.. _`NaCl`: https://nacl.cr.yp.to/ 147.. _`PyNaCl`: https://pynacl.readthedocs.io 148.. _`WSGIApplicationGroup`: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIApplicationGroup.html 149.. _`issue`: https://github.com/pyca/cryptography/issues 150