aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/architecture.rst5
-rw-r--r--docs/conf.py16
-rw-r--r--docs/contributing.rst12
-rw-r--r--docs/exceptions.rst6
-rw-r--r--docs/glossary.rst2
-rw-r--r--docs/hazmat/primitives/cryptographic-hashes.rst29
-rw-r--r--docs/hazmat/primitives/hmac.rst14
-rw-r--r--docs/hazmat/primitives/interfaces.rst26
-rw-r--r--docs/hazmat/primitives/symmetric-encryption.rst55
-rw-r--r--docs/security.rst2
10 files changed, 138 insertions, 29 deletions
diff --git a/docs/architecture.rst b/docs/architecture.rst
index 4cf639c2..5ca2c252 100644
--- a/docs/architecture.rst
+++ b/docs/architecture.rst
@@ -1,11 +1,6 @@
Architecture
============
-.. warning::
-
- Because ``cryptography`` is so young, much of this document is
- aspirational, rather than documentation.
-
``cryptography`` has three different layers:
* ``cryptography``: This package contains higher level recipes, for example
diff --git a/docs/conf.py b/docs/conf.py
index 69be32e9..77050e72 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,6 +14,12 @@
import os
import sys
+try:
+ import sphinx_rtd_theme
+except ImportError:
+ sphinx_rtd_theme = None
+
+
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -98,16 +104,18 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'default'
+
+if sphinx_rtd_theme:
+ html_theme = "sphinx_rtd_theme"
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+else:
+ html_theme = "default"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 3b301842..97f31e0b 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -122,6 +122,18 @@ So, specifically:
* No blank line at the end.
* Use Sphinx parameter/attribute documentation `syntax`_.
+Because of the inherent challenges in implementing correct cryptographic
+systems, we want to make our documentation point people in the right directions
+as much as possible. To that end:
+
+* When documenting a generic interface, use a strong algorithm in examples.
+ (e.g. when showing a hashing example, don't use
+ :class:`cryptography.hazmat.primitives.hashes.MD5`)
+* When giving prescriptive advice, always provide references and supporting
+ material.
+* When there is real disagreement between cryptographic experts, represent both
+ sides of the argument and describe the trade-offs clearly.
+
When documenting a new module in the ``hazmat`` package, its documentation
should begin with the "Hazardous Materials" warning:
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
index 6ac11b3c..ab1b28fe 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -3,7 +3,13 @@ Exceptions
.. currentmodule:: cryptography.exceptions
+.. class:: AlreadyFinalized
+
+ This is raised when a context is used after being finalized.
+
+
.. class:: UnsupportedAlgorithm
This is raised when a backend doesn't support the requested algorithm (or
combination of algorithms).
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index e4fc8283..b6f2d06f 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -27,4 +27,4 @@ Glossary
asymmetric cryptography
Cryptographic operations where encryption and decryption use different
- keys. There are seperate encryption and decryption keys.
+ keys. There are separate encryption and decryption keys.
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 76ca20c0..52e87702 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -12,9 +12,9 @@ Message Digests
results (with a high probability) in different digests.
This is an implementation of
- :class:`cryptography.hazmat.primitives.interfaces.HashContext` meant to
+ :class:`~cryptography.hazmat.primitives.interfaces.HashContext` meant to
be used with
- :class:`cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+ :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
implementations to provide an incremental interface to calculating
various message digests.
@@ -27,19 +27,34 @@ Message Digests
>>> digest.finalize()
'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90'
+ Keep in mind that attacks against cryptographic hashes only get stronger
+ with time, and that often algorithms that were once thought to be strong,
+ become broken. Because of this it's important to include a plan for
+ upgrading the hash algorithm you use over time. For more information, see
+ `Lifetimes of cryptographic hash functions`_.
+
.. method:: update(data)
:param bytes data: The bytes you wish to hash.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
.. method:: copy()
- :return: a new instance of this object with a copied internal state.
+ Copy this :class:`Hash` instance, usually so that we may call
+ :meth:`finalize` and get an intermediate digest value while we continue
+ to call :meth:`update` on the original.
+
+ :return: A new instance of :class:`Hash` which can be updated
+ 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.
+ 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.
@@ -102,9 +117,13 @@ MD5
.. warning::
MD5 is a deprecated hash algorithm that has practical known collision
- attacks. You are strongly discouraged from using it.
+ attacks. You are strongly discouraged from using it. Existing applications
+ should strongly consider moving away.
.. class:: MD5()
MD5 is a deprecated cryptographic hash function. It has a 128-bit message
digest and has practical known collision attacks.
+
+
+.. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index bd1a4934..cff2dbf1 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -36,15 +36,25 @@ message.
.. method:: update(msg)
:param bytes msg: The bytes to hash and authenticate.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
.. method:: copy()
- :return: a new instance of this object with a copied internal state.
+ Copy this :class:`HMAC` instance, usually so that we may call
+ :meth:`finalize` and get an intermediate digest value while we continue
+ to call :meth:`update` on the original.
+
+ :return: A new instance of :class:`HMAC` which can be updated
+ 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.
+ 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/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 7068316e..11cff51a 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -12,11 +12,33 @@ to document argument and return types.
.. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html
-Cipher Modes
-~~~~~~~~~~~~
+Symmetric Ciphers
+~~~~~~~~~~~~~~~~~
.. currentmodule:: cryptography.hazmat.primitives.interfaces
+
+.. class:: CipherAlgorithm
+
+ A named symmetric encryption algorithm.
+
+ .. attribute:: name
+
+ :type: str
+
+ The standard name for the mode, for example, "AES", "Camellia", or
+ "Blowfish".
+
+ .. attribute:: key_size
+
+ :type: int
+
+ The number of bits in the key being used.
+
+
+Cipher Modes
+------------
+
Interfaces used by the symmetric cipher modes described in
:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 5f1a64a1..eef359d6 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -14,13 +14,22 @@ Symmetric Encryption
Symmetric encryption is a way to encrypt (hide the plaintext value) material
-where the encrypter and decrypter both use the same key.
+where the sender and receiver both use the same key. Note that symmetric
+encryption is **not** sufficient for most applications, because it only
+provides secrecy (an attacker can't see the message) but not authenticity (an
+attacker can create bogus messages and force the application to decrypt them).
+For this reason it is *strongly* recommended to combine encryption with a
+message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in
+an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
.. class:: Cipher(algorithm, mode)
- Cipher objects combine an algorithm (such as AES) with a mode (such as
- CBC, CTR, or GCM). A simple example of encrypting (and then decrypting)
- content with AES is:
+ Cipher objects combine an algorithm (such as
+ :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a
+ mode (such as
+ :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` or
+ :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`). A simple
+ example of encrypting (and then decrypting) content with AES is:
.. doctest::
@@ -70,6 +79,7 @@ where the encrypter and decrypter both use the same key.
:param bytes data: The data you wish to pass into the context.
:return bytes: Returns the data that was encrypted or decrypted.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
When the ``Cipher`` was constructed in a mode that turns it into a
stream cipher (e.g.
@@ -81,6 +91,10 @@ where the encrypter and decrypter both use the same key.
:return bytes: Returns the remainder of the data.
+ Once ``finalize`` is called this object can no longer be used and
+ :meth:`update` and :meth:`finalize` will raise
+ :class:`~cryptography.exceptions.AlreadyFinalized`.
+
Algorithms
~~~~~~~~~~
@@ -107,10 +121,10 @@ Algorithms
.. class:: TripleDES(key)
- Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a
- block cipher standardized by NIST. Triple DES has known cryptoanalytic
+ Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a
+ block cipher standardized by NIST. Triple DES has known crypto-analytic
flaws, however none of them currently enable a practical attack.
- Nonetheless, Triples DES is not reccomended for new applications because it
+ Nonetheless, Triples DES is not recommended for new applications because it
is incredibly slow; old applications should consider moving away from it.
:param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits
@@ -143,12 +157,32 @@ Weak Ciphers
Blowfish is a block cipher developed by Bruce Schneier. It is known to be
susceptible to attacks when using weak keys. The author has recommended
- that users of Blowfish move to newer algorithms like
- :class:`AES`.
+ that users of Blowfish move to newer algorithms, such as :class:`AES`.
:param bytes key: The secret key, 32-448 bits in length (in increments of
8). This must be kept secret.
+.. class:: ARC4(key)
+
+ ARC4 (Alleged RC4) is a stream cipher with serious weaknesses in its
+ initial stream output. Its use is strongly discouraged. ARC4 does not use
+ mode constructions.
+
+ :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``,
+ ``192``, or ``256`` bits in length. This must be kept
+ secret.
+
+ .. doctest::
+
+ >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+ >>> algorithm = algorithms.ARC4(key)
+ >>> cipher = Cipher(algorithm, mode=None)
+ >>> encryptor = cipher.encryptor()
+ >>> ct = encryptor.update(b"a secret message")
+ >>> decryptor = cipher.decryptor()
+ >>> decryptor.update(ct)
+ 'a secret message'
+
.. _symmetric-encryption-modes:
@@ -252,3 +286,6 @@ Insecure Modes
ciphers. Each block of data is encrypted in the same way. This means
identical plaintext blocks will always result in identical ciphertext
blocks, and thus result in information leakage
+
+
+.. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html
diff --git a/docs/security.rst b/docs/security.rst
index 36c8e0f7..88959709 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -5,7 +5,7 @@ We take the security of ``cryptography`` seriously. If you believe you've
identified a security issue in it, please report it to
``alex.gaynor@gmail.com``. Message may be encrypted with PGP using key
fingerprint ``E27D 4AA0 1651 72CB C5D2 AF2B 125F 5C67 DFE9 4084`` (this public
-key is available from most commonly-used keyservers).
+key is available from most commonly-used key servers).
Once you’ve submitted an issue via email, you should receive an acknowledgment
within 48 hours, and depending on the action to be taken, you may receive