elliptic_curve/hazmat.rs
1//! Hazardous materials (a.k.a. "hazmat"): low-level primitives.
2//!
3//! <div class="warning">
4//! <b>Security️ Warning</b>
5//!
6//! YOU PROBABLY DON'T WANT TO USE THESE!
7//!
8//! If you are an end user / non-expert in cryptography, do not use these!
9//! Failure to use them correctly can lead to catastrophic failures.
10//! </div>
11
12use crate::{
13 CurveArithmetic, FieldBytes, Generate,
14 ops::{BatchInvert, Invert, Retrieve},
15};
16use ff::PrimeField;
17use subtle::CtOption;
18
19/// Access to a curve's base field element type.
20///
21/// This trait is bounded on [`CurveArithmetic`] to provide a complete arithmetic implementation,
22/// and also make the associated `FieldElement` type completely inaccessible unless this trait
23/// is in scope, having been imported from this `hazmat` module so that text appears in the import.
24/// We also explicitly recommend against re-exporting it so the `hazmat` keyword is easy to
25/// search for.
26///
27/// <div class="warning">
28/// <b>Security Warning</b>
29///
30/// Field elements are easily misused, unlike group-based abstractions. Some elliptic curves utilize
31/// lazy normalization, meaning that field elements may be non-canonical leading to miscomputations.
32/// We strongly recommend you avoid using this trait except for use cases that are truly dependent
33/// on coordinates, such as curve point encodings or hash2curve.
34/// </div>
35pub trait FieldArithmetic: CurveArithmetic {
36 /// Base field element type.
37 type FieldElement: BatchInvert
38 + Generate
39 + Invert<Output = CtOption<Self::FieldElement>>
40 + PrimeField<Repr = FieldBytes<Self>>
41 + Retrieve<Output = Self::Uint>;
42}