diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/constant-time.rst | 38 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 |
3 files changed, 39 insertions, 1 deletions
diff --git a/docs/conf.py b/docs/conf.py index 77050e72..5092e4d3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -257,6 +257,5 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst new file mode 100644 index 00000000..632e7c68 --- /dev/null +++ b/docs/hazmat/primitives/constant-time.rst @@ -0,0 +1,38 @@ +.. hazmat:: + +Constant time functions +======================= + +.. currentmodule:: cryptography.hazmat.primitives.constant_time + +This module contains functions for operating with secret data in a way that +does not leak information about that data through how long it takes to perform +the operation. These functions should be used whenever operating on secret data +along with data that is user supplied. + +An example would be comparing a HMAC signature received from a client to the +one generated by the server code for authentication purposes. + +For more information about this sort of issue, see `Coda Hale's blog post`_ +about the timing attacks on KeyCzar and Java's ``MessageDigest.isEqual()``. + + +.. function:: bytes_eq(a, b) + + Compare ``a`` and ``b`` to one another in constant time if they are of the + same length. + + .. doctest:: + + >>> from cryptography.hazmat.primitives import constant_time + >>> constant_time.bytes_eq(b"foo", b"foo") + True + >>> constant_time.bytes_eq(b"foo", b"bar") + False + + :param a bytes: The left-hand side. + :param b bytes: The right-hand side. + :returns boolean: True if ``a`` has the same bytes as ``b``. + + +.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/ diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 614c414a..b115fdbc 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -10,4 +10,5 @@ Primitives hmac symmetric-encryption padding + constant-time interfaces |