crypto_bigint/uint/
sub_mod.rs

1//! [`Uint`] modular subtraction operations.
2
3use crate::{Limb, SubMod, Uint};
4
5impl<const LIMBS: usize> Uint<LIMBS> {
6    /// Computes `self - rhs mod p`.
7    ///
8    /// Assumes `self - rhs` as unbounded signed integer is in `[-p, p)`.
9    pub const fn sub_mod(&self, rhs: &Self, p: &Self) -> Self {
10        let (out, mask) = self.sbb(rhs, Limb::ZERO);
11
12        // If underflow occurred on the final limb, borrow = 0xfff...fff, otherwise
13        // borrow = 0x000...000. Thus, we use it as a mask to conditionally add the modulus.
14        out.wrapping_add(&p.bitand_limb(mask))
15    }
16
17    /// Returns `(self..., carry) - (rhs...) mod (p...)`, where `carry <= 1`.
18    /// Assumes `-(p...) <= (self..., carry) - (rhs...) < (p...)`.
19    #[inline(always)]
20    pub(crate) const fn sub_mod_with_carry(&self, carry: Limb, rhs: &Self, p: &Self) -> Self {
21        debug_assert!(carry.0 <= 1);
22
23        let (out, borrow) = self.sbb(rhs, Limb::ZERO);
24
25        // The new `borrow = Word::MAX` iff `carry == 0` and `borrow == Word::MAX`.
26        let mask = carry.wrapping_neg().not().bitand(borrow);
27
28        // If underflow occurred on the final limb, borrow = 0xfff...fff, otherwise
29        // borrow = 0x000...000. Thus, we use it as a mask to conditionally add the modulus.
30        out.wrapping_add(&p.bitand_limb(mask))
31    }
32
33    /// Computes `self - rhs mod p` for the special modulus
34    /// `p = MAX+1-c` where `c` is small enough to fit in a single [`Limb`].
35    ///
36    /// Assumes `self - rhs` as unbounded signed integer is in `[-p, p)`.
37    pub const fn sub_mod_special(&self, rhs: &Self, c: Limb) -> Self {
38        let (out, borrow) = self.sbb(rhs, Limb::ZERO);
39
40        // If underflow occurred, then we need to subtract `c` to account for
41        // the underflow. This cannot underflow due to the assumption
42        // `self - rhs >= -p`.
43        let l = borrow.0 & c.0;
44        out.wrapping_sub(&Self::from_word(l))
45    }
46}
47
48impl<const LIMBS: usize> SubMod for Uint<LIMBS> {
49    type Output = Self;
50
51    fn sub_mod(&self, rhs: &Self, p: &Self) -> Self {
52        debug_assert!(self < p);
53        debug_assert!(rhs < p);
54        self.sub_mod(rhs, p)
55    }
56}
57
58#[cfg(all(test, feature = "rand"))]
59mod tests {
60    use crate::{Limb, NonZero, Random, RandomMod, Uint, U256};
61    use rand_core::SeedableRng;
62
63    #[test]
64    fn sub_mod_nist_p256() {
65        let a =
66            U256::from_be_hex("1a2472fde50286541d97ca6a3592dd75beb9c9646e40c511b82496cfc3926956");
67        let b =
68            U256::from_be_hex("d5777c45019673125ad240f83094d4252d829516fac8601ed01979ec1ec1a251");
69        let n =
70            U256::from_be_hex("ffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
71
72        let actual = a.sub_mod(&b, &n);
73        let expected =
74            U256::from_be_hex("44acf6b7e36c1342c2c5897204fe09504e1e2efb1a900377dbc4e7a6a133ec56");
75
76        assert_eq!(expected, actual);
77    }
78
79    macro_rules! test_sub_mod {
80        ($size:expr, $test_name:ident) => {
81            #[test]
82            fn $test_name() {
83                let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(1);
84                let moduli = [
85                    NonZero::<Uint<$size>>::random(&mut rng),
86                    NonZero::<Uint<$size>>::random(&mut rng),
87                ];
88
89                for p in &moduli {
90                    let base_cases = [
91                        (1u64, 0u64, 1u64.into()),
92                        (0, 1, p.wrapping_sub(&1u64.into())),
93                        (0, 0, 0u64.into()),
94                    ];
95                    for (a, b, c) in &base_cases {
96                        let a: Uint<$size> = (*a).into();
97                        let b: Uint<$size> = (*b).into();
98
99                        let x = a.sub_mod(&b, p);
100                        assert_eq!(*c, x, "{} - {} mod {} = {} != {}", a, b, p, x, c);
101                    }
102
103                    if $size > 1 {
104                        for _i in 0..100 {
105                            let a: Uint<$size> = Limb::random(&mut rng).into();
106                            let b: Uint<$size> = Limb::random(&mut rng).into();
107                            let (a, b) = if a < b { (b, a) } else { (a, b) };
108
109                            let c = a.sub_mod(&b, p);
110                            assert!(c < **p, "not reduced");
111                            assert_eq!(c, a.wrapping_sub(&b), "result incorrect");
112                        }
113                    }
114
115                    for _i in 0..100 {
116                        let a = Uint::<$size>::random_mod(&mut rng, p);
117                        let b = Uint::<$size>::random_mod(&mut rng, p);
118
119                        let c = a.sub_mod(&b, p);
120                        assert!(c < **p, "not reduced: {} >= {} ", c, p);
121
122                        let x = a.wrapping_sub(&b);
123                        if a >= b && x < **p {
124                            assert_eq!(c, x, "incorrect result");
125                        }
126                    }
127                }
128            }
129        };
130    }
131
132    macro_rules! test_sub_mod_special {
133        ($size:expr, $test_name:ident) => {
134            #[test]
135            fn $test_name() {
136                let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(1);
137                let moduli = [
138                    NonZero::<Limb>::random(&mut rng),
139                    NonZero::<Limb>::random(&mut rng),
140                ];
141
142                for special in &moduli {
143                    let p =
144                        &NonZero::new(Uint::ZERO.wrapping_sub(&Uint::from(special.get()))).unwrap();
145
146                    let minus_one = p.wrapping_sub(&Uint::ONE);
147
148                    let base_cases = [
149                        (Uint::ZERO, Uint::ZERO, Uint::ZERO),
150                        (Uint::ONE, Uint::ZERO, Uint::ONE),
151                        (Uint::ZERO, Uint::ONE, minus_one),
152                        (minus_one, minus_one, Uint::ZERO),
153                        (Uint::ZERO, minus_one, Uint::ONE),
154                    ];
155                    for (a, b, c) in &base_cases {
156                        let x = a.sub_mod_special(&b, *special.as_ref());
157                        assert_eq!(*c, x, "{} - {} mod {} = {} != {}", a, b, p, x, c);
158                    }
159
160                    for _i in 0..100 {
161                        let a = Uint::<$size>::random_mod(&mut rng, p);
162                        let b = Uint::<$size>::random_mod(&mut rng, p);
163
164                        let c = a.sub_mod_special(&b, *special.as_ref());
165                        assert!(c < **p, "not reduced: {} >= {} ", c, p);
166
167                        let expected = a.sub_mod(&b, p);
168                        assert_eq!(c, expected, "incorrect result");
169                    }
170                }
171            }
172        };
173    }
174
175    // Test requires 1-limb is capable of representing a 64-bit integer
176    #[cfg(target_pointer_width = "64")]
177    test_sub_mod!(1, sub1);
178
179    test_sub_mod!(2, sub2);
180    test_sub_mod!(3, sub3);
181    test_sub_mod!(4, sub4);
182    test_sub_mod!(5, sub5);
183    test_sub_mod!(6, sub6);
184    test_sub_mod!(7, sub7);
185    test_sub_mod!(8, sub8);
186    test_sub_mod!(9, sub9);
187    test_sub_mod!(10, sub10);
188    test_sub_mod!(11, sub11);
189    test_sub_mod!(12, sub12);
190
191    test_sub_mod_special!(1, sub_mod_special_1);
192    test_sub_mod_special!(2, sub_mod_special_2);
193    test_sub_mod_special!(3, sub_mod_special_3);
194    test_sub_mod_special!(4, sub_mod_special_4);
195    test_sub_mod_special!(5, sub_mod_special_5);
196    test_sub_mod_special!(6, sub_mod_special_6);
197    test_sub_mod_special!(7, sub_mod_special_7);
198    test_sub_mod_special!(8, sub_mod_special_8);
199    test_sub_mod_special!(9, sub_mod_special_9);
200    test_sub_mod_special!(10, sub_mod_special_10);
201    test_sub_mod_special!(11, sub_mod_special_11);
202    test_sub_mod_special!(12, sub_mod_special_12);
203}
crypto_bigint/uint/sub_mod.rs

crypto_bigint/uint/
sub_mod.rs
