diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contributing.rst | 44 | ||||
| -rw-r--r-- | docs/glossary.rst | 11 | ||||
| -rw-r--r-- | docs/hazmat/bindings/interfaces.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/bindings/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 22 | ||||
| -rw-r--r-- | docs/index.rst | 21 |
6 files changed, 84 insertions, 20 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 97f31e0b..a8010a9a 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. @@ -47,8 +48,42 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function +API Considerations +~~~~~~~~~~~~~~~~~~ + +Most projects' APIs are designed with a philosophy of "make easy things easy, +and make hard things possible". One of the perils of writing cryptographic code +is that code that is secure looks just like code that isn't, and produces +results that are also difficult to distinguish. As a result ``cryptography`` +has, as a design philosophy: "make it hard to do insecure things". Here are a +few strategies for API design which should be both followed, and should inspire +other API choices: + +If it is incorrect to ignore the result of a method, it should raise an +exception, and not return a boolean ``True``/``False`` flag. For example, a +method to verify a signature should raise ``InvalidSignature``, and not return +whether the signature was valid. + +.. code-block:: python + + # This is bad. + def verify(sig): + # ... + return is_valid + + # Good! + def verify(sig): + # ... + if not is_valid: + raise InvalidSignature + +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 +specifying a different backend. + C bindings ----------- +~~~~~~~~~~ When binding C code with ``cffi`` we have our own style guide, it's pretty simple. @@ -141,6 +176,9 @@ should begin with the "Hazardous Materials" warning: .. hazmat:: +When referring to a hypothetical individual (such as "a person receiving an +encrypted message") use gender neutral pronouns (they/them/their). + Development Environment ----------------------- @@ -158,7 +196,7 @@ dependencies, install ``cryptography`` in ``editable`` mode. For example: You are now ready to run the tests and build the documentation. Running Tests -------------- +~~~~~~~~~~~~~ ``cryptography`` unit tests are found in the ``tests/`` directory and are designed to be run using `pytest`_. `pytest`_ will discover the tests @@ -192,7 +230,7 @@ You may not have all the required Python versions installed, in which case you will see one or more ``InterpreterNotFound`` errors. Building Documentation ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ ``cryptography`` documentation is stored in the ``docs/`` directory. It is written in `reStructured Text`_ and rendered using `Sphinx`_. diff --git a/docs/glossary.rst b/docs/glossary.rst index b6f2d06f..63e0a6ce 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -28,3 +28,14 @@ Glossary asymmetric cryptography Cryptographic operations where encryption and decryption use different keys. There are separate encryption and decryption keys. + + authentication + The process of verifying that a message was created by a specific + individual (or program). Like encryption, authentication can be either + symmetric or asymmetric. Authentication is necessary for effective + encryption. + + Ciphertext indistinguishability + This is a property of encryption systems whereby two encrypted messages + aren't distinguishable without knowing the encryption key. This is + considered a basic, necessary property for a working encryption system. diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst index c55d86dc..711c82c2 100644 --- a/docs/hazmat/bindings/interfaces.rst +++ b/docs/hazmat/bindings/interfaces.rst @@ -69,6 +69,8 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :raises ValueError: When tag is not None in an AEAD mode + .. method:: create_symmetric_decryption_ctx(cipher, mode) @@ -86,6 +88,8 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :raises ValueError: When tag is None in an AEAD mode + .. class:: HashBackend diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 194eeb92..d6bfa672 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -21,5 +21,5 @@ These are `CFFI`_ bindings to the `OpenSSL`_ C library. and access constants. -.. _`CFFI`: http://cffi.readthedocs.org/ +.. _`CFFI`: https://cffi.readthedocs.org/ .. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 8d8d558b..ef6f0871 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.bindings 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() @@ -230,8 +229,9 @@ Weak Ciphers .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.bindings 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() @@ -329,9 +329,10 @@ Modes .. danger:: - When using this mode you MUST not use the decrypted data until every - byte has been decrypted. GCM provides NO guarantees of ciphertext - integrity until decryption is complete. + When using this mode you MUST not use the decrypted data until + :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize` + has been called. GCM provides NO guarantees of ciphertext integrity + until decryption is complete. GCM (Galois Counter Mode) is a mode of operation for block ciphers. An AEAD (authenticated encryption with additional data) mode is a type of @@ -349,13 +350,14 @@ Modes Do not reuse an ``initialization_vector`` with a given ``key``. - :param bytes tag: The tag bytes to verify during decryption. Must be provided - for decryption, but is ignored when encrypting. + :param bytes tag: The tag bytes to verify during decryption. When encrypting + this must be None. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend) + >>> from cryptography.hazmat.bindings 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 1b88e24e..2263c32f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,18 +1,27 @@ Welcome to ``cryptography`` =========================== -.. warning:: +``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. - ``cryptography`` is very young, and very incomplete. +Installing +---------- -``cryptography`` is a Python library which exposes cryptographic recipes and -primitives. +We don't yet have a release on PyPI, for now you can install ``cryptography`` +directly from Github: + +.. code-block:: console + + $ pip install git+https://github.com/pyca/cryptography Why a new crypto library for Python? ------------------------------------ -We wanted to address a few issues with existing cryptography libraries in -Python: +If you've done cryptographic work in Python before, you've probably seen some +other libraries in Python, such as *M2Crypto*, *PyCrypto*, or *PyOpenSSL*. In +building ``cryptography`` we wanted to address a few issues we observed in the +existing libraries: * Lack of PyPy and Python 3 support. * Lack of maintenance. |