From ef0fcf26c920c011948f078481739f4e2c31535f Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 6 Nov 2013 11:12:45 -0800 Subject: Add a default_backend and start updating docs. --- docs/hazmat/primitives/cryptographic-hashes.rst | 6 +++--- docs/hazmat/primitives/hmac.rst | 5 +++-- docs/hazmat/primitives/symmetric-encryption.rst | 9 ++++++--- 3 files changed, 12 insertions(+), 8 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 52e87702..b3db9f19 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -5,7 +5,7 @@ Message Digests .. currentmodule:: cryptography.hazmat.primitives.hashes -.. class:: Hash(algorithm) +.. class:: Hash(algorithm, backend) A cryptographic hash function takes an arbitrary block of data and calculates a fixed-size bit string (a digest), such that different data @@ -19,9 +19,9 @@ Message Digests various message digests. .. doctest:: - + >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes - >>> digest = hashes.Hash(hashes.SHA256()) + >>> digest = hashes.Hash(hashes.SHA256(), default_backend()) >>> digest.update(b"abc") >>> digest.update(b"123") >>> digest.finalize() diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index cff2dbf1..7d87ca7e 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -15,7 +15,7 @@ message authentication codes using a cryptographic hash function coupled with a secret key. You can use an HMAC to verify integrity as well as authenticate a message. -.. class:: HMAC(key, algorithm) +.. class:: HMAC(key, algorithm, backend) HMAC objects take a ``key`` and a provider of :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. @@ -27,8 +27,9 @@ message. .. doctest:: + >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac - >>> h = hmac.HMAC(key, hashes.SHA256()) + >>> h = hmac.HMAC(key, hashes.SHA256(), default_backend()) >>> h.update(b"message to hash") >>> h.finalize() '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index eef359d6..42d2090c 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -12,6 +12,9 @@ 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 @@ -22,7 +25,7 @@ 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`_. -.. class:: Cipher(algorithm, mode) +.. class:: Cipher(algorithm, mode, backend) Cipher objects combine an algorithm (such as :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a @@ -33,8 +36,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: - >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv)) + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, mode + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() -- cgit v1.2.3 From 846460ae25554cbf007c0b65f8d7997d543ea53e Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 6 Nov 2013 11:24:50 -0800 Subject: Fix doctests. --- docs/hazmat/primitives/cryptographic-hashes.rst | 1 + docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index b3db9f19..f05b45a5 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -19,6 +19,7 @@ Message Digests various message digests. .. doctest:: + >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes >>> digest = hashes.Hash(hashes.SHA256(), default_backend()) diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 42d2090c..e7d019da 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -36,7 +36,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: - >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, mode + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() -- cgit v1.2.3 From 63fa19ace98c2c88a6065acc9e944a71480ff651 Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 20 Nov 2013 10:49:13 -0800 Subject: Use backend as keyword argument everywhere. --- docs/hazmat/primitives/cryptographic-hashes.rst | 2 +- docs/hazmat/primitives/hmac.rst | 2 +- docs/hazmat/primitives/symmetric-encryption.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index f05b45a5..92f8fa30 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -22,7 +22,7 @@ Message Digests >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes - >>> digest = hashes.Hash(hashes.SHA256(), default_backend()) + >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend()) >>> digest.update(b"abc") >>> digest.update(b"123") >>> digest.finalize() diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 7d87ca7e..10db40ee 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -29,7 +29,7 @@ message. >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac - >>> h = hmac.HMAC(key, hashes.SHA256(), default_backend()) + >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") >>> h.finalize() '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index e7d019da..76f68a12 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -37,7 +37,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend) + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() @@ -179,7 +179,7 @@ Weak Ciphers >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes >>> algorithm = algorithms.ARC4(key) - >>> cipher = Cipher(algorithm, mode=None) + >>> cipher = Cipher(algorithm, mode=None, backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") >>> decryptor = cipher.decryptor() -- cgit v1.2.3 From 663295d015d4aa65258f14d91c6350726604350c Mon Sep 17 00:00:00 2001 From: David Reid Date: Wed, 20 Nov 2013 13:55:08 -0800 Subject: Document all the parameters including cross references to specific providers where appropriate. --- docs/hazmat/primitives/cryptographic-hashes.rst | 10 ++++++++++ docs/hazmat/primitives/hmac.rst | 10 ++++++++++ docs/hazmat/primitives/symmetric-encryption.rst | 14 ++++++++++++-- 3 files changed, 32 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 92f8fa30..312d7e69 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -34,6 +34,14 @@ Message Digests upgrading the hash algorithm you use over time. For more information, see `Lifetimes of cryptographic hash functions`_. + :param algorithm: A + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider such as those described in + :ref:`below `. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.HashBackend` + provider. + .. method:: update(data) :param bytes data: The bytes you wish to hash. @@ -60,6 +68,8 @@ Message Digests :return bytes: The message digest as bytes. +.. _cryptographic-hash-algorithms: + SHA-1 ~~~~~ diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 10db40ee..db5e98d3 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -34,6 +34,16 @@ message. >>> h.finalize() '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' + + :param key: Secret key as ``bytes``. + :param algorithm: A + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider such as those described in + :ref:`Cryptographic Hashes `. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.HMACBackend` + provider. + .. method:: update(msg) :param bytes msg: The bytes to hash and authenticate. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 76f68a12..f63ad90a 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -44,8 +44,16 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. >>> decryptor.update(ct) + decryptor.finalize() 'a secret message' - :param algorithms: One of the algorithms described below. - :param mode: One of the modes described below. + :param algorithms: A + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider such as those described + :ref:`below `. + :param mode: A :class:`~cryptography.hazmat.primitives.interfaces.Mode` + provider such as those described + :ref:`below `. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend` + provider. .. method:: encryptor() @@ -98,6 +106,8 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :meth:`update` and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. +.. _symmetric-encryption-algorithms: + Algorithms ~~~~~~~~~~ -- cgit v1.2.3