faq.rst 7.5 KB

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