docs/hazmat/primitives/constant-time.rst

.. 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/