From 4da28c35d93e14a5e6b0a252751e7cfbaf0fe372 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 7 Nov 2013 07:50:17 +0800 Subject: ARC4 support --- docs/hazmat/primitives/symmetric-encryption.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 7d3b072d..4d0703bb 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -149,6 +149,16 @@ Weak Ciphers :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. + Modes ~~~~~ -- cgit v1.2.3 From ab5f0116a2fc906b854b0593675492ec5e406a3d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 8 Nov 2013 10:34:00 -0800 Subject: Be more and more explicit about how to do things correctly --- docs/hazmat/primitives/cryptographic-hashes.rst | 7 ++++--- docs/hazmat/primitives/symmetric-encryption.rst | 23 +++++++++++++++++------ 2 files changed, 21 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 76ca20c0..20fa23cf 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. @@ -102,7 +102,8 @@ 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() diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5f1a64a1..5542e832 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 encrypter and decrypter 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* reccomended to combine encryption with a +message authentication code, such as :doc:`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:: @@ -143,8 +152,7 @@ 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. @@ -252,3 +260,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 -- cgit v1.2.3 From 27283cfa4300162f6a7a667364acab781c49710f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 8 Nov 2013 10:49:22 -0800 Subject: Try to use the sphinx rtd theme locally if it's installed --- docs/conf.py | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'docs') 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 # " v documentation". #html_title = None -- cgit v1.2.3 From 0994c5628a3d960a45f8aac33f0d5d985eb48cf7 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 10 Nov 2013 03:19:14 +0800 Subject: update docs to include arc4 example --- docs/hazmat/primitives/symmetric-encryption.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 9d18ce50..77e61b56 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -159,6 +159,17 @@ Weak Ciphers ``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: -- cgit v1.2.3 From 6392a9c63ce134c4aceefb8a4eb9da2fa7f4f390 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 13 Nov 2013 10:01:15 -0800 Subject: Document AlreadyFinalized. --- docs/exceptions.rst | 6 ++++++ docs/hazmat/primitives/cryptographic-hashes.rst | 13 +++++++++++-- 2 files changed, 17 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 6ac11b3c..d6c15087 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 it has been finalized. + + .. class:: UnsupportedAlgorithm This is raised when a backend doesn't support the requested algorithm (or combination of algorithms). + diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 20fa23cf..7eff1b85 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -30,16 +30,25 @@ Message Digests .. 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` and :meth:`copy` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. -- cgit v1.2.3 From e9d64d78b240d7e8c55ed6e04b0387e6666a6038 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 10:28:01 -0800 Subject: Explain ways in which we can make our docs stronger --- docs/contributing.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 3b301842..98578ee2 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 inherit 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 perscriptive advice, always provide references and supporting + material. +* When there is disagreement about legitimate cryptographic experts, represent + both sides of the argument and describe the tradeoffs clearly. + When documenting a new module in the ``hazmat`` package, its documentation should begin with the "Hazardous Materials" warning: -- cgit v1.2.3 From 9480129db921e84253d3b2a8c8e8becb5f8934b3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 10:33:01 -0800 Subject: Describe that hashes get real broken over time --- docs/hazmat/primitives/cryptographic-hashes.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 20fa23cf..e7b4f2d6 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -27,6 +27,12 @@ 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. @@ -109,3 +115,6 @@ 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 -- cgit v1.2.3 From 5cbab0c815681cff4bdbfde151953df2242ee7c9 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 11:55:57 -0800 Subject: typo fix --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 98578ee2..108ecb6a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -129,7 +129,7 @@ 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 perscriptive advice, always provide references and supporting +* When giving prescriptive advice, always provide references and supporting material. * When there is disagreement about legitimate cryptographic experts, represent both sides of the argument and describe the tradeoffs clearly. -- cgit v1.2.3 From d118c91cc381ce757a6b14f4e4c60505c1cdb48a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 11:56:49 -0800 Subject: Clearer! --- docs/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 108ecb6a..b86faaa1 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -131,8 +131,8 @@ as much as possible. To that end: :class:`cryptography.hazmat.primitives.hashes.MD5`) * When giving prescriptive advice, always provide references and supporting material. -* When there is disagreement about legitimate cryptographic experts, represent - both sides of the argument and describe the tradeoffs clearly. +* When there is real disagreement between cryptographic experts, represent both + sides of the argument and describe the tradeoffs clearly. When documenting a new module in the ``hazmat`` package, its documentation should begin with the "Hazardous Materials" warning: -- cgit v1.2.3 From a659688c5de3c778eb175d0c3eae1db9a2e513a0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 12:54:03 -0800 Subject: typo --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index b86faaa1..8e5b1ced 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -122,7 +122,7 @@ So, specifically: * No blank line at the end. * Use Sphinx parameter/attribute documentation `syntax`_. -Because of the inherit challenges in implementing correct cryptographic +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: -- cgit v1.2.3 From 00fb12ae9d453e1c6db6a046ebf1f68000b44377 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 13 Nov 2013 13:02:44 -0800 Subject: Accidentally less words. --- docs/exceptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index d6c15087..ab1b28fe 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -5,7 +5,7 @@ Exceptions .. class:: AlreadyFinalized - This is raised when a context is used after being it has been finalized. + This is raised when a context is used after being finalized. .. class:: UnsupportedAlgorithm -- cgit v1.2.3 From 34511c697f6f17915b5fe5a58214bb38d779f4a8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 13:30:30 -0800 Subject: Use AlreadyFinalized for symmetric ciphers --- docs/hazmat/primitives/symmetric-encryption.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 28b143ba..950ea8b0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -79,6 +79,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :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. @@ -90,6 +91,10 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :return bytes: Returns the remainder of the data. + Once ``finalize`` is called this object can no longer be used and + :meth:`update` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. + Algorithms ~~~~~~~~~~ -- cgit v1.2.3 From 2cce618311c892aa5a1be2ef899e8ff7a08ae5ef Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 13 Nov 2013 13:49:41 -0800 Subject: Make HMAC methods raise AlreadyFinalized. --- docs/hazmat/primitives/hmac.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'docs') 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: -- cgit v1.2.3 From 9b70ba37ff66e18b67efd0f7d196becc77763c41 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 13:49:43 -0800 Subject: Also mention finalize --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 950ea8b0..4ef15459 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -92,7 +92,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :return bytes: Returns the remainder of the data. Once ``finalize`` is called this object can no longer be used and - :meth:`update` will raise + :meth:`update` and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. Algorithms -- cgit v1.2.3 From 272d537b90af00e5e5153f3818aee7ffe1df4f65 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 13:50:02 -0800 Subject: Here too --- docs/hazmat/primitives/cryptographic-hashes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 525fd889..52e87702 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -53,7 +53,7 @@ Message Digests 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` and :meth:`copy` will raise + :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. -- cgit v1.2.3 From 0a394df31c4165d0230843ebea2717b3cd3caafa Mon Sep 17 00:00:00 2001 From: David Reid Date: Fri, 15 Nov 2013 16:19:50 -0800 Subject: Implement and document an interface for cipher algorithms --- docs/hazmat/primitives/interfaces.rst | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) (limited to 'docs') 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 `. -- cgit v1.2.3 From 9316f4c54edc24487d75c7bc3cb3490d79e364a3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 15 Nov 2013 16:38:42 -0800 Subject: Fixed some spelling mistakes --- docs/conf.py | 1 + docs/glossary.rst | 2 +- docs/hazmat/primitives/symmetric-encryption.rst | 8 ++++---- 3 files changed, 6 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 77050e72..4cddbe41 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,6 +38,7 @@ extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', 'cryptography-docs', + 'sphinxcontrib.spelling', ] # Add any paths that contain templates here, relative to this directory. 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/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 4ef15459..984fe81d 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -18,7 +18,7 @@ where the encrypter and decrypter 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* reccomended to combine encryption with a +For this reason it is *strongly* recommended to combine encryption with a message authentication code, such as :doc:`HMAC `, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. @@ -121,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 -- cgit v1.2.3 From b04080f61d35e147f0e67ae8b009b5860900df82 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 15 Nov 2013 16:39:46 -0800 Subject: Revert this --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 4cddbe41..77050e72 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,6 @@ extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', 'cryptography-docs', - 'sphinxcontrib.spelling', ] # Add any paths that contain templates here, relative to this directory. -- cgit v1.2.3 From 54e04003c2bc136e27c379441e2407191cd9377b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 15 Nov 2013 16:44:41 -0800 Subject: Two more fixes --- docs/contributing.rst | 2 +- docs/security.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 8e5b1ced..97f31e0b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -132,7 +132,7 @@ as much as possible. To that end: * 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 tradeoffs clearly. + 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/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 -- cgit v1.2.3 From b317c7a0dd197140b7ef1fd3446941f5b568e645 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 15 Nov 2013 16:45:52 -0800 Subject: Another two --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 984fe81d..eef359d6 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -14,7 +14,7 @@ Symmetric Encryption Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the encrypter and decrypter both use the same key. Note that symmetric +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). -- cgit v1.2.3 From 601dd098216a3d86a27370717b1cc3371df4c468 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 17 Nov 2013 11:17:59 -0800 Subject: This document is now basically accurate --- docs/architecture.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs') 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 -- cgit v1.2.3