/rust/registry/src/index.crates.io-1949cf8c6b5b557f/group-0.13.0/src/cofactor.rs

Source
use core::fmt;
use core::ops::{Mul, Neg};
use ff::PrimeField;
use subtle::{Choice, CtOption};

use crate::{prime::PrimeGroup, Curve, Group, GroupEncoding, GroupOps, GroupOpsOwned};

/// This trait represents an element of a cryptographic group with a large prime-order
/// subgroup and a comparatively-small cofactor.
pub trait CofactorGroup:
    Group
    + GroupEncoding
    + GroupOps<<Self as CofactorGroup>::Subgroup>
    + GroupOpsOwned<<Self as CofactorGroup>::Subgroup>
{
    /// The large prime-order subgroup in which cryptographic operations are performed.
    /// If `Self` implements `PrimeGroup`, then `Self::Subgroup` may be `Self`.
    type Subgroup: PrimeGroup<Scalar = Self::Scalar> + Into<Self>;

    /// Maps `self` to the prime-order subgroup by multiplying this element by some
    /// `k`-multiple of the cofactor.
    ///
    /// The value `k` does not vary between inputs for a given implementation, but may
    /// vary between different implementations of `CofactorGroup` because some groups have
    /// more efficient methods of clearing the cofactor when `k` is allowed to be
    /// different than `1`.
    ///
    /// If `Self` implements [`PrimeGroup`], this returns `self`.
    fn clear_cofactor(&self) -> Self::Subgroup;

    /// Returns `self` if it is contained in the prime-order subgroup.
    ///
    /// If `Self` implements [`PrimeGroup`], this returns `Some(self)`.
    fn into_subgroup(self) -> CtOption<Self::Subgroup>;

    /// Determines if this element is of small order.
    ///
    /// Returns:
    /// - `true` if `self` is in the torsion subgroup.
    /// - `false` if `self` is not in the torsion subgroup.
    fn is_small_order(&self) -> Choice {
        self.clear_cofactor().is_identity()
    }

    /// Determines if this element is "torsion free", i.e., is contained in the
    /// prime-order subgroup.
    ///
    /// Returns:
    /// - `true` if `self` has trivial torsion and is in the prime-order subgroup.
    /// - `false` if `self` has non-zero torsion component and is not in the prime-order
    ///   subgroup.
    fn is_torsion_free(&self) -> Choice;
}

/// Efficient representation of an elliptic curve point guaranteed to be
/// in the correct prime order subgroup.
pub trait CofactorCurve:
    Curve<AffineRepr = <Self as CofactorCurve>::Affine> + CofactorGroup
{
    type Affine: CofactorCurveAffine<Curve = Self, Scalar = Self::Scalar>
        + Mul<Self::Scalar, Output = Self>
        + for<'r> Mul<&'r Self::Scalar, Output = Self>;
}

/// Affine representation of an elliptic curve point guaranteed to be
/// in the correct prime order subgroup.
pub trait CofactorCurveAffine:
    GroupEncoding
    + Copy
    + Clone
    + Sized
    + Send
    + Sync
    + fmt::Debug
    + PartialEq
    + Eq
    + 'static
    + Neg<Output = Self>
    + Mul<<Self as CofactorCurveAffine>::Scalar, Output = <Self as CofactorCurveAffine>::Curve>
    + for<'r> Mul<
        &'r <Self as CofactorCurveAffine>::Scalar,
        Output = <Self as CofactorCurveAffine>::Curve,
    >
{
    type Scalar: PrimeField;
    type Curve: CofactorCurve<Affine = Self, Scalar = Self::Scalar>;

    /// Returns the additive identity.
    fn identity() -> Self;

    /// Returns a fixed generator of unknown exponent.
    fn generator() -> Self;

    /// Determines if this point represents the point at infinity; the
    /// additive identity.
    fn is_identity(&self) -> Choice;

    /// Converts this element to its curve representation.
    fn to_curve(&self) -> Self::Curve;
}

Coverage Report

Created: 2026-01-13 06:57

Line	Count	Source
1		use core::fmt;
2		use core::ops::{Mul, Neg};
3		use ff::PrimeField;
4		use subtle::{Choice, CtOption};
5
6		use crate::{prime::PrimeGroup, Curve, Group, GroupEncoding, GroupOps, GroupOpsOwned};
7
8		/// This trait represents an element of a cryptographic group with a large prime-order
9		/// subgroup and a comparatively-small cofactor.
10		pub trait CofactorGroup:
11		Group
12		+ GroupEncoding
13		+ GroupOps<<Self as CofactorGroup>::Subgroup>
14		+ GroupOpsOwned<<Self as CofactorGroup>::Subgroup>
15		{
16		/// The large prime-order subgroup in which cryptographic operations are performed.
17		/// If `Self` implements `PrimeGroup`, then `Self::Subgroup` may be `Self`.
18		type Subgroup: PrimeGroup<Scalar = Self::Scalar> + Into<Self>;
19
20		/// Maps `self` to the prime-order subgroup by multiplying this element by some
21		/// `k`-multiple of the cofactor.
22		///
23		/// The value `k` does not vary between inputs for a given implementation, but may
24		/// vary between different implementations of `CofactorGroup` because some groups have
25		/// more efficient methods of clearing the cofactor when `k` is allowed to be
26		/// different than `1`.
27		///
28		/// If `Self` implements [`PrimeGroup`], this returns `self`.
29		fn clear_cofactor(&self) -> Self::Subgroup;
30
31		/// Returns `self` if it is contained in the prime-order subgroup.
32		///
33		/// If `Self` implements [`PrimeGroup`], this returns `Some(self)`.
34		fn into_subgroup(self) -> CtOption<Self::Subgroup>;
35
36		/// Determines if this element is of small order.
37		///
38		/// Returns:
39		/// - `true` if `self` is in the torsion subgroup.
40		/// - `false` if `self` is not in the torsion subgroup.
41	0	fn is_small_order(&self) -> Choice {
42	0	self.clear_cofactor().is_identity()
43	0	}
44
45		/// Determines if this element is "torsion free", i.e., is contained in the
46		/// prime-order subgroup.
47		///
48		/// Returns:
49		/// - `true` if `self` has trivial torsion and is in the prime-order subgroup.
50		/// - `false` if `self` has non-zero torsion component and is not in the prime-order
51		/// subgroup.
52		fn is_torsion_free(&self) -> Choice;
53		}
54
55		/// Efficient representation of an elliptic curve point guaranteed to be
56		/// in the correct prime order subgroup.
57		pub trait CofactorCurve:
58		Curve<AffineRepr = <Self as CofactorCurve>::Affine> + CofactorGroup
59		{
60		type Affine: CofactorCurveAffine<Curve = Self, Scalar = Self::Scalar>
61		+ Mul<Self::Scalar, Output = Self>
62		+ for<'r> Mul<&'r Self::Scalar, Output = Self>;
63		}
64
65		/// Affine representation of an elliptic curve point guaranteed to be
66		/// in the correct prime order subgroup.
67		pub trait CofactorCurveAffine:
68		GroupEncoding
69		+ Copy
70		+ Clone
71		+ Sized
72		+ Send
73		+ Sync
74		+ fmt::Debug
75		+ PartialEq
76		+ Eq
77		+ 'static
78		+ Neg<Output = Self>
79		+ Mul<<Self as CofactorCurveAffine>::Scalar, Output = <Self as CofactorCurveAffine>::Curve>
80		+ for<'r> Mul<
81		&'r <Self as CofactorCurveAffine>::Scalar,
82		Output = <Self as CofactorCurveAffine>::Curve,
83		>
84		{
85		type Scalar: PrimeField;
86		type Curve: CofactorCurve<Affine = Self, Scalar = Self::Scalar>;
87
88		/// Returns the additive identity.
89		fn identity() -> Self;
90
91		/// Returns a fixed generator of unknown exponent.
92		fn generator() -> Self;
93
94		/// Determines if this point represents the point at infinity; the
95		/// additive identity.
96		fn is_identity(&self) -> Choice;
97
98		/// Converts this element to its curve representation.
99		fn to_curve(&self) -> Self::Curve;
100		}