index.rst 2.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104
  1. Welcome to ``cryptography``
  2. ===========================
  3. ``cryptography`` is a Python library which exposes cryptographic recipes and
  4. primitives. Our goal is for it to be your "cryptographic standard library". If
  5. you are interested in learning more about the field of cryptography, we
  6. recommend `Crypto 101, by Laurens Van Houtven`_.
  7. Installation
  8. ------------
  9. You can install ``cryptography`` with ``pip``:
  10. .. code-block:: console
  11. $ pip install cryptography
  12. See :doc:`Installation <installation>` for more information.
  13. Why a new crypto library for Python?
  14. ------------------------------------
  15. If you've done cryptographic work in Python before, you've probably seen some
  16. other libraries in Python, such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In
  17. building ``cryptography`` we wanted to address a few issues we observed in the
  18. existing libraries:
  19. * Lack of PyPy and Python 3 support.
  20. * Lack of maintenance.
  21. * Use of poor implementations of algorithms (i.e. ones with known side-channel
  22. attacks).
  23. * Lack of high level, "Cryptography for humans", APIs.
  24. * Absence of algorithms such as
  25. :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
  26. :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
  27. * Poor introspectability, and thus poor testability.
  28. * Extremely error prone APIs, and bad defaults.
  29. .. _cryptography-layout:
  30. Layout
  31. ------
  32. ``cryptography`` is broadly divided into two levels. One with safe
  33. cryptographic recipes, "cryptography for humans" if you will. These are safe
  34. and easy to use and don't require developers to make many decisions.
  35. The other level is low-level cryptographic primitives. These are often
  36. dangerous and can be used incorrectly. They require making decisions and having
  37. an in-depth knowledge of the cryptographic concepts at work. Because of the
  38. potential danger in working at this level, this is referred to as the
  39. "hazardous materials" or "hazmat" layer. These live in the
  40. ``cryptography.hazmat`` package, and their documentation will always contain an
  41. admonition at the top.
  42. We recommend using the recipes layer whenever possible, and falling back to the
  43. hazmat layer only when necessary.
  44. The recipes layer
  45. ~~~~~~~~~~~~~~~~~
  46. .. toctree::
  47. :maxdepth: 2
  48. fernet
  49. x509/index
  50. random-numbers
  51. exceptions
  52. faq
  53. glossary
  54. The hazardous materials layer
  55. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  56. .. toctree::
  57. :maxdepth: 2
  58. hazmat/primitives/index
  59. hazmat/backends/index
  60. hazmat/bindings/index
  61. The ``cryptography`` open source project
  62. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63. .. toctree::
  64. :maxdepth: 2
  65. installation
  66. development/index
  67. security
  68. limitations
  69. api-stability
  70. doing-a-release
  71. changelog
  72. community
  73. .. note::
  74. ``cryptography`` has not been subjected to an external audit of its code or
  75. documentation. If you're interested in discussing an audit please
  76. :doc:`get in touch </community>`.
  77. .. _`Crypto 101, by Laurens Van Houtven`: https://www.crypto101.io/