ctutils/
lib.rs

1#![no_std]
2#![doc = include_str!("../README.md")]
3#![doc(
4    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
5    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg"
6)]
7#![forbid(unsafe_code)] // `unsafe` should go in `cmov`
8#![warn(
9    clippy::borrow_as_ptr,
10    clippy::cast_lossless,
11    clippy::cast_possible_truncation,
12    clippy::cast_precision_loss,
13    clippy::checked_conversions,
14    clippy::implicit_saturating_sub,
15    clippy::integer_division_remainder_used,
16    clippy::must_use_candidate,
17    clippy::mod_module_files,
18    clippy::panic,
19    clippy::panic_in_result_fn,
20    clippy::ref_as_ptr,
21    clippy::semicolon_if_nothing_returned,
22    clippy::std_instead_of_alloc,
23    clippy::std_instead_of_core,
24    clippy::undocumented_unsafe_blocks,
25    clippy::unnecessary_safety_comment,
26    clippy::unwrap_in_result,
27    missing_copy_implementations,
28    missing_debug_implementations,
29    missing_docs,
30    rust_2018_idioms,
31    trivial_casts,
32    trivial_numeric_casts,
33    unused_lifetimes,
34    unused_qualifications
35)]
36#![cfg_attr(not(test), warn(clippy::unwrap_used))]
37
38//! # API Design
39//!
40//! ## [`Choice`]: constant-time analogue for [`bool`]
41//! Values of this type are one of either [`Choice::FALSE`] or [`Choice::TRUE`].
42//!
43//! To achieve constant-time operation, `Choice` is ultimately used in combination with special
44//! CPU-specific constant-time predication instructions implemented by the [`cmov`] crate
45//! (with a portable "best effort" fallback that cannot provide guarantees).
46//!
47//! It additionally uses various methods to hint to the compiler that it should avoid inserting
48//! branches based on its value where it otherwise would if `bool` were used instead, but cannot
49//! provide guarantees in this regard.
50//!
51//! ## [`CtOption`]: constant-time analogue for [`Option`]
52//! The core `Option` type is typically great for representing the conditional absence or presence
53//! of a value, and provides a number of handy combinators for operating on them.
54//!
55//! However, it has a rather fundamental flaw when constant-time is desirable: its combinators are
56//! lazily evaluated. To ensure constant-time operation, all combinators must be eagerly evaluated
57//! so they aren't conditionally executed based on the value's presence.
58//!
59//! `CtOption` instead carries a `Choice` along with a value, which makes it possible to do
60//! something it isn't with `Option`: evaluate combinators eagerly instead of lazily, running the
61//! same functions regardless of the value's effective presence or absence.
62//!
63//! ## [`CtAssign`]: constant-time additional assignment using [predication]
64//! Support for conditionally assigning to a type or slices thereof (for types which impl the
65//! [`CtAssignSlice`] trait) based on a provided condition value.
66//!
67//! Uses predication instructions or a portable simulation thereof to perform constant-time
68//! conditional assignment based ona  [`Choice`].
69//!
70//! *NOTE: for `subtle` users, this trait provides the equivalent of the
71//! `ConditionallySelectable::conditional_assign` method, but as its own trait without a `Sized`
72//! bound so it can also be impl'd for slices*
73//!
74//! ## [`CtEq`]: constant-time analogue for [`PartialEq`]/[`Eq`]
75//! Equality testing often short circuits for performance reasons, but when comparing values in
76//! constant-time such short-circuiting is forbidden.
77//!
78//! The `CtEq` trait is a replacement for these scenarios. It's impl'd for several core types
79//! including unsigned and signed integers as well as slices and arrays. It returns a `Choice`
80//! as opposed to a `bool`], following the standard practice in this crate.
81//!
82//! *NOTE: for `subtle` users, this is the equivalent of the `ConstantTimeEq` trait*
83//!
84//! ## [`CtSelect`]: constant-time [predication]
85//! Predication in computer architecture describes methods for conditionally modifying state
86//! using non-branch instructions which perform conditional modifications based on a *predicate*
87//! or boolean value, in the design of this library a `Choice`.
88//!
89//! The `CtSelect` trait provides methods for performing conditional selection between two
90//! different inputs and returning a new one.
91//!
92//! *NOTE: for `subtle` users, this is the equivalent of the `ConditionallySelectable` trait*
93//!
94//! [predication]: https://en.wikipedia.org/wiki/Predication_(computer_architecture)
95//!
96//! # [`subtle`] interop
97//!
98//! When the `subtle` feature of this crate is enabled, bidirectional [`From`] impls are available
99//! for the following types:
100//!
101//! - [`Choice`] <=> [`subtle::Choice`]
102//! - [`CtOption`] <=> [`subtle::CtOption`]
103//!
104//! This makes it possible to use `ctutils` in a codebase where other dependencies are using
105//! `subtle`.
106
107#[cfg(feature = "alloc")]
108extern crate alloc;
109
110mod choice;
111mod ct_option;
112mod traits;
113
114pub use choice::Choice;
115pub use ct_option::CtOption;
116pub use traits::{
117    ct_assign::{CtAssign, CtAssignSlice},
118    ct_eq::{CtEq, CtEqSlice},
119    ct_find::CtFind,
120    ct_gt::CtGt,
121    ct_lookup::CtLookup,
122    ct_lt::CtLt,
123    ct_neg::CtNeg,
124    ct_select::{CtSelect, CtSelectArray, CtSelectUsingCtAssign},
125};
ctutils/lib.rs

ctutils/
lib.rs
