From d6f14daf49036a434bc0a6b190457694f8703be1 Mon Sep 17 00:00:00 2001 From: Julian Krause Date: Thu, 5 Dec 2013 11:06:27 -0800 Subject: Improve documentation. --- docs/hazmat/primitives/constant-time.rst | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives/constant-time.rst') diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst index 2e8e26d7..4e00e9b9 100644 --- a/docs/hazmat/primitives/constant-time.rst +++ b/docs/hazmat/primitives/constant-time.rst @@ -6,11 +6,17 @@ Constant time functions .. currentmodule:: cryptography.hazmat.primitives.constant_time In order for cryptographic operations to not leak information through timing -side channels, constant time operations need to be made available. +side channels, constant time operations need to be used. + +One should use these functions whenever you are comparing a secret to +something received. This includes things like HMAC signatures as described by +a `timing attack on KeyCzar`_. + .. function:: bytes_eq(a, b) - Compare ``a`` and ``b`` to one another in constant time. + Compare ``a`` and ``b`` to one another in constant time if they are of the + same length. .. doctest:: @@ -20,5 +26,9 @@ side channels, constant time operations need to be made available. >>> constant_time.bytes_eq(b"foo", b"bar") False - :param a: ``bytes``. - :param b: ``bytes``. + :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``. + + +.. _`timing attack on KeyCzar`: http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/ -- cgit v1.2.3