faq.rst 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899
  1. Frequently asked questions
  2. ==========================
  3. ``cryptography`` failed to install!
  4. -----------------------------------
  5. If you are having issues installing ``cryptography`` the first troubleshooting
  6. step is to upgrade ``pip`` and then try to install again. For most users this will
  7. take the form of ``pip install -U pip``, but on Windows you should do
  8. ``python -m pip install -U pip``. If you are still seeing errors after upgrading
  9. and trying ``pip install cryptography`` again, please see the :doc:`/installation`
  10. documentation.
  11. How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)?
  12. --------------------------------------------------------------------------------
  13. While ``cryptography`` and `NaCl`_ both share the goal of making cryptography
  14. easier, and safer, to use for developers, ``cryptography`` is designed to be a
  15. general purpose library, interoperable with existing systems, while NaCl
  16. features a collection of hand selected algorithms.
  17. ``cryptography``'s :ref:`recipes <cryptography-layout>` layer has similar goals
  18. to NaCl.
  19. If you prefer NaCl's design, we highly recommend `PyNaCl`_.
  20. Why use ``cryptography``?
  21. -------------------------
  22. If you've done cryptographic work in Python before you have likely encountered
  23. other libraries in Python such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In
  24. building ``cryptography`` we wanted to address a few issues we observed in the
  25. legacy libraries:
  26. * Extremely error prone APIs and insecure defaults.
  27. * Use of poor implementations of algorithms (i.e. ones with known side-channel
  28. attacks).
  29. * Lack of maintenance.
  30. * Lack of high level APIs.
  31. * Lack of PyPy and Python 3 support.
  32. * Absence of algorithms such as
  33. :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
  34. :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
  35. Compiling ``cryptography`` on macOS produces a ``fatal error: 'openssl/aes.h' file not found`` error
  36. ----------------------------------------------------------------------------------------------------
  37. This happens because macOS 10.11 no longer includes a copy of OpenSSL.
  38. ``cryptography`` now provides wheels which include a statically linked copy of
  39. OpenSSL. You're seeing this error because your copy of pip is too old to find
  40. our wheel files. Upgrade your copy of pip with ``pip install -U pip`` and then
  41. try install ``cryptography`` again.
  42. If you are using PyPy, we do not currently ship ``cryptography`` wheels for
  43. PyPy. You will need to install your own copy of OpenSSL -- we recommend using
  44. Homebrew.
  45. Starting ``cryptography`` using ``mod_wsgi`` produces an ``InternalError`` during a call in ``_register_osrandom_engine``
  46. -------------------------------------------------------------------------------------------------------------------------
  47. Upgrade to the latest ``cryptography`` and this issue should be resolved.
  48. ``cryptography`` raised an ``InternalError`` and I'm not sure what to do?
  49. -------------------------------------------------------------------------
  50. Frequently ``InternalError`` is raised when there are errors on the OpenSSL
  51. error stack that were placed there by other libraries that are also using
  52. OpenSSL. Try removing the other libraries and see if the problem persists.
  53. If you have no other libraries using OpenSSL in your process, or they do not
  54. appear to be at fault, it's possible that this is a bug in ``cryptography``.
  55. Please file an `issue`_ with instructions on how to reproduce it.
  56. Installing ``cryptography`` fails with ``ImportError: No module named setuptools_ext``
  57. --------------------------------------------------------------------------------------
  58. Your ``cffi`` package is out of date. ``pip install -U cffi`` to update it.
  59. error: ``-Werror=sign-conversion``: No option ``-Wsign-conversion`` during installation
  60. ---------------------------------------------------------------------------------------
  61. The compiler you are using is too old and not supported by ``cryptography``.
  62. Please upgrade to a more recent version. If you are running OpenBSD 6.1 or
  63. earlier the default compiler is extremely old. Use ``pkg_add`` to install a
  64. newer ``gcc`` and then install ``cryptography`` using
  65. ``CC=/path/to/newer/gcc pip install cryptography``.
  66. Installing cryptography with OpenSSL 0.9.8 or 1.0.0 fails
  67. ---------------------------------------------------------
  68. The OpenSSL project has dropped support for the 0.9.8 and 1.0.0 release series.
  69. Since they are no longer receiving security patches from upstream,
  70. ``cryptography`` is also dropping support for them. To fix this issue you
  71. should upgrade to a newer version of OpenSSL (1.0.1 or later). This may require
  72. you to upgrade to a newer operating system.
  73. .. _`NaCl`: https://nacl.cr.yp.to/
  74. .. _`PyNaCl`: https://pynacl.readthedocs.io
  75. .. _`WSGIApplicationGroup`: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIApplicationGroup.html
  76. .. _`issue`: https://github.com/pyca/cryptography/issues