Crate ctutils 

RustCrypto: Constant-Time Utilities

Constant-time utility library with selection and equality testing support targeting cryptographic applications. Supports const fn where appropriate. Built on the cmov crate which provides architecture-specific predication intrinsics. Heavily inspired by the subtle crate.

About

This crate contains constant-time equivalents of the bool and Option types (Choice and CtOption respectively), along with traits that can be used in combination with them.

The CtOption type notably provides eagerly evaluated combinator methods (as opposed to the lazily evaluated combinators on Option) which make it possible to write constant-time code using an idiomatic Rust style.

This is an experimental next-generation constant-time library inspired by subtle, but for now we recommend you continue to stick with subtle. We may attempt to get some of the changes in this library incorporated into subtle for a potential v3.0.

What makes this crate different from subtle?

• Pervasive const fn support
  • Almost all constructors/methods on Choice are const fn
  • Choice can be constructed using various const fn predicates on integer types, enabling writing constant-time const fn logic
  • CtOption supports const fn constructors and *_copied methods to access the inner value when it’s a Copy type
  • Macros to act as CtOption pseudo-combinators: map! and unwrap_or!
  • Expanded selection of CtOption combinators that more closely mirrors std::option::Option
• Guaranteed constant-time equality testing and conditional selection on x86(_64) and aarch64 using asm! implementations in the cmov crate which call special constant-time CPU instructions with a portable “best effort” fallback on other platforms using bitwise arithmetic and black_box
• No Copy (or even Clone) bounds, which means all functionality can work with heap-allocated types in addition to stack-allocated

Many features of this crate are extractions from the crypto-bigint crate, where we implement all core logic as const fn and needed solutions for implementing constant-time code despite the unique constraints it imposes.

⚠️ Security Warning

The implementation contained in this crate has never been independently audited!

USE AT YOUR OWN RISK!

Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

API Design

Choice: constant-time analogue for bool

Values of this type are one of either Choice::FALSE or Choice::TRUE.

To achieve constant-time operation, Choice is ultimately used in combination with special CPU-specific constant-time predication instructions implemented by the cmov crate (with a portable “best effort” fallback that cannot provide guarantees).

It additionally uses various methods to hint to the compiler that it should avoid inserting branches based on its value where it otherwise would if bool were used instead, but cannot provide guarantees in this regard.

CtOption: constant-time analogue for Option

The core Option type is typically great for representing the conditional absence or presence of a value, and provides a number of handy combinators for operating on them.

However, it has a rather fundamental flaw when constant-time is desirable: its combinators are lazily evaluated. To ensure constant-time operation, all combinators must be eagerly evaluated so they aren’t conditionally executed based on the value’s presence.

CtOption instead carries a Choice along with a value, which makes it possible to do something it isn’t with Option: evaluate combinators eagerly instead of lazily, running the same functions regardless of the value’s effective presence or absence.

CtEq: constant-time analogue for PartialEq/Eq

Equality testing often short circuits for performance reasons, but when comparing values in constant-time such short-circuiting is forbidden.

The CtEq trait is a replacement for these scenarios. It’s impl’d for several core types including unsigned and signed integers as well as slices and arrays. It returns a Choice as opposed to a bool], following the standard practice in this crate.

NOTE: for subtle users, this is the equivalent of the ConstantTimeEq trait

CtSelect: constant-time predication

Predication in computer architecture describes methods for conditionally modifying state using non-branch instructions which perform conditional modifications based on a predicate or boolean value, in the design of this library a Choice.

The CtSelect trait provides methods for performing conditional moves, either conditionally modifying a value in-place, or selecting from two different inputs and returning a new one.

NOTE: for subtle users, this is the equivalent of the ConditionallySelectable trait

subtle interop

When the subtle feature of this crate is enabled, bidirectional From impls are available for the following types:

• Choice <=> subtle::Choice
• CtOption <=> subtle::CtOption

This makes it possible to use ctutils in a codebase where other dependencies are using subtle.

Macros

map

Helper macro for providing behavior like the CtOption::map combinator that works in const fn contexts.

unwrap_or

Helper macro for providing behavior like the CtOption::unwrap_or combinator that works in const fn contexts.

Structs

Choice

Constant-time analogue of bool providing a “best effort” optimization barrier.

CtOption

Equivalent of Option but predicated on a Choice with combinators that allow for constant-time operations which always perform the same sequence of instructions regardless of the value of is_some.

Traits

CtEq

Constant-time equality: like (Partial)Eq with Choice instead of bool.

CtGt

Constant time greater than.

CtLt

Constant time less than.

CtNeg

Constant-time conditional negation: negates a value when choice is Choice::TRUE.

CtSelect

Constant-time selection: pick between two values based on a given Choice.