diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/community.rst | 5 | ||||
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/exceptions.rst | 9 | ||||
| -rw-r--r-- | docs/glossary.rst | 30 | ||||
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 29 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 23 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 18 | ||||
| -rw-r--r-- | docs/index.rst | 2 |
8 files changed, 93 insertions, 27 deletions
diff --git a/docs/community.rst b/docs/community.rst index 552318da..bf1cd1c7 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -9,7 +9,12 @@ You can find ``cryptography`` all over the web: * `Documentation`_ * IRC: ``#cryptography-dev`` on ``irc.freenode.net`` +Wherever we interact, we strive to follow the `Python Community Code of +Conduct`_. + + .. _`Mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev .. _`Source code`: https://github.com/pyca/cryptography .. _`Issue tracker`: https://github.com/pyca/cryptography/issues .. _`Documentation`: https://cryptography.io/ +.. _`Python Community Code of Conduct`: http://www.python.org/psf/codeofconduct/ diff --git a/docs/conf.py b/docs/conf.py index 8e0fc7be..69be32e9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -252,7 +252,3 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} - - -# Enable the new ReadTheDocs theme -RTD_NEW_THEME = True diff --git a/docs/exceptions.rst b/docs/exceptions.rst new file mode 100644 index 00000000..6ac11b3c --- /dev/null +++ b/docs/exceptions.rst @@ -0,0 +1,9 @@ +Exceptions +========== + +.. currentmodule:: cryptography.exceptions + +.. 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 new file mode 100644 index 00000000..e4fc8283 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,30 @@ +Glossary +======== + +.. glossary:: + + plaintext + User-readable data you care about. + + ciphertext + The encoded data, it's not user readable. Potential attackers are able + to see this. + + encryption + The process of converting plaintext to ciphertext. + + decryption + The process of converting ciphertext to plaintext. + + key + Secret data is encoded with a function using this key. Sometimes + multiple keys are used. These **must** be kept secret, if a key is + exposed to an attacker, any data encrypted with it will be exposed. + + symmetric cryptography + Cryptographic operations where encryption and decryption use the same + key. + + asymmetric cryptography + Cryptographic operations where encryption and decryption use different + keys. There are seperate encryption and decryption keys. diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index c780dcb0..76ca20c0 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -5,21 +5,27 @@ Message Digests .. currentmodule:: cryptography.hazmat.primitives.hashes -.. class:: BaseHash(data=None) +.. class:: Hash(algorithm) - Abstract base class that implements a common interface for all hash - algorithms that follow here. + A cryptographic hash function takes an arbitrary block of data and + calculates a fixed-size bit string (a digest), such that different data + results (with a high probability) in different digests. - If ``data`` is provided ``update(data)`` is called upon construction. + This is an implementation of + :class:`cryptography.hazmat.primitives.interfaces.HashContext` meant to + be used with + :class:`cryptography.hazmat.primitives.interfaces.HashAlgorithm` + implementations to provide an incremental interface to calculating + various message digests. .. doctest:: >>> from cryptography.hazmat.primitives import hashes - >>> digest = hashes.SHA256() + >>> digest = hashes.Hash(hashes.SHA256()) >>> digest.update(b"abc") >>> digest.update(b"123") - >>> digest.hexdigest() - '6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090' + >>> 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' .. method:: update(data) @@ -29,13 +35,14 @@ Message Digests :return: a new instance of this object with a copied internal state. - .. method:: digest() + .. method:: finalize() - :return bytes: The message digest as bytes. + Finalize the current context and return the message digest as bytes. + + Once ``finalize`` is called this object can no longer be used. - .. method:: hexdigest() + :return bytes: The message digest as bytes. - :return str: The message digest as hex. SHA-1 ~~~~~ diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 44cc29fa..bd1a4934 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -15,21 +15,23 @@ 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, msg=None, digestmod=None) +.. class:: HMAC(key, algorithm) - HMAC objects take a ``key``, a hash class derived from - :class:`~cryptography.primitives.hashes.BaseHash`, and optional message. + HMAC objects take a ``key`` and a provider of + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. The ``key`` should be randomly generated bytes and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. + This is an implementation of :rfc:`2104`. + .. doctest:: >>> from cryptography.hazmat.primitives import hashes, hmac - >>> h = hmac.HMAC(key, digestmod=hashes.SHA256) + >>> h = hmac.HMAC(key, hashes.SHA256()) >>> h.update(b"message to hash") - >>> h.hexdigest() - '...' + >>> h.finalize() + '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' .. method:: update(msg) @@ -39,11 +41,10 @@ message. :return: a new instance of this object with a copied internal state. - .. method:: digest() - - :return bytes: The message digest as bytes. + .. method:: finalize() - .. method:: hexdigest() + Finalize the current context and return the message digest as bytes. - :return str: The message digest as hex. + Once ``finalize`` is called this object can no longer be used. + :return bytes: The message digest as bytes. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5852dc21..c1c8d247 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -42,12 +42,21 @@ where the encrypter and decrypter both use the same key. :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. + .. method:: decryptor() :return: A decrypting :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. + + .. currentmodule:: cryptography.hazmat.primitives.interfaces .. class:: CipherContext @@ -63,6 +72,12 @@ 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. + When the ``BlockCipher`` was constructed in a mode turns it into a + stream cipher (e.g. + :class:`cryptography.hazmat.primitives.block.modes.CTR`), this will + return bytes immediately, however in other modes it will return chunks, + whose size is determined by the cipher's block size. + .. method:: finalize() :return bytes: Returns the remainder of the data. @@ -162,7 +177,8 @@ Modes block size of less than 128-bits. CTR (Counter) is a mode of operation for block ciphers. It is considered - cryptographically strong. + cryptographically strong. It transforms a block cipher into a stream + cipher. :param bytes nonce: Should be random bytes. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce diff --git a/docs/index.rst b/docs/index.rst index 4fd5d3be..1b88e24e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,6 +31,8 @@ Contents :maxdepth: 2 architecture + exceptions + glossary contributing security community |