diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/changelog.rst | 11 | ||||
| -rw-r--r-- | docs/contributing.rst | 2 | ||||
| -rw-r--r-- | docs/doing-a-release.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 32 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 16 | ||||
| -rw-r--r-- | docs/index.rst | 6 |
6 files changed, 52 insertions, 16 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 00000000..41db635e --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,11 @@ +Changelog +========= +0.2 - 2014-XX-XX +~~~~~~~~~~~~~~~~ + +* In development. + +0.1 - 2014-01-08 +~~~~~~~~~~~~~~~~ + +* Initial release. diff --git a/docs/contributing.rst b/docs/contributing.rst index 657c4359..8e32c368 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -29,6 +29,8 @@ devastating, ``cryptography`` has a strict code review policy: backwards incompatible release of a dependency) no pull requests may be merged until this is rectified. * All merged patches must have 100% test coverage. +* New features and significant bug fixes should be documented in the + :doc:`/changelog`. The purpose of these policies is to minimize the chances we merge a change which jeopardizes our users' security. diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index 0f382064..194e82f4 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -10,6 +10,7 @@ The first step in doing a release is bumping the version number in the software. * Update the version number in ``cryptography/__about__.py``. +* Set the release date in the :doc:`/changelog`. * Do a commit indicating this. * Send a pull request with this. * Wait for it to be merged. diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index dc5c54f8..a21799be 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -37,6 +37,16 @@ message. If the backend doesn't support the requested ``algorithm`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + To check that a given signature is correct use the :meth:`verify` method. + You will receive an exception if the signature is wrong: + + .. code-block:: pycon + + >>> h.verify(b"an incorrect signature") + Traceback (most recent call last): + ... + cryptography.exceptions.InvalidSignature: Signature did not match digest. + :param key: Secret key as ``bytes``. :param algorithm: A :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` @@ -61,17 +71,6 @@ message. and finalized independently of the original instance. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` - .. method:: finalize() - - Finalize the current context and return the message digest as bytes. - - Once ``finalize`` is called this object can no longer be used and - :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. - - :return bytes: The message digest as bytes. - :raises cryptography.exceptions.AlreadyFinalized: - .. method:: verify(signature) Finalize the current context and securely compare digest to @@ -82,3 +81,14 @@ message. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` :raises cryptography.exceptions.InvalidSignature: If signature does not match digest + + .. method:: finalize() + + Finalize the current context and return the message digest as bytes. + + Once ``finalize`` is called this object can no longer be used and + :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. + + :return bytes: The message digest as bytes. + :raises cryptography.exceptions.AlreadyFinalized: diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 2233d525..83165690 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -169,6 +169,8 @@ Modes CBC (Cipher block chaining) is a mode of operation for block ciphers. It is considered cryptographically strong. + **Padding is required when using this mode.** + :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included in a transmitted message). Must be the @@ -211,6 +213,8 @@ Modes cryptographically strong. It transforms a block cipher into a stream cipher. + **This mode does not require padding.** + :param bytes nonce: Should be random bytes. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce with the same key compromises the security of every @@ -224,6 +228,8 @@ Modes OFB (Output Feedback) is a mode of operation for block ciphers. It transforms a block cipher into a stream cipher. + **This mode does not require padding.** + :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included in a transmitted message). Must be the @@ -237,6 +243,8 @@ Modes CFB (Cipher Feedback) is a mode of operation for block ciphers. It transforms a block cipher into a stream cipher. + **This mode does not require padding.** + :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included in a transmitted message). Must be the @@ -261,6 +269,8 @@ Modes Additional means of verifying integrity (like :doc:`HMAC </hazmat/primitives/hmac>`) are not necessary. + **This mode does not require padding.** + :param bytes initialization_vector: Must be random bytes. They do not need to be kept secret (they can be included in a transmitted message). NIST @@ -365,6 +375,8 @@ Insecure Modes identical plaintext blocks will always result in identical ciphertext blocks, and thus result in information leakage + **Padding is required when using this mode.** + Interfaces ---------- @@ -377,8 +389,8 @@ Interfaces finish the operation and obtain the remainder of the data. Block ciphers require that plaintext or ciphertext always be a multiple of - their block size, because of that **padding** is often required to make a - message the correct size. ``CipherContext`` will not automatically apply + their block size, because of that **padding** is sometimes required to make + a message the correct size. ``CipherContext`` will not automatically apply any padding; you'll need to add your own. For block ciphers the recommended padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you are using a stream cipher mode (such as diff --git a/docs/index.rst b/docs/index.rst index 4bbfe7fd..e17b4f9f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,12 +8,11 @@ needs in Python. Installing ---------- -We don't yet have a release on PyPI, for now you can install ``cryptography`` -directly from Github: +You can install ``cryptography`` with ``pip``: .. code-block:: console - $ pip install git+https://github.com/pyca/cryptography + $ pip install cryptography Why a new crypto library for Python? ------------------------------------ @@ -80,4 +79,5 @@ The ``cryptography`` open source project security api-stability doing-a-release + changelog community |