diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contributing.rst | 20 | ||||
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 13 |
4 files changed, 29 insertions, 9 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index cb9c7283..744f2098 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -53,11 +53,10 @@ API Considerations Most projects' APIs are designed with a philosophy of "make easy things easy, and make hard things possible". One of the perils of writing cryptographic code -is that code that is secure looks just like code that isn't, and produces -results that are also difficult to distinguish. As a result ``cryptography`` -has, as a design philosophy: "make it hard to do insecure things". Here are a -few strategies for API design which should be both followed, and should inspire -other API choices: +is that secure code looks just like insecure code, and its results are almost +always indistinguishable. As a result ``cryptography`` has, as a design +philosophy: "make it hard to do insecure things". Here are a few strategies for +API design which should be both followed, and should inspire other API choices: If it is incorrect to ignore the result of a method, it should raise an exception, and not return a boolean ``True``/``False`` flag. For example, a @@ -77,6 +76,10 @@ whether the signature was valid. if not is_valid: raise InvalidSignature +Every recipe should include a version or algorithmic marker of some sort in its +output in order to allow transparent upgrading of the algorithms in use, as +the algorithms or parameters needed to achieve a given security margin evolve. + APIs at the :doc:`/hazmat/primitives/index` layer should always take an explicit backend, APIs at the recipes layer should automatically use the :func:`~cryptography.hazmat.backends.default_backend`, but optionally allow @@ -163,7 +166,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`) + :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 @@ -206,7 +209,7 @@ automatically, so all you have to do is: $ py.test ... - 4294 passed in 15.24 seconds + 62746 passed in 220.43 seconds This runs the tests with the default Python interpreter. @@ -244,7 +247,8 @@ Use `tox`_ to build the documentation. For example: docs: commands succeeded congratulations :) -The HTML documentation index can now be found at ``docs/_build/html/index.html`` +The HTML documentation index can now be found at +``docs/_build/html/index.html``. .. _`GitHub`: https://github.com/pyca/cryptography diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 90ca198a..38347378 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -28,6 +28,9 @@ 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' + If the backend doesn't support the requested ``algorithm`` an + :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + 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 diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0c0d0220..0547b7d2 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -34,6 +34,8 @@ 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' + If the backend doesn't support the requested ``algorithm`` an + :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. :param key: Secret key as ``bytes``. :param algorithm: A diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f4d0457a..30896a05 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -61,7 +61,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. .. method:: decryptor() @@ -352,6 +352,16 @@ Modes Do not reuse an ``initialization_vector`` with a given ``key``. + .. note:: + + Cryptography will emit a 128-bit tag when finalizing encryption. + You can shorten a tag by truncating it to the desired length, but this + is **not recommended** as it lowers the security margins of the + authentication (`NIST SP-800-38D`_ recommends 96-bits or greater). + If you must shorten the tag the minimum allowed length is 4 bytes + (32-bits). Applications **must** verify the tag is the expected length + to guarantee the expected security margin. + :param bytes tag: The tag bytes to verify during decryption. When encrypting this must be None. @@ -390,3 +400,4 @@ Insecure Modes .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html .. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf +.. _`NIST SP-800-38D`: http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf |