faq.rst 2.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546
  1. Frequently asked questions
  2. ==========================
  3. How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)?
  4. --------------------------------------------------------------------------------
  5. While ``cryptography`` and `NaCl`_ both share the goal of making cryptography
  6. easier, and safer, to use for developers, ``cryptography`` is designed to be a
  7. general purpose library, interoperable with existing systems, while NaCl
  8. features a collection of hand selected algorithms.
  9. ``cryptography``'s :ref:`recipes <cryptography-layout>` layer has similar goals
  10. to NaCl.
  11. If you prefer NaCl's design, we highly recommend `PyNaCl`_.
  12. Compiling ``cryptography`` on OS X produces a ``fatal error: 'openssl/aes.h' file not found`` error
  13. ---------------------------------------------------------------------------------------------------
  14. This happens because OS X 10.11 no longer includes a copy of OpenSSL.
  15. ``cryptography`` now provides wheels which include a statically linked copy of
  16. OpenSSL. You're seeing this error because your copy of pip is too old to find
  17. our wheel files. Upgrade your copy of pip with ``pip install -U pip`` and then
  18. try install ``cryptography`` again.
  19. Starting ``cryptography`` using ``mod_wsgi`` produces an ``InternalError`` during a call in ``_register_osrandom_engine``
  20. -------------------------------------------------------------------------------------------------------------------------
  21. This happens because ``mod_wsgi`` uses sub-interpreters, which can cause a
  22. problem during initialization of the OpenSSL backend. To resolve this set the
  23. `WSGIApplicationGroup`_ to ``%{GLOBAL}`` in the ``mod_wsgi`` configuration.
  24. ``cryptography`` raised an ``InternalError`` and I'm not sure what to do?
  25. -------------------------------------------------------------------------
  26. Frequently ``InternalError`` is raised when there are errors on the OpenSSL
  27. error stack that were placed there by other libraries that are also using
  28. OpenSSL. Try removing the other libraries and see if the problem persists.
  29. If you have no other libraries using OpenSSL in your process, or they do not
  30. appear to be at fault, it's possible that this is a bug in ``cryptography``.
  31. Please file an `issue`_ with instructions on how to reproduce it.
  32. .. _`NaCl`: https://nacl.cr.yp.to/
  33. .. _`PyNaCl`: https://pynacl.readthedocs.org
  34. .. _`WSGIApplicationGroup`: https://modwsgi.readthedocs.org/en/develop/configuration-directives/WSGIApplicationGroup.html
  35. .. _`issue`: https://github.com/pyca/cryptography/issues