164 lines
7.3 KiB
ReStructuredText
164 lines
7.3 KiB
ReStructuredText
Frequently asked questions
|
|
==========================
|
|
|
|
.. _faq-howto-handle-deprecation-warning:
|
|
|
|
I cannot suppress the deprecation warning that ``cryptography`` emits on import
|
|
-------------------------------------------------------------------------------
|
|
|
|
.. hint::
|
|
|
|
The deprecation warning emitted on import does not inherit
|
|
:py:exc:`DeprecationWarning` but inherits :py:exc:`UserWarning`
|
|
instead.
|
|
|
|
If your pytest setup follows the best practices of failing on
|
|
emitted warnings (``filterwarnings = error``), you may ignore it
|
|
by adding the following line at the end of the list::
|
|
|
|
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
|
|
|
|
**Note:** Using ``cryptography.utils.CryptographyDeprecationWarning``
|
|
is not possible here because specifying it triggers
|
|
``import cryptography`` internally that emits the warning before
|
|
the ignore rule even kicks in.
|
|
|
|
Ref: https://github.com/pytest-dev/pytest/issues/7524
|
|
|
|
The same applies when you use :py:func:`~warnings.filterwarnings` in
|
|
your code or invoke CPython with :std:option:`-W` command line option.
|
|
|
|
``cryptography`` failed to install!
|
|
-----------------------------------
|
|
|
|
If you are having issues installing ``cryptography`` the first troubleshooting
|
|
step is to upgrade ``pip`` and then try to install again. For most users this will
|
|
take the form of ``pip install -U pip``, but on Windows you should do
|
|
``python -m pip install -U pip``. If you are still seeing errors after upgrading
|
|
and trying ``pip install cryptography`` again, please see the :doc:`/installation`
|
|
documentation.
|
|
|
|
How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)?
|
|
--------------------------------------------------------------------------------
|
|
|
|
While ``cryptography`` and `NaCl`_ both share the goal of making cryptography
|
|
easier, and safer, to use for developers, ``cryptography`` is designed to be a
|
|
general purpose library, interoperable with existing systems, while NaCl
|
|
features a collection of hand selected algorithms.
|
|
|
|
``cryptography``'s :ref:`recipes <cryptography-layout>` layer has similar goals
|
|
to NaCl.
|
|
|
|
If you prefer NaCl's design, we highly recommend `PyNaCl`_, which is also
|
|
maintained by the PyCA team.
|
|
|
|
Why use ``cryptography``?
|
|
-------------------------
|
|
|
|
If you've done cryptographic work in Python before you have likely encountered
|
|
other libraries in Python such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In
|
|
building ``cryptography`` we wanted to address a few issues we observed in the
|
|
legacy libraries:
|
|
|
|
* Extremely error prone APIs and insecure defaults.
|
|
* Use of poor implementations of algorithms (i.e. ones with known side-channel
|
|
attacks).
|
|
* Lack of maintenance.
|
|
* Lack of high level APIs.
|
|
* Lack of PyPy and Python 3 support.
|
|
* Absence of algorithms such as
|
|
:class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
|
|
:class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
|
|
|
|
Installing ``cryptography`` produces a ``fatal error: 'openssl/opensslv.h' file not found`` error
|
|
-------------------------------------------------------------------------------------------------
|
|
|
|
``cryptography`` provides wheels which include a statically linked copy of
|
|
OpenSSL. If you see this error it is likely because your copy of ``pip`` is too
|
|
old to find our wheel files. Upgrade your ``pip`` with ``pip install -U pip``
|
|
and then try to install ``cryptography`` again.
|
|
|
|
Users on PyPy, unusual CPU architectures, or distributions of Linux using
|
|
``musl`` (like Alpine) will need to compile ``cryptography`` themselves. Please
|
|
view our :doc:`/installation` documentation.
|
|
|
|
``cryptography`` raised an ``InternalError`` and I'm not sure what to do?
|
|
-------------------------------------------------------------------------
|
|
|
|
Frequently ``InternalError`` is raised when there are errors on the OpenSSL
|
|
error stack that were placed there by other libraries that are also using
|
|
OpenSSL. Try removing the other libraries and see if the problem persists.
|
|
If you have no other libraries using OpenSSL in your process, or they do not
|
|
appear to be at fault, it's possible that this is a bug in ``cryptography``.
|
|
Please file an `issue`_ with instructions on how to reproduce it.
|
|
|
|
error: ``-Werror=sign-conversion``: No option ``-Wsign-conversion`` during installation
|
|
---------------------------------------------------------------------------------------
|
|
|
|
The compiler you are using is too old and not supported by ``cryptography``.
|
|
Please upgrade to a more recent version. If you are running OpenBSD 6.1 or
|
|
earlier the default compiler is extremely old. Use ``pkg_add`` to install a
|
|
newer ``gcc`` and then install ``cryptography`` using
|
|
``CC=/path/to/newer/gcc pip install cryptography``.
|
|
|
|
Installing ``cryptography`` fails with ``Invalid environment marker: python_version < '3'``
|
|
-------------------------------------------------------------------------------------------
|
|
|
|
Your ``pip`` and/or ``setuptools`` are outdated. Please upgrade to the latest
|
|
versions with ``pip install -U pip setuptools`` (or on Windows
|
|
``python -m pip install -U pip setuptools``).
|
|
|
|
Installing cryptography with OpenSSL 0.9.8, 1.0.0, 1.0.1, 1.0.2 fails
|
|
---------------------------------------------------------------------
|
|
|
|
The OpenSSL project has dropped support for the 0.9.8, 1.0.0, 1.0.1, and 1.0.2
|
|
release series. Since they are no longer receiving security patches from
|
|
upstream, ``cryptography`` is also dropping support for them. To fix this issue
|
|
you should upgrade to a newer version of OpenSSL (1.1.0 or later). This may
|
|
require you to upgrade to a newer operating system.
|
|
|
|
Why are there no wheels for my Python3.x version?
|
|
-------------------------------------------------
|
|
|
|
Our Python3 wheels are ``abi3`` wheels. This means they support multiple
|
|
versions of Python. The ``abi3`` wheel can be used with any version of Python
|
|
greater than or equal to the version it specifies. Recent versions of ``pip``
|
|
will automatically install ``abi3`` wheels.
|
|
|
|
Why can't I import my PEM file?
|
|
-------------------------------
|
|
|
|
PEM is a format (defined by several RFCs, but originally :rfc:`1421`) for
|
|
encoding keys, certificates and others cryptographic data into a regular form.
|
|
The data is encoded as base64 and wrapped with a header and footer.
|
|
|
|
If you are having trouble importing PEM files, make sure your file fits
|
|
the following rules:
|
|
|
|
* has a one-line header like this: ``-----BEGIN [FILE TYPE]-----``
|
|
(where ``[FILE TYPE]`` is ``CERTIFICATE``, ``PUBLIC KEY``, ``PRIVATE KEY``,
|
|
etc.)
|
|
|
|
* has a one-line footer like this: ``-----END [FILE TYPE]-----``
|
|
|
|
* all lines, except for the final one, must consist of exactly 64
|
|
characters.
|
|
|
|
For example, this is a PEM file for a RSA Public Key: ::
|
|
|
|
-----BEGIN PUBLIC KEY-----
|
|
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7CsKFSzq20NLb2VQDXma
|
|
9DsDXtKADv0ziI5hT1KG6Bex5seE9pUoEcUxNv4uXo2jzAUgyRweRl/DLU8SoN8+
|
|
WWd6YWik4GZvNv7j0z28h9Q5jRySxy4dmElFtIRHGiKhqd1Z06z4AzrmKEzgxkOk
|
|
LJjY9cvwD+iXjpK2oJwNNyavvjb5YZq6V60RhpyNtKpMh2+zRLgIk9sROEPQeYfK
|
|
22zj2CnGBMg5Gm2uPOsGDltl/I/Fdh1aO3X4i1GXwCuPf1kSAg6lPJD0batftkSG
|
|
v0X0heUaV0j1HSNlBWamT4IR9+iJfKJHekOqvHQBcaCu7Ja4kXzx6GZ3M2j/Ja3A
|
|
2QIDAQAB
|
|
-----END PUBLIC KEY-----
|
|
|
|
|
|
.. _`NaCl`: https://nacl.cr.yp.to/
|
|
.. _`PyNaCl`: https://pynacl.readthedocs.io
|
|
.. _`WSGIApplicationGroup`: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIApplicationGroup.html
|
|
.. _`issue`: https://github.com/pyca/cryptography/issues
|