Constant time

Purpose

Whenever you interact with secrets and cryptographic parameters, you should use constant time functions to avoid leaking information via timing to an attacker. Such leaks can completely compromise security.

For example, you should increment counters/nonces, compare tags, compare retyped passwords, and so on using this class.

Usage

Equals

Returns whether two spans are equal in length and contain equal data.

bool equal = ConstantTime.Equals(ReadOnlySpan<byte> a, ReadOnlySpan<byte> b);

Exceptions

ArgumentOutOfRangeException

a.Length is equal to 0.

ArgumentOutOfRangeException

b.Length is equal to 0.

Increment

Increments a span counter in little-endian format.

ConstantTime.Increment(Span<byte> buffer);

Exceptions

ArgumentOutOfRangeException

buffer.Length is equal to 0.

Add

Fills a span with the sum of two spans in little-endian format.

ConstantTime.Add(Span<byte> buffer, ReadOnlySpan<byte> a, ReadOnlySpan<byte> b);

Exceptions

ArgumentOutOfRangeException

buffer.Length is equal to 0.

ArgumentOutOfRangeException

a.Length is equal to 0 or not equal to buffer.Length.

ArgumentOutOfRangeException

b.Length is equal to 0 or not equal to a.Length.

Subtract

Fills a span with the result of subtracting the second span from the first span in little-endian format.

ConstantTime.Subtract(Span<byte> buffer, ReadOnlySpan<byte> a, ReadOnlySpan<byte> b);

Exceptions

ArgumentOutOfRangeException

buffer.Length is equal to 0.

ArgumentOutOfRangeException

a.Length is equal to 0 or not equal to buffer.Length.

ArgumentOutOfRangeException

b.Length is equal to 0 or not equal to a.Length.

IsLessThan

Returns whether the contents of the first span is less than the second span in little-endian format.

bool lessThan = ConstantTime.IsLessThan(ReadOnlySpan<byte> a, ReadOnlySpan<byte> b);

Exceptions

ArgumentOutOfRangeException

a.Length is equal to 0 or not equal to b.Length.

ArgumentOutOfRangeException

b.Length is equal to 0.

IsGreaterThan

Returns whether the contents of the first span is greater than the second span in little-endian format.

bool greaterThan = ConstantTime.IsGreaterThan(ReadOnlySpan<byte> a, ReadOnlySpan<byte> b);

Exceptions

ArgumentOutOfRangeException

a.Length is equal to 0 or not equal to b.Length.

ArgumentOutOfRangeException

b.Length is equal to 0.

IsAllZeros

Returns whether a span only contains zeros.

bool allZeros = ConstantTime.IsAllZeros(ReadOnlySpan<byte> buffer);

Exceptions

ArgumentOutOfRangeException

buffer.Length is equal to 0.

Notes

Tags MUST be compared in constant time using ConstantTime.Equals() to prevent forgery. The VerifyTag() and FinalizeAndVerify() functions do this for you.

These constant time functions can also be used for non-secret values. If in doubt, use constant time.