Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 82 insertions, 0 deletions

diff --git a/third_party/rust/subtle/README.md b/third_party/rust/subtle/README.md
new file mode 100644
index 0000000000..de77575540
--- /dev/null
+++ b/third_party/rust/subtle/README.md
@@ -0,0 +1,82 @@
+# subtle [![](https://img.shields.io/crates/v/subtle.svg)](https://crates.io/crates/subtle) [![](https://img.shields.io/badge/dynamic/json.svg?label=docs&uri=https%3A%2F%2Fcrates.io%2Fapi%2Fv1%2Fcrates%2Fsubtle%2Fversions&query=%24.versions%5B0%5D.num&colorB=4F74A6)](https://doc.dalek.rs/subtle) [![](https://travis-ci.org/dalek-cryptography/subtle.svg?branch=master)](https://travis-ci.org/dalek-cryptography/subtle)
+
+**Pure-Rust traits and utilities for constant-time cryptographic implementations.**
+
+It consists of a `Choice` type, and a collection of traits using `Choice`
+instead of `bool` which are intended to execute in constant-time.  The `Choice`
+type is a wrapper around a `u8` that holds a `0` or `1`.
+
+```toml
+subtle = "2.5"
+```
+
+This crate represents a “best-effort” attempt, since side-channels
+are ultimately a property of a deployed cryptographic system
+including the hardware it runs on, not just of software.
+
+The traits are implemented using bitwise operations, and should execute in
+constant time provided that a) the bitwise operations are constant-time and
+b) the bitwise operations are not recognized as a conditional assignment and
+optimized back into a branch.
+
+For a compiler to recognize that bitwise operations represent a conditional
+assignment, it needs to know that the value used to generate the bitmasks is
+really a boolean `i1` rather than an `i8` byte value. In an attempt to
+prevent this refinement, the crate tries to hide the value of a `Choice`'s
+inner `u8` by passing it through a volatile read. For more information, see
+the _About_ section below.
+
+Rust versions from 1.66 or higher support a new best-effort optimization
+barrier ([`core::hint::black_box`]).  To use the new optimization barrier,
+enable the `core_hint_black_box` feature.
+
+Rust versions from 1.51 or higher have const generics support. You may enable
+`const-generics` feautre to have `subtle` traits implemented for arrays `[T; N]`.
+
+Versions prior to `2.2` recommended use of the `nightly` feature to enable an
+optimization barrier; this is not required in versions `2.2` and above.
+
+Note: the `subtle` crate contains `debug_assert`s to check invariants during
+debug builds. These invariant checks involve secret-dependent branches, and
+are not present when compiled in release mode. This crate is intended to be
+used in release mode.
+
+## Documentation
+
+Documentation is available [here][docs].
+
+## Minimum Supported Rust Version
+
+Rust **1.41** or higher.
+
+Minimum supported Rust version can be changed in the future, but it will be done with a minor version bump.
+
+## About
+
+This library aims to be the Rust equivalent of Go’s `crypto/subtle` module.
+
+Old versions of the optimization barrier in `impl From<u8> for Choice` were
+based on Tim Maclean's [work on `rust-timing-shield`][rust-timing-shield],
+which attempts to provide a more comprehensive approach for preventing
+software side-channels in Rust code.
+
+From version `2.2`, it was based on Diane Hosfelt and Amber Sprenkels' work on
+"Secret Types in Rust".  Version `2.5` adds the `core_hint_black_box` feature,
+which uses the original method through the [`core::hint::black_box`] function
+from the Rust standard library.
+
+`subtle` is authored by isis agora lovecruft and Henry de Valence.
+
+## Warning
+
+This code is a low-level library, intended for specific use-cases implementing
+cryptographic protocols.  It represents a best-effort attempt to protect
+against some software side-channels.  Because side-channel resistance is not a
+property of software alone, but of software together with hardware, any such
+effort is fundamentally limited.
+
+**USE AT YOUR OWN RISK**
+
+[docs]: https://docs.rs/subtle
+[`core::hint::black_box`]: https://doc.rust-lang.org/core/hint/fn.black_box.html
+[rust-timing-shield]: https://www.chosenplaintext.ca/open-source/rust-timing-shield/security