group/
cofactor.rs

1use subtle::{Choice, CtOption};
2
3use crate::{prime::PrimeGroup, Curve, CurveAffine, Group, GroupEncoding, GroupOps, GroupOpsOwned};
4
5/// This trait represents an element of a cryptographic group with a large prime-order
6/// subgroup and a comparatively-small cofactor.
7pub trait CofactorGroup:
8    Group
9    + GroupEncoding
10    + GroupOps<<Self as CofactorGroup>::Subgroup>
11    + GroupOpsOwned<<Self as CofactorGroup>::Subgroup>
12{
13    /// The large prime-order subgroup in which cryptographic operations are performed.
14    /// If `Self` implements `PrimeGroup`, then `Self::Subgroup` may be `Self`.
15    type Subgroup: PrimeGroup<Scalar = Self::Scalar> + Into<Self>;
16
17    /// Maps `self` to the prime-order subgroup by multiplying this element by some
18    /// `k`-multiple of the cofactor.
19    ///
20    /// The value `k` does not vary between inputs for a given implementation, but may
21    /// vary between different implementations of `CofactorGroup` because some groups have
22    /// more efficient methods of clearing the cofactor when `k` is allowed to be
23    /// different than `1`.
24    ///
25    /// If `Self` implements [`PrimeGroup`], this returns `self`.
26    fn clear_cofactor(&self) -> Self::Subgroup;
27
28    /// Returns `self` if it is contained in the prime-order subgroup.
29    ///
30    /// If `Self` implements [`PrimeGroup`], this returns `Some(self)`.
31    fn into_subgroup(self) -> CtOption<Self::Subgroup>;
32
33    /// Determines if this element is of small order.
34    ///
35    /// Returns:
36    /// - `true` if `self` is in the torsion subgroup.
37    /// - `false` if `self` is not in the torsion subgroup.
38    fn is_small_order(&self) -> Choice {
39        self.clear_cofactor().is_identity()
40    }
41
42    /// Determines if this element is "torsion free", i.e., is contained in the
43    /// prime-order subgroup.
44    ///
45    /// Returns:
46    /// - `true` if `self` has trivial torsion and is in the prime-order subgroup.
47    /// - `false` if `self` has non-zero torsion component and is not in the prime-order
48    ///   subgroup.
49    fn is_torsion_free(&self) -> Choice;
50}
51
52/// Efficient representation of an elliptic curve point guaranteed to be
53/// in the correct prime order subgroup.
54pub trait CofactorCurve: Curve + CofactorGroup {}
55
56/// Affine representation of an elliptic curve point guaranteed to be
57/// in the correct prime order subgroup.
58pub trait CofactorCurveAffine: CurveAffine {}
59
60impl<C: CurveAffine> CofactorCurveAffine for C where C::Curve: CofactorCurve {}
group/cofactor.rs

group/
cofactor.rs
