From d0ec60e7d671bb1f927cd711949d95441d947933 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 16 Oct 2013 08:46:50 -0500 Subject: AES Counter support * vectors from RFC 3686 * Documentation for the mode --- docs/primitives/symmetric-encryption.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs/primitives') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index c4bbf0a5..52bd6a40 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -77,6 +77,19 @@ Modes reuse an ``initialization_vector`` with a given ``key``. +.. class:: cryptography.primitives.block.modes.CTR(nonce) + + CTR (Counter) is a mode of operation for block ciphers. It is considered + cryptographically strong. + + :param bytes nonce: Must be random bytes. They do not need to be kept + secret (they can be included in a transmitted + message). Must be the same number of bytes as the + ``block_size`` of the cipher. It is critical to + never reuse a ``nonce`` with a given ``key``. Unlike + CBC, reusing a nonce compromises the security of + all data encrypted under the key (see: two time pad). + .. class:: cryptography.primitives.block.modes.OFB(initialization_vector) OFB (Output Feedback) is a mode of operation for block ciphers. It -- cgit v1.2.3 From 389892f8ad5700b152d20948ded9c540b2cdaff8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 16 Oct 2013 13:20:50 -0500 Subject: update docs to roughly describe many time pad attack & link cbc --- docs/primitives/symmetric-encryption.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 52bd6a40..9520d6eb 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -87,8 +87,11 @@ Modes message). Must be the same number of bytes as the ``block_size`` of the cipher. It is critical to never reuse a ``nonce`` with a given ``key``. Unlike - CBC, reusing a nonce compromises the security of - all data encrypted under the key (see: two time pad). + :class:`~cryptography.primitives.block.modes.CBC`, + reusing a nonce compromises the security of all data + encrypted under the key. Specifically, + (pt1 xor keystream) xor (pt2 xor keystream) is + equivalent to (pt1 xor pt2). .. class:: cryptography.primitives.block.modes.OFB(initialization_vector) -- cgit v1.2.3 From 0ba2f9464693fe7ae0167eb47df9b1a96408ed9c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 17 Oct 2013 12:06:46 -0500 Subject: remove confusing explanation about reusing nonce in counter mode docs --- docs/primitives/symmetric-encryption.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 9520d6eb..21421d16 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -89,9 +89,7 @@ Modes never reuse a ``nonce`` with a given ``key``. Unlike :class:`~cryptography.primitives.block.modes.CBC`, reusing a nonce compromises the security of all data - encrypted under the key. Specifically, - (pt1 xor keystream) xor (pt2 xor keystream) is - equivalent to (pt1 xor pt2). + encrypted under the key. .. class:: cryptography.primitives.block.modes.OFB(initialization_vector) -- cgit v1.2.3 From 4506428ad913d183ad90c0fed668745a6d2aaf33 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 17 Oct 2013 13:41:53 -0500 Subject: ctr doc language take 3 --- docs/primitives/symmetric-encryption.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index 21421d16..a1f8ba32 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -77,19 +77,25 @@ Modes reuse an ``initialization_vector`` with a given ``key``. + .. class:: cryptography.primitives.block.modes.CTR(nonce) + .. warning:: + + Counter mode is not recommended for use with block ciphers that have a + block size of less than 128-bits. + CTR (Counter) is a mode of operation for block ciphers. It is considered cryptographically strong. - :param bytes nonce: Must be random bytes. They do not need to be kept - secret (they can be included in a transmitted - message). Must be the same number of bytes as the - ``block_size`` of the cipher. It is critical to - never reuse a ``nonce`` with a given ``key``. Unlike - :class:`~cryptography.primitives.block.modes.CBC`, - reusing a nonce compromises the security of all data - encrypted under the key. + :param bytes nonce: Recommended to be random. It is critical to never reuse + a ```nonce``` (or its subsequent incremented values) + with a given key. Any reuse of the nonce with the same + key compromises the security of every message encrypted + with that key. Must be the same number of bytes as the + ```block_size``` of the cipher with a given key. The + nonce does not need to be kept secret and may be + included alongside the ciphertext. .. class:: cryptography.primitives.block.modes.OFB(initialization_vector) -- cgit v1.2.3 From 89b3dd38c32b19853d24caa0f091a0dd78e54084 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 17 Oct 2013 14:02:45 -0500 Subject: additional doc work on ctr --- docs/primitives/symmetric-encryption.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst index a1f8ba32..7899e67d 100644 --- a/docs/primitives/symmetric-encryption.rst +++ b/docs/primitives/symmetric-encryption.rst @@ -88,14 +88,13 @@ Modes CTR (Counter) is a mode of operation for block ciphers. It is considered cryptographically strong. - :param bytes nonce: Recommended to be random. It is critical to never reuse - a ```nonce``` (or its subsequent incremented values) - with a given key. Any reuse of the nonce with the same - key compromises the security of every message encrypted - with that key. Must be the same number of bytes as the - ```block_size``` of the cipher with a given key. The - nonce does not need to be kept secret and may be - included alongside the ciphertext. + :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 + message encrypted with that key. Must be the same + number of bytes as the ``block_size`` of the cipher + with a given key. The nonce does not need to be kept + secret and may be included alongside the ciphertext. .. class:: cryptography.primitives.block.modes.OFB(initialization_vector) -- cgit v1.2.3 From 36e7d0df315dca887f5b073e17209ee3eeb5a576 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 18 Oct 2013 18:54:40 -0500 Subject: MD5 support + documentation for all hashes --- docs/primitives/cryptographic-hashes.rst | 164 +++++++++++++++++++++++++++++++ docs/primitives/index.rst | 1 + 2 files changed, 165 insertions(+) create mode 100644 docs/primitives/cryptographic-hashes.rst (limited to 'docs/primitives') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst new file mode 100644 index 00000000..1499f762 --- /dev/null +++ b/docs/primitives/cryptographic-hashes.rst @@ -0,0 +1,164 @@ +Message Digests +==================== + +SHA-1 +~~~~~~~ + +.. attention:: + + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. + +.. class:: cryptography.primitives.hashes.SHA1() + + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + + +SHA-2 Family +~~~~~~~ + +.. class:: cryptography.primitives.hashes.SHA224() + + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA256() + + SHA-256 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 256-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA384() + + SHA-384 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 384-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA512() + + SHA-512 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 512-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +RIPEMD160 +~~~~~~~ + +.. class:: cryptography.primitives.hashes.RIPEMD160() + + RIPEMD160 is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 160-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +Whirlpool +~~~~~~~ + +.. class:: cryptography.primitives.hashes.Whirlpool() + + Whirlpool is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 512-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +MD5 +~~~~~~~ + +.. warning:: + + MD5 is a deprecated hash algorithm that has practical known collision + attacks. You are strongly discouraged from using it. + +.. class:: cryptography.primitives.hashes.MD5() + + MD5 is a deprecated cryptographic hash function. It has a 160-bit message + digest and has practical known collision attacks. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst index 1066e30e..c18c62ca 100644 --- a/docs/primitives/index.rst +++ b/docs/primitives/index.rst @@ -4,4 +4,5 @@ Primitives .. toctree:: :maxdepth: 1 + cryptographic-hashes symmetric-encryption -- cgit v1.2.3 From 505491bd64dd410a3ac6c7f01c71e902a3c58917 Mon Sep 17 00:00:00 2001 From: Matthew Iversen Date: Sat, 19 Oct 2013 15:56:17 +1100 Subject: Simplify documentation --- docs/primitives/cryptographic-hashes.rst | 123 ++++++------------------------- 1 file changed, 24 insertions(+), 99 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 1499f762..6e8f601b 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -1,23 +1,20 @@ Message Digests ==================== -SHA-1 -~~~~~~~ - -.. attention:: - - NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications - are strongly suggested to use SHA-2 over SHA-1. - -.. class:: cryptography.primitives.hashes.SHA1() +.. class:: cryptography.primitives.hashes.BaseHash - SHA-1 is a cryptographic hash function standardized by NIST. It has a - 160-bit message digest. + Abstract base class that implements a common interface for + all hash algorithms that follow here .. method:: update(string) :param bytes string: The bytes you wish to hash. + .. method:: copy() + + :return: a new instance of this object with a + copied internal state. + .. method:: digest() :return bytes: The message digest as bytes. @@ -26,120 +23,60 @@ SHA-1 :return str: The message digest as hex. +SHA-1 +~~~~~ -SHA-2 Family -~~~~~~~ - -.. class:: cryptography.primitives.hashes.SHA224() - - SHA-224 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 224-bit message digest. +.. attention:: - .. method:: update(string) + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. - :param bytes string: The bytes you wish to hash. +.. class:: cryptography.primitives.hashes.SHA1() - .. method:: digest() + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. - :return bytes: The message digest as bytes. +SHA-2 Family +~~~~~~~~~~~~ - .. method:: hexdigest() +.. class:: cryptography.primitives.hashes.SHA224() - :return str: The message digest as hex. + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. .. class:: cryptography.primitives.hashes.SHA256() SHA-256 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 256-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - .. class:: cryptography.primitives.hashes.SHA384() SHA-384 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 384-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - .. class:: cryptography.primitives.hashes.SHA512() SHA-512 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 512-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - RIPEMD160 -~~~~~~~ +~~~~~~~~~ .. class:: cryptography.primitives.hashes.RIPEMD160() RIPEMD160 is a cryptographic hash function that is part of ISO/IEC 10118-3:2004. It has a 160-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - Whirlpool -~~~~~~~ +~~~~~~~~~ .. class:: cryptography.primitives.hashes.Whirlpool() Whirlpool is a cryptographic hash function that is part of ISO/IEC 10118-3:2004. It has a 512-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - MD5 -~~~~~~~ +~~~ .. warning:: @@ -150,15 +87,3 @@ MD5 MD5 is a deprecated cryptographic hash function. It has a 160-bit message digest and has practical known collision attacks. - - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. -- cgit v1.2.3 From 6b9ddeb015e3e36ba955c58191820ba1c07bdd76 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 12:28:15 -0500 Subject: fix doc formatting and rename update param to "data" --- docs/primitives/cryptographic-hashes.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 6e8f601b..397e50d7 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -3,17 +3,16 @@ Message Digests .. class:: cryptography.primitives.hashes.BaseHash - Abstract base class that implements a common interface for - all hash algorithms that follow here + Abstract base class that implements a common interface for all hash + algorithms that follow here. - .. method:: update(string) + .. method:: update(data) - :param bytes string: The bytes you wish to hash. + :param bytes data The bytes you wish to hash. .. method:: copy() - :return: a new instance of this object with a - copied internal state. + :return: a new instance of this object with a copied internal state. .. method:: digest() -- cgit v1.2.3 From ddc62f0d6546406b052a96eaa841ab8fd5335be8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 20 Oct 2013 06:14:24 -0700 Subject: Small fixups for the docs --- docs/primitives/cryptographic-hashes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/primitives') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 397e50d7..d4dde042 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -1,5 +1,5 @@ Message Digests -==================== +=============== .. class:: cryptography.primitives.hashes.BaseHash @@ -8,7 +8,7 @@ Message Digests .. method:: update(data) - :param bytes data The bytes you wish to hash. + :param bytes data: The bytes you wish to hash. .. method:: copy() -- cgit v1.2.3