diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.rst | 6 | ||||
| -rw-r--r-- | docs/conf.py | 1 | ||||
| -rw-r--r-- | docs/contributing.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/backends/index.rst (renamed from docs/hazmat/bindings/index.rst) | 2 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst (renamed from docs/hazmat/bindings/interfaces.rst) | 2 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst (renamed from docs/hazmat/bindings/openssl.rst) | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/constant-time.rst | 38 | ||||
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 19 | ||||
| -rw-r--r-- | docs/index.rst | 42 |
12 files changed, 92 insertions, 32 deletions
diff --git a/docs/architecture.rst b/docs/architecture.rst index 5ca2c252..bacde1bb 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -8,6 +8,6 @@ Architecture ``cryptography.hazmat.primitives``. * ``cryptography.hazmat.primitives``: This packages contains low level algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of - ``cryptography.hazmat.bindings``. -* ``cryptography.hazmat.bindings``: This package contains bindings to low level - cryptographic libraries. Our initial target will be OpenSSL. + ``cryptography.hazmat.backends``. +* ``cryptography.hazmat.backends``: This package contains bindings to low level + cryptographic libraries. Our initial target is OpenSSL. diff --git a/docs/conf.py b/docs/conf.py index 77050e72..5092e4d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -257,6 +257,5 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/contributing.rst b/docs/contributing.rst index 100f13f5..cb9c7283 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -28,6 +28,7 @@ devastating, ``cryptography`` has a strict code review policy: * If somehow the tests get into a failing state on ``master`` (such as by a backwards incompatible release of a dependency) no pull requests may be merged until this is rectified. +* All merged patches must have 100% test coverage. The purpose of these policies is to minimize the chances we merge a change which jeopardizes our users' security. @@ -78,7 +79,7 @@ whether the signature was valid. APIs at the :doc:`/hazmat/primitives/index` layer should always take an explicit backend, APIs at the recipes layer should automatically use the -:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow +:func:`~cryptography.hazmat.backends.default_backend`, but optionally allow specifying a different backend. C bindings diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/backends/index.rst index 746f4596..a89cf0d5 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/backends/index.rst @@ -13,7 +13,7 @@ Bindings Getting a Backend Provider ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. currentmodule:: cryptography.hazmat.bindings +.. currentmodule:: cryptography.hazmat.backends ``cryptography`` aims to support multiple backends to ensure it can provide the widest number of supported cryptographic algorithms as well as supporting diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 711c82c2..b524943d 100644 --- a/docs/hazmat/bindings/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -3,7 +3,7 @@ Backend Interfaces ================== -.. currentmodule:: cryptography.hazmat.bindings.interfaces +.. currentmodule:: cryptography.hazmat.backends.interfaces Backend implementations may provide a number of interfaces to support operations diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/backends/openssl.rst index d6bfa672..12fbff04 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -5,7 +5,7 @@ OpenSSL These are `CFFI`_ bindings to the `OpenSSL`_ C library. -.. data:: cryptography.hazmat.bindings.openssl.backend +.. data:: cryptography.hazmat.backends.openssl.backend This is the exposed API for the OpenSSL bindings. It has two public attributes: diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst new file mode 100644 index 00000000..632e7c68 --- /dev/null +++ b/docs/hazmat/primitives/constant-time.rst @@ -0,0 +1,38 @@ +.. hazmat:: + +Constant time functions +======================= + +.. currentmodule:: cryptography.hazmat.primitives.constant_time + +This module contains functions for operating with secret data in a way that +does not leak information about that data through how long it takes to perform +the operation. These functions should be used whenever operating on secret data +along with data that is user supplied. + +An example would be comparing a HMAC signature received from a client to the +one generated by the server code for authentication purposes. + +For more information about this sort of issue, see `Coda Hale's blog post`_ +about the timing attacks on KeyCzar and Java's ``MessageDigest.isEqual()``. + + +.. function:: bytes_eq(a, b) + + Compare ``a`` and ``b`` to one another in constant time if they are of the + same length. + + .. doctest:: + + >>> from cryptography.hazmat.primitives import constant_time + >>> constant_time.bytes_eq(b"foo", b"foo") + True + >>> constant_time.bytes_eq(b"foo", b"bar") + False + + :param a bytes: The left-hand side. + :param b bytes: The right-hand side. + :returns boolean: True if ``a`` has the same bytes as ``b``. + + +.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/ diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 312d7e69..90ca198a 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -20,7 +20,7 @@ Message Digests .. doctest:: - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend()) >>> digest.update(b"abc") @@ -39,7 +39,7 @@ Message Digests provider such as those described in :ref:`below <cryptographic-hash-algorithms>`. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.HashBackend` + :class:`~cryptography.hazmat.backends.interfaces.HashBackend` provider. .. method:: update(data) diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index db5e98d3..0c0d0220 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -27,7 +27,7 @@ message. .. doctest:: - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") @@ -41,7 +41,7 @@ message. provider such as those described in :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.HMACBackend` + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. .. method:: update(msg) diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 614c414a..b115fdbc 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -10,4 +10,5 @@ Primitives hmac symmetric-encryption padding + constant-time interfaces diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 2f390175..f4d0457a 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -12,9 +12,6 @@ Symmetric Encryption key = binascii.unhexlify(b"0" * 32) iv = binascii.unhexlify(b"0" * 32) - from cryptography.hazmat.bindings import default_backend - backend = default_backend() - Symmetric encryption is a way to encrypt (hide the plaintext value) material where the sender and receiver both use the same key. Note that symmetric @@ -37,6 +34,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.backends import default_backend + >>> backend = default_backend() >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() @@ -52,7 +51,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider such as those described :ref:`below <symmetric-encryption-modes>`. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend` + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. .. method:: encryptor() @@ -230,8 +229,9 @@ Weak Ciphers .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.backends import default_backend >>> algorithm = algorithms.ARC4(key) - >>> cipher = Cipher(algorithm, mode=None, backend=backend) + >>> cipher = Cipher(algorithm, mode=None, backend=default_backend()) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") >>> decryptor = cipher.decryptor() @@ -266,16 +266,18 @@ Modes A good construction looks like: - .. code-block:: pycon + .. doctest:: >>> import os + >>> from cryptography.hazmat.primitives.ciphers.modes import CBC >>> iv = os.urandom(16) >>> mode = CBC(iv) While the following is bad and will leak information: - .. code-block:: pycon + .. doctest:: + >>> from cryptography.hazmat.primitives.ciphers.modes import CBC >>> iv = "a" * 16 >>> mode = CBC(iv) @@ -356,7 +358,8 @@ Modes .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend) + >>> from cryptography.hazmat.backends import default_backend + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend()) >>> encryptor = cipher.encryptor() >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() diff --git a/docs/index.rst b/docs/index.rst index a1a650a8..381063df 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,6 @@ Welcome to ``cryptography`` =========================== -.. warning:: - - ``cryptography`` is very young, and very incomplete. - ``cryptography`` is a Python library which exposes cryptographic recipes and primitives. We hope it'll be your one-stop-shop for all your cryptographic needs in Python. @@ -36,9 +32,24 @@ existing libraries: * Poor introspectability, and thus poor testability. * Extremely error prone APIs, and bad defaults. +Layout +------ + +``cryptography`` is broadly divided into two levels. One with safe +cryptographic recipes, "cryptography for humans" if you will. These are safe +and easy to use and don't require developers to make many decisions. + +The other level is low-level cryptographic primitives. These are often +dangerous and can be used incorrectly. They require making decisions and having +an in-depth knowledge of the cryptographic concepts at work. Because of the +potential danger in working at this level, this is referred to as the +"hazardous materials" or "hazmat" layer. -Contents --------- +We recommend using the recipes layer whenever possible, and falling back to the +hazmat layer only when necessary. + +The recipes layer +~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 @@ -46,15 +57,22 @@ Contents architecture exceptions glossary - contributing - security - community -Hazardous Materials -------------------- +The hazardous materials layer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 hazmat/primitives/index - hazmat/bindings/index + hazmat/backends/index + +The ``cryptography`` open source project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 2 + + contributing + security + community |