Some simplifications of vartime division

[fjarri]

• Extract shl/shr by a limb-sized shift into separate methods
• Add a more detailed docstring and some debug assertions in div3by2()
• Replaced saturating_sub with wrapping_sub in several places. While logically it is the same thing (the wrapping/saturation only happens for values that are later selected out), I think there are readability advantages. First, elsewhere in the code we use wrapping ops for selected out values (meaning "perform the subtraction without any checks, since we already have a constant-time condition for that"), so saturating_sub indicates that the algorithm actually uses the saturation mechanic. Second, in case of a bug, it will be easier to spot the consequences of a "0xffff..." value than a 0.

Questions:

• should I move the new shl/shr methods to shl.rs/shr.rs? Are they general enough?
• should div3by2_vartime() be moved out of div_limb.rs?

[andrewwhitehead]

I'm also worried about the runtime of this method depending on the dividend value. Replacing it completely would also mess with my PR #643, do you want to do a quick review of that one?

[fjarri]

The original div3by2() can be preserved, of course, but I am worried about the connection of its contents and the original algorithm Q from the article. Could you add some explanations about why it actually does the same thing?

[andrewwhitehead]

I added a PR to better align that method with the definition, as it doesn't look like overflow was being handled properly in the remainder.

[tarcieri]

@andrewwhitehead can you take a look again now that #643 is merged?

[tarcieri]

It seems like we should probably get #643 merged first since it might affect this.

Edit: merged!

[andrewwhitehead]

The constant-time division does use this remainder

[tarcieri]

Oops, I now see this broke the build: https://github.com/RustCrypto/crypto-bigint/actions/runs/10472862474/job/29003356626

[andrewwhitehead]

Looks good to me.

I think at some point it would make sense to turn functions like shl_limb_vartime into methods on a struct like LimbsMut(&mut [Limb]), which might be a convenient way to collect and document them. Then once there is language support they could be const-ified and used by both Uint and BoxedUint.

[tarcieri]

Going to revert this merge as it broke the build. Edit: opened #658