use num_bigint::BigUint;
use num_traits::{One, Zero};
use rand::rand_core::UnwrapErr;
use rand::{rngs::StdRng, rngs::SysRng, Rng, SeedableRng};
use thiserror::Error;
#[derive(Debug, Error)]
#[error("DHpkcs3EngineError: {0}")]
pub(crate) struct DhPkcs3EngineError(pub String);
#[derive(Debug, Clone)]
pub(crate) struct DhParameterSpec {
p: BigUint,
g: BigUint,
length: u32,
q: Option<BigUint>,
}
impl DhParameterSpec {
pub fn new(p: BigUint, g: BigUint, length: u32) -> Self {
Self {
p,
g,
length,
q: None,
}
}
pub fn with_subgroup_order(mut self, q: BigUint) -> Self {
self.q = Some(q);
self
}
pub fn q(&self) -> Option<&BigUint> {
self.q.as_ref()
}
pub fn length(&self) -> u32 {
self.length
}
pub fn g(&self) -> &BigUint {
&self.g
}
pub fn p(&self) -> &BigUint {
&self.p
}
}
impl std::fmt::Display for DhParameterSpec {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"DhParameterSpec; p: {:?}, g: {:?}, length: {}",
self.p.to_bytes_be(),
self.g.to_bytes_be(),
self.length,
)
}
}
#[derive(Debug, Clone)]
pub(crate) struct DHpkcs3Engine {
parameter_spec: DhParameterSpec,
public_key: BigUint,
private_key: BigUint,
}
impl DHpkcs3Engine {
#[cfg(test)]
pub fn from_private(
private_key: BigUint,
parameter_spec: DhParameterSpec,
) -> Result<Self, DhPkcs3EngineError> {
Self::new(parameter_spec, Some(private_key), None)
}
pub fn new(
parameter_spec: DhParameterSpec,
private_key: Option<BigUint>,
seed: Option<u64>,
) -> Result<Self, DhPkcs3EngineError> {
let priv_key = match private_key {
Some(p) => p,
None => Self::generate_private_key(¶meter_spec, seed)?,
};
if priv_key.is_zero() {
return Err(DhPkcs3EngineError(
"Private key must not be zero".to_string(),
));
}
let group_order;
let upper: &BigUint = match parameter_spec.q() {
Some(q) => q,
None => {
group_order = parameter_spec.p() - BigUint::one();
&group_order
}
};
if &priv_key >= upper {
return Err(DhPkcs3EngineError(format!(
"Private key must be less than the {} order",
if parameter_spec.q().is_some() {
"subgroup"
} else {
"group"
}
)));
}
let pub_key = Self::generate_public_key(&priv_key, ¶meter_spec);
Ok(Self {
parameter_spec,
public_key: pub_key,
private_key: priv_key,
})
}
pub fn public_key(&self) -> &BigUint {
&self.public_key
}
#[cfg(test)]
pub fn private_key(&self) -> &BigUint {
&self.private_key
}
fn validate_peer_public_key(&self, y: &BigUint) -> Result<(), DhPkcs3EngineError> {
let p = self.parameter_spec.p();
let two = BigUint::from(2u32);
if p < &two {
return Err(DhPkcs3EngineError(
"Invalid DH modulus p (must be >= 2)".to_string(),
));
}
let upper = p - &two; if y < &two || y > &upper {
return Err(DhPkcs3EngineError(
"Peer DH public key out of range; require 2 <= y <= p-2".to_string(),
));
}
if let Some(q) = self.parameter_spec.q() {
if y.modpow(q, p) != BigUint::one() {
return Err(DhPkcs3EngineError(
"Peer DH public key fails small-subgroup check (y^q mod p != 1)".to_string(),
));
}
}
Ok(())
}
pub fn compute_secret_key(
&self,
other_public_key: &BigUint,
) -> Result<BigUint, DhPkcs3EngineError> {
self.validate_peer_public_key(other_public_key)?;
Ok(other_public_key.modpow(&self.private_key, self.parameter_spec.p()))
}
pub fn compute_generator(
&self,
other_public_key: &BigUint,
nonce: &BigUint,
) -> Result<BigUint, DhPkcs3EngineError> {
let h = self.compute_secret_key(other_public_key)?;
let g_exp = self
.parameter_spec
.g()
.modpow(nonce, self.parameter_spec.p());
let g_prime = (g_exp * h) % self.parameter_spec.p();
let p = self.parameter_spec.p();
let two = BigUint::from(2u32);
if g_prime < two || g_prime > p - &two {
return Err(DhPkcs3EngineError(
"Mapped generator is degenerate (outside [2, p-2])".to_string(),
));
}
Ok(g_prime)
}
fn generate_private_key(
spec: &DhParameterSpec,
seed: Option<u64>,
) -> Result<BigUint, DhPkcs3EngineError> {
if let Some(q) = spec.q() {
if q <= &BigUint::one() {
return Err(DhPkcs3EngineError(format!(
"Invalid subgroup order q - must be greater than 1, got {q}"
)));
}
let keep_bits = q.bits();
let byte_len = (keep_bits as usize).div_ceil(8);
let upper = q.clone();
let lower = BigUint::one();
let mut bytes = vec![0u8; byte_len.max(1)];
return Ok(match seed {
Some(s) => Self::draw_in_range(
&mut StdRng::seed_from_u64(s),
&mut bytes,
&lower,
&upper,
keep_bits,
),
None => Self::draw_in_range(
&mut UnwrapErr(SysRng),
&mut bytes,
&lower,
&upper,
keep_bits,
),
});
}
let length = spec.length;
if length == 0 || !length.is_multiple_of(8) {
return Err(DhPkcs3EngineError(format!(
"Invalid bitLength value - {length}"
)));
}
let byte_len = (length / 8) as usize;
let lower = BigUint::one() << (length - 1);
let upper = (BigUint::one() << length).min(spec.p() - BigUint::one());
if upper <= lower {
return Err(DhPkcs3EngineError(format!(
"No valid private-key range: 2^(length-1) ({lower}) >= min(2^length, p-1) ({upper})"
)));
}
let mut bytes = vec![0u8; byte_len];
let keep_bits = length as u64;
match seed {
Some(s) => {
let mut rng = StdRng::seed_from_u64(s);
Ok(Self::draw_in_range(
&mut rng, &mut bytes, &lower, &upper, keep_bits,
))
}
None => {
let mut rng = UnwrapErr(SysRng);
Ok(Self::draw_in_range(
&mut rng, &mut bytes, &lower, &upper, keep_bits,
))
}
}
}
fn draw_in_range<R: Rng>(
rng: &mut R,
buf: &mut [u8],
lower: &BigUint,
upper: &BigUint,
keep_bits: u64,
) -> BigUint {
let excess = (buf.len() as u64 * 8).saturating_sub(keep_bits);
loop {
rng.fill_bytes(buf);
if excess > 0 {
if let Some(first) = buf.first_mut() {
*first &= 0xFFu8 >> excess;
}
}
let n = BigUint::from_bytes_be(buf);
if &n >= lower && &n < upper {
return n;
}
}
}
fn generate_public_key(private_key: &BigUint, spec: &DhParameterSpec) -> BigUint {
spec.g().modpow(private_key, spec.p())
}
}
#[cfg(test)]
mod tests {
use super::*;
fn small_spec() -> DhParameterSpec {
DhParameterSpec::new(BigUint::from(23u32), BigUint::from(5u32), 8)
}
#[test]
fn key_pair_roundtrip_with_fixed_private() {
let spec = small_spec();
let engine = DHpkcs3Engine::from_private(BigUint::from(6u32), spec.clone()).unwrap();
assert_eq!(engine.public_key(), &BigUint::from(8u32));
assert_eq!(engine.private_key(), &BigUint::from(6u32));
}
#[test]
fn shared_secret_symmetric() {
let spec = small_spec();
let alice = DHpkcs3Engine::from_private(BigUint::from(6u32), spec.clone()).unwrap();
let bob = DHpkcs3Engine::from_private(BigUint::from(15u32), spec).unwrap();
let s_ab = alice.compute_secret_key(bob.public_key()).unwrap();
let s_ba = bob.compute_secret_key(alice.public_key()).unwrap();
assert_eq!(s_ab, s_ba);
}
#[test]
fn compute_generator_matches_definition() {
let spec = small_spec();
let nonce = BigUint::from(3u32);
let alice = DHpkcs3Engine::from_private(BigUint::from(6u32), spec.clone()).unwrap();
let bob = DHpkcs3Engine::from_private(BigUint::from(15u32), spec.clone()).unwrap();
let h = alice.compute_secret_key(bob.public_key()).unwrap();
let g_exp = spec.g().modpow(&nonce, spec.p());
let expected = (&g_exp * &h) % spec.p();
let got = alice.compute_generator(bob.public_key(), &nonce).unwrap();
assert_eq!(got, expected);
}
#[test]
fn seeded_private_key_is_deterministic() {
let spec = DhParameterSpec::new(BigUint::from(23u32), BigUint::from(5u32), 8)
.with_subgroup_order(BigUint::from(11u32));
let a = DHpkcs3Engine::new(spec.clone(), None, Some(42)).unwrap();
let b = DHpkcs3Engine::new(spec, None, Some(42)).unwrap();
assert_eq!(a.private_key(), b.private_key());
assert_eq!(a.public_key(), b.public_key());
}
#[test]
fn compute_secret_key_rejects_out_of_range_peer() {
let spec = small_spec();
let engine = DHpkcs3Engine::from_private(BigUint::from(6u32), spec).unwrap();
assert!(engine.compute_secret_key(&BigUint::zero()).is_err());
assert!(engine.compute_secret_key(&BigUint::one()).is_err());
assert!(engine.compute_secret_key(&BigUint::from(22u32)).is_err()); assert!(engine.compute_secret_key(&BigUint::from(8u32)).is_ok());
}
#[test]
fn compute_secret_key_rejects_small_subgroup_peer() {
let spec = DhParameterSpec::new(BigUint::from(467u32), BigUint::from(4u32), 8)
.with_subgroup_order(BigUint::from(233u32));
let engine = DHpkcs3Engine::from_private(BigUint::from(5u32), spec).unwrap();
assert!(engine.compute_secret_key(&BigUint::from(4u32)).is_ok());
let err = engine.compute_secret_key(&BigUint::from(2u32)).unwrap_err();
assert!(err.0.contains("small-subgroup"));
}
#[test]
fn zero_private_key_is_rejected() {
let spec = small_spec();
let err = DHpkcs3Engine::from_private(BigUint::zero(), spec).unwrap_err();
assert!(err.0.contains("must not be zero"));
}
#[test]
fn out_of_range_private_key_is_rejected() {
let spec = small_spec();
let err = DHpkcs3Engine::from_private(BigUint::from(23u32), spec).unwrap_err();
assert!(err.0.contains("less than"));
}
#[test]
fn degenerate_subgroup_order_is_rejected() {
let spec = DhParameterSpec::new(BigUint::from(23u32), BigUint::from(5u32), 8)
.with_subgroup_order(BigUint::one());
let err = DHpkcs3Engine::new(spec, None, Some(0)).unwrap_err();
assert!(err.0.contains("subgroup order"));
}
#[test]
fn private_key_respects_subgroup_order_q() {
let q = BigUint::from(101u32);
let spec = DhParameterSpec::new(BigUint::from(7919u32), BigUint::from(7u32), 256)
.with_subgroup_order(q.clone());
for seed in 0..50u64 {
let engine = DHpkcs3Engine::new(spec.clone(), None, Some(seed)).unwrap();
let x = engine.private_key();
assert!(*x >= BigUint::one(), "x must be >= 1");
assert!(*x < q, "x ({x}) must be < q ({q})");
}
}
#[test]
fn generated_private_key_is_within_range() {
let spec = DhParameterSpec::new(BigUint::from(2147483647u32), BigUint::from(5u32), 16);
let engine = DHpkcs3Engine::new(spec, None, Some(1)).unwrap();
let lower = BigUint::one() << 15;
let upper = BigUint::one() << 16;
assert!(engine.private_key() >= &lower);
assert!(engine.private_key() < &upper);
}
#[test]
fn non_multiple_of_8_bit_length_is_rejected() {
let spec = DhParameterSpec::new(BigUint::from(23u32), BigUint::from(5u32), 7);
let err = DHpkcs3Engine::new(spec, None, Some(0)).unwrap_err();
assert!(err.0.contains("Invalid bitLength"));
}
#[test]
fn zero_bit_length_is_rejected() {
let spec = DhParameterSpec::new(BigUint::from(23u32), BigUint::from(5u32), 0);
let err = DHpkcs3Engine::new(spec, None, Some(0)).unwrap_err();
assert!(err.0.contains("Invalid bitLength"));
}
#[test]
fn empty_range_after_cap_is_rejected() {
let spec = DhParameterSpec::new(BigUint::from(23u32), BigUint::from(5u32), 16);
let err = DHpkcs3Engine::new(spec, None, Some(0)).unwrap_err();
assert!(err.0.contains("No valid private-key range"));
}
}