faq.rst 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163
  1. Frequently asked questions
  2. ==========================
  3. .. _faq-howto-handle-deprecation-warning:
  4. I cannot suppress the deprecation warning that ``cryptography`` emits on import
  5. -------------------------------------------------------------------------------
  6. .. hint::
  7. The deprecation warning emitted on import does not inherit
  8. :py:exc:`DeprecationWarning` but inherits :py:exc:`UserWarning`
  9. instead.
  10. If your pytest setup follows the best practices of failing on
  11. emitted warnings (``filterwarnings = error``), you may ignore it
  12. by adding the following line at the end of the list::
  13. ignore:Python 2 is no longer supported by the Python core team. Support for it is now deprecated in cryptography, and will be removed in a future release.:UserWarning
  14. **Note:** Using ``cryptography.utils.CryptographyDeprecationWarning``
  15. is not possible here because specifying it triggers
  16. ``import cryptography`` internally that emits the warning before
  17. the ignore rule even kicks in.
  18. Ref: https://github.com/pytest-dev/pytest/issues/7524
  19. The same applies when you use :py:func:`~warnings.filterwarnings` in
  20. your code or invoke CPython with :std:option:`-W` command line option.
  21. ``cryptography`` failed to install!
  22. -----------------------------------
  23. If you are having issues installing ``cryptography`` the first troubleshooting
  24. step is to upgrade ``pip`` and then try to install again. For most users this will
  25. take the form of ``pip install -U pip``, but on Windows you should do
  26. ``python -m pip install -U pip``. If you are still seeing errors after upgrading
  27. and trying ``pip install cryptography`` again, please see the :doc:`/installation`
  28. documentation.
  29. How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)?
  30. --------------------------------------------------------------------------------
  31. While ``cryptography`` and `NaCl`_ both share the goal of making cryptography
  32. easier, and safer, to use for developers, ``cryptography`` is designed to be a
  33. general purpose library, interoperable with existing systems, while NaCl
  34. features a collection of hand selected algorithms.
  35. ``cryptography``'s :ref:`recipes <cryptography-layout>` layer has similar goals
  36. to NaCl.
  37. If you prefer NaCl's design, we highly recommend `PyNaCl`_, which is also
  38. maintained by the PyCA team.
  39. Why use ``cryptography``?
  40. -------------------------
  41. If you've done cryptographic work in Python before you have likely encountered
  42. other libraries in Python such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In
  43. building ``cryptography`` we wanted to address a few issues we observed in the
  44. legacy libraries:
  45. * Extremely error prone APIs and insecure defaults.
  46. * Use of poor implementations of algorithms (i.e. ones with known side-channel
  47. attacks).
  48. * Lack of maintenance.
  49. * Lack of high level APIs.
  50. * Lack of PyPy and Python 3 support.
  51. * Absence of algorithms such as
  52. :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
  53. :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
  54. Installing ``cryptography`` produces a ``fatal error: 'openssl/opensslv.h' file not found`` error
  55. -------------------------------------------------------------------------------------------------
  56. ``cryptography`` provides wheels which include a statically linked copy of
  57. OpenSSL. If you see this error it is likely because your copy of ``pip`` is too
  58. old to find our wheel files. Upgrade your ``pip`` with ``pip install -U pip``
  59. and then try to install ``cryptography`` again.
  60. Users on PyPy, unusual CPU architectures, or distributions of Linux using
  61. ``musl`` (like Alpine) will need to compile ``cryptography`` themselves. Please
  62. view our :doc:`/installation` documentation.
  63. ``cryptography`` raised an ``InternalError`` and I'm not sure what to do?
  64. -------------------------------------------------------------------------
  65. Frequently ``InternalError`` is raised when there are errors on the OpenSSL
  66. error stack that were placed there by other libraries that are also using
  67. OpenSSL. Try removing the other libraries and see if the problem persists.
  68. If you have no other libraries using OpenSSL in your process, or they do not
  69. appear to be at fault, it's possible that this is a bug in ``cryptography``.
  70. Please file an `issue`_ with instructions on how to reproduce it.
  71. error: ``-Werror=sign-conversion``: No option ``-Wsign-conversion`` during installation
  72. ---------------------------------------------------------------------------------------
  73. The compiler you are using is too old and not supported by ``cryptography``.
  74. Please upgrade to a more recent version. If you are running OpenBSD 6.1 or
  75. earlier the default compiler is extremely old. Use ``pkg_add`` to install a
  76. newer ``gcc`` and then install ``cryptography`` using
  77. ``CC=/path/to/newer/gcc pip install cryptography``.
  78. Installing ``cryptography`` fails with ``Invalid environment marker: python_version < '3'``
  79. -------------------------------------------------------------------------------------------
  80. Your ``pip`` and/or ``setuptools`` are outdated. Please upgrade to the latest
  81. versions with ``pip install -U pip setuptools`` (or on Windows
  82. ``python -m pip install -U pip setuptools``).
  83. Installing cryptography with OpenSSL 0.9.8, 1.0.0, 1.0.1, 1.0.2 fails
  84. ---------------------------------------------------------------------
  85. The OpenSSL project has dropped support for the 0.9.8, 1.0.0, 1.0.1, and 1.0.2
  86. release series. Since they are no longer receiving security patches from
  87. upstream, ``cryptography`` is also dropping support for them. To fix this issue
  88. you should upgrade to a newer version of OpenSSL (1.1.0 or later). This may
  89. require you to upgrade to a newer operating system.
  90. Why are there no wheels for my Python3.x version?
  91. -------------------------------------------------
  92. Our Python3 wheels are ``abi3`` wheels. This means they support multiple
  93. versions of Python. The ``abi3`` wheel can be used with any version of Python
  94. greater than or equal to the version it specifies. Recent versions of ``pip``
  95. will automatically install ``abi3`` wheels.
  96. Why can't I import my PEM file?
  97. -------------------------------
  98. PEM is a format (defined by several RFCs, but originally :rfc:`1421`) for
  99. encoding keys, certificates and others cryptographic data into a regular form.
  100. The data is encoded as base64 and wrapped with a header and footer.
  101. If you are having trouble importing PEM files, make sure your file fits
  102. the following rules:
  103. * has a one-line header like this: ``-----BEGIN [FILE TYPE]-----``
  104. (where ``[FILE TYPE]`` is ``CERTIFICATE``, ``PUBLIC KEY``, ``PRIVATE KEY``,
  105. etc.)
  106. * has a one-line footer like this: ``-----END [FILE TYPE]-----``
  107. * all lines, except for the final one, must consist of exactly 64
  108. characters.
  109. For example, this is a PEM file for a RSA Public Key: ::
  110. -----BEGIN PUBLIC KEY-----
  111. MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7CsKFSzq20NLb2VQDXma
  112. 9DsDXtKADv0ziI5hT1KG6Bex5seE9pUoEcUxNv4uXo2jzAUgyRweRl/DLU8SoN8+
  113. WWd6YWik4GZvNv7j0z28h9Q5jRySxy4dmElFtIRHGiKhqd1Z06z4AzrmKEzgxkOk
  114. LJjY9cvwD+iXjpK2oJwNNyavvjb5YZq6V60RhpyNtKpMh2+zRLgIk9sROEPQeYfK
  115. 22zj2CnGBMg5Gm2uPOsGDltl/I/Fdh1aO3X4i1GXwCuPf1kSAg6lPJD0batftkSG
  116. v0X0heUaV0j1HSNlBWamT4IR9+iJfKJHekOqvHQBcaCu7Ja4kXzx6GZ3M2j/Ja3A
  117. 2QIDAQAB
  118. -----END PUBLIC KEY-----
  119. .. _`NaCl`: https://nacl.cr.yp.to/
  120. .. _`PyNaCl`: https://pynacl.readthedocs.io
  121. .. _`WSGIApplicationGroup`: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIApplicationGroup.html
  122. .. _`issue`: https://github.com/pyca/cryptography/issues