jwt_compact_frame/alg/

rsa.rs

//! RSA-based JWT algorithms: `RS*` and `PS*`.

pub use rsa::{errors::Error as RsaError, RsaPrivateKey, RsaPublicKey};

use rand_core::{CryptoRng, RngCore};
use rsa::{
	traits::{PrivateKeyParts, PublicKeyParts},
	BigUint, Pkcs1v15Sign, Pss,
};
use sha2::{Digest, Sha256, Sha384, Sha512};

use core::{fmt, str::FromStr};

use crate::{
	alg::{SecretBytes, StrongKey, WeakKeyError},
	alloc::{Cow, String, ToOwned, Vec},
	jwk::{JsonWebKey, JwkError, KeyType, RsaPrimeFactor, RsaPrivateParts},
	Algorithm, AlgorithmSignature,
};
use scale_info::prelude::boxed::Box;

/// RSA signature.
#[derive(Debug)]
#[cfg_attr(docsrs, doc(cfg(feature = "rsa")))]
pub struct RsaSignature(Vec<u8>);

impl AlgorithmSignature for RsaSignature {
	const LENGTH: Option<core::num::NonZeroUsize> = None;

	fn try_from_slice(bytes: &[u8]) -> anyhow::Result<Self> {
		Ok(RsaSignature(bytes.to_vec()))
	}

	fn as_bytes(&self) -> Cow<'_, [u8]> {
		Cow::Borrowed(&self.0)
	}
}

/// RSA hash algorithm.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
enum HashAlg {
	Sha256,
	Sha384,
	Sha512,
}

impl HashAlg {
	fn digest(self, message: &[u8]) -> Box<[u8]> {
		match self {
			Self::Sha256 => {
				let digest: [u8; 32] = *(Sha256::digest(message).as_ref());
				Box::new(digest)
			},
			Self::Sha384 => {
				let mut digest = [0_u8; 48];
				digest.copy_from_slice(Sha384::digest(message).as_ref());
				Box::new(digest)
			},
			Self::Sha512 => {
				let mut digest = [0_u8; 64];
				digest.copy_from_slice(Sha512::digest(message).as_ref());
				Box::new(digest)
			},
		}
	}
}

/// RSA padding algorithm.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
enum Padding {
	Pkcs1v15,
	Pss,
}

#[derive(Debug)]
enum PaddingScheme {
	Pkcs1v15(Pkcs1v15Sign),
	Pss(Pss),
}

/// Bit length of an RSA key modulus (aka RSA key length).
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
#[non_exhaustive]
#[cfg_attr(docsrs, doc(cfg(feature = "rsa")))]
pub enum ModulusBits {
	/// 2048 bits. This is the minimum recommended key length as of 2020.
	TwoKibibytes,
	/// 3072 bits.
	ThreeKibibytes,
	/// 4096 bits.
	FourKibibytes,
}

impl ModulusBits {
	/// Converts this length to the numeric value.
	pub fn bits(self) -> usize {
		match self {
			Self::TwoKibibytes => 2_048,
			Self::ThreeKibibytes => 3_072,
			Self::FourKibibytes => 4_096,
		}
	}

	fn is_valid_bits(bits: usize) -> bool {
		matches!(bits, 2_048 | 3_072 | 4_096)
	}
}

impl TryFrom<usize> for ModulusBits {
	type Error = ModulusBitsError;

	fn try_from(value: usize) -> Result<Self, Self::Error> {
		match value {
			2_048 => Ok(Self::TwoKibibytes),
			3_072 => Ok(Self::ThreeKibibytes),
			4_096 => Ok(Self::FourKibibytes),
			_ => Err(ModulusBitsError(())),
		}
	}
}

/// Error type returned when a conversion of an integer into `ModulusBits` fails.
#[derive(Debug)]
#[cfg_attr(docsrs, doc(cfg(feature = "rsa")))]
pub struct ModulusBitsError(());

impl fmt::Display for ModulusBitsError {
	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		formatter.write_str(
			"Unsupported bit length of RSA modulus; only lengths 2048, 3072 and 4096 \
            are supported.",
		)
	}
}

#[cfg(feature = "std")]
impl std::error::Error for ModulusBitsError {}

/// Integrity algorithm using [RSA] digital signatures.
///
/// Depending on the variation, the algorithm employs PKCS#1 v1.5 or PSS padding and
/// one of the hash functions from the SHA-2 family: SHA-256, SHA-384, or SHA-512.
/// See [RFC 7518] for more details. Depending on the chosen parameters,
/// the name of the algorithm is one of `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`:
///
/// - `R` / `P` denote the padding scheme: PKCS#1 v1.5 for `R`, PSS for `P`
/// - `256` / `384` / `512` denote the hash function
///
/// The length of RSA keys is not unequivocally specified by the algorithm; nevertheless,
/// it **MUST** be at least 2048 bits as per RFC 7518. To minimize risks of misconfiguration,
/// use [`StrongAlg`](super::StrongAlg) wrapper around `Rsa`:
///
/// ```
/// # use jwt_compact_frame::alg::{StrongAlg, Rsa};
/// const ALG: StrongAlg<Rsa> = StrongAlg(Rsa::rs256());
/// // `ALG` will not support RSA keys with unsecure lengths by design!
/// ```
///
/// [RSA]: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
/// [RFC 7518]: https://www.rfc-editor.org/rfc/rfc7518.html
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(docsrs, doc(cfg(feature = "rsa")))]
pub struct Rsa {
	hash_alg: HashAlg,
	padding_alg: Padding,
}

impl Algorithm for Rsa {
	type Signature = RsaSignature;
	type SigningKey = RsaPrivateKey;
	type VerifyingKey = RsaPublicKey;

	fn name(&self) -> Cow<'static, str> {
		Cow::Borrowed(self.alg_name())
	}

	fn sign(&self, signing_key: &Self::SigningKey, message: &[u8]) -> Self::Signature {
		let digest = self.hash_alg.digest(message);
		let digest = digest.as_ref();
		let signing_result = match self.padding_scheme() {
			PaddingScheme::Pkcs1v15(padding) => signing_key.sign_with_rng(&mut rand_core::OsRng, padding, digest),
			PaddingScheme::Pss(padding) => signing_key.sign_with_rng(&mut rand_core::OsRng, padding, digest),
		};
		RsaSignature(signing_result.expect("Unexpected RSA signature failure"))
	}

	fn verify_signature(
		&self,
		signature: &Self::Signature,
		verifying_key: &Self::VerifyingKey,
		message: &[u8],
	) -> bool {
		let digest = self.hash_alg.digest(message);
		let verify_result = match self.padding_scheme() {
			PaddingScheme::Pkcs1v15(padding) => verifying_key.verify(padding, &digest, &signature.0),
			PaddingScheme::Pss(padding) => verifying_key.verify(padding, &digest, &signature.0),
		};
		verify_result.is_ok()
	}
}

impl Rsa {
	const fn new(hash_alg: HashAlg, padding_alg: Padding) -> Self {
		Rsa { hash_alg, padding_alg }
	}

	/// RSA with SHA-256 and PKCS#1 v1.5 padding.
	pub const fn rs256() -> Rsa {
		Rsa::new(HashAlg::Sha256, Padding::Pkcs1v15)
	}

	/// RSA with SHA-384 and PKCS#1 v1.5 padding.
	pub const fn rs384() -> Rsa {
		Rsa::new(HashAlg::Sha384, Padding::Pkcs1v15)
	}

	/// RSA with SHA-512 and PKCS#1 v1.5 padding.
	pub const fn rs512() -> Rsa {
		Rsa::new(HashAlg::Sha512, Padding::Pkcs1v15)
	}

	/// RSA with SHA-256 and PSS padding.
	pub const fn ps256() -> Rsa {
		Rsa::new(HashAlg::Sha256, Padding::Pss)
	}

	/// RSA with SHA-384 and PSS padding.
	pub const fn ps384() -> Rsa {
		Rsa::new(HashAlg::Sha384, Padding::Pss)
	}

	/// RSA with SHA-512 and PSS padding.
	pub const fn ps512() -> Rsa {
		Rsa::new(HashAlg::Sha512, Padding::Pss)
	}

	/// RSA based on the specified algorithm name.
	///
	/// # Panics
	///
	/// - Panics if the name is not one of the six RSA-based JWS algorithms. Prefer using
	///   the [`FromStr`] trait if the conversion is potentially fallible.
	pub fn with_name(name: &str) -> Self {
		name.parse().unwrap()
	}

	fn padding_scheme(self) -> PaddingScheme {
		match self.padding_alg {
			Padding::Pkcs1v15 => PaddingScheme::Pkcs1v15(match self.hash_alg {
				HashAlg::Sha256 => Pkcs1v15Sign::new::<Sha256>(),
				HashAlg::Sha384 => Pkcs1v15Sign::new::<Sha384>(),
				HashAlg::Sha512 => Pkcs1v15Sign::new::<Sha512>(),
			}),
			Padding::Pss => {
				// The salt length needs to be set to the size of hash function output;
				// see https://www.rfc-editor.org/rfc/rfc7518.html#section-3.5.
				PaddingScheme::Pss(match self.hash_alg {
					HashAlg::Sha256 => Pss::new_with_salt::<Sha256>(Sha256::output_size()),
					HashAlg::Sha384 => Pss::new_with_salt::<Sha384>(Sha384::output_size()),
					HashAlg::Sha512 => Pss::new_with_salt::<Sha512>(Sha512::output_size()),
				})
			},
		}
	}

	fn alg_name(self) -> &'static str {
		match (self.padding_alg, self.hash_alg) {
			(Padding::Pkcs1v15, HashAlg::Sha256) => "RS256",
			(Padding::Pkcs1v15, HashAlg::Sha384) => "RS384",
			(Padding::Pkcs1v15, HashAlg::Sha512) => "RS512",
			(Padding::Pss, HashAlg::Sha256) => "PS256",
			(Padding::Pss, HashAlg::Sha384) => "PS384",
			(Padding::Pss, HashAlg::Sha512) => "PS512",
		}
	}

	/// Generates a new key pair with the specified modulus bit length (aka key length).
	pub fn generate<R: CryptoRng + RngCore>(
		rng: &mut R,
		modulus_bits: ModulusBits,
	) -> rsa::errors::Result<(StrongKey<RsaPrivateKey>, StrongKey<RsaPublicKey>)> {
		let signing_key = RsaPrivateKey::new(rng, modulus_bits.bits())?;
		let verifying_key = signing_key.to_public_key();
		Ok((StrongKey(signing_key), StrongKey(verifying_key)))
	}
}

impl FromStr for Rsa {
	type Err = RsaParseError;

	fn from_str(s: &str) -> Result<Self, Self::Err> {
		Ok(match s {
			"RS256" => Self::rs256(),
			"RS384" => Self::rs384(),
			"RS512" => Self::rs512(),
			"PS256" => Self::ps256(),
			"PS384" => Self::ps384(),
			"PS512" => Self::ps512(),
			_ => return Err(RsaParseError(s.to_owned())),
		})
	}
}

/// Errors that can occur when parsing an [`Rsa`] algorithm from a string.
#[derive(Debug)]
#[cfg_attr(docsrs, doc(cfg(feature = "rsa")))]
pub struct RsaParseError(String);

impl fmt::Display for RsaParseError {
	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
		write!(formatter, "Invalid RSA algorithm name: {}", self.0)
	}
}

#[cfg(feature = "std")]
impl std::error::Error for RsaParseError {}

impl StrongKey<RsaPrivateKey> {
	/// Converts this private key to a public key.
	pub fn to_public_key(&self) -> StrongKey<RsaPublicKey> {
		StrongKey(self.0.to_public_key())
	}
}

impl TryFrom<RsaPrivateKey> for StrongKey<RsaPrivateKey> {
	type Error = WeakKeyError<RsaPrivateKey>;

	fn try_from(key: RsaPrivateKey) -> Result<Self, Self::Error> {
		if ModulusBits::is_valid_bits(key.n().bits()) {
			Ok(StrongKey(key))
		} else {
			Err(WeakKeyError(key))
		}
	}
}

impl TryFrom<RsaPublicKey> for StrongKey<RsaPublicKey> {
	type Error = WeakKeyError<RsaPublicKey>;

	fn try_from(key: RsaPublicKey) -> Result<Self, Self::Error> {
		if ModulusBits::is_valid_bits(key.n().bits()) {
			Ok(StrongKey(key))
		} else {
			Err(WeakKeyError(key))
		}
	}
}

impl<'a> From<&'a RsaPublicKey> for JsonWebKey<'a> {
	fn from(key: &'a RsaPublicKey) -> JsonWebKey<'a> {
		JsonWebKey::Rsa {
			modulus: Cow::Owned(key.n().to_bytes_be()),
			public_exponent: Cow::Owned(key.e().to_bytes_be()),
			private_parts: None,
		}
	}
}

impl TryFrom<&JsonWebKey<'_>> for RsaPublicKey {
	type Error = JwkError;

	fn try_from(jwk: &JsonWebKey<'_>) -> Result<Self, Self::Error> {
		let JsonWebKey::Rsa { modulus, public_exponent, .. } = jwk else {
			return Err(JwkError::key_type(jwk, KeyType::Rsa));
		};

		let e = BigUint::from_bytes_be(public_exponent);
		let n = BigUint::from_bytes_be(modulus);
		Self::new(n, e).map_err(|err| JwkError::custom(anyhow::anyhow!(err)))
	}
}

/// ⚠ **Warning.** Contrary to [RFC 7518], this implementation does not set `dp`, `dq`, and `qi`
/// fields in the JWK root object, as well as `d` and `t` fields for additional factors
/// (i.e., in the `oth` array).
///
/// [RFC 7518]: https://tools.ietf.org/html/rfc7518#section-6.3.2
impl<'a> From<&'a RsaPrivateKey> for JsonWebKey<'a> {
	fn from(key: &'a RsaPrivateKey) -> JsonWebKey<'a> {
		const MSG: &str = "RsaPrivateKey must have at least 2 prime factors";

		let p = key.primes().get(0).expect(MSG);
		let q = key.primes().get(1).expect(MSG);

		let private_parts = RsaPrivateParts {
			private_exponent: SecretBytes::owned(key.d().to_bytes_be()),
			prime_factor_p: SecretBytes::owned(p.to_bytes_be()),
			prime_factor_q: SecretBytes::owned(q.to_bytes_be()),
			p_crt_exponent: None,
			q_crt_exponent: None,
			q_crt_coefficient: None,
			other_prime_factors: key.primes()[2..]
				.iter()
				.map(|factor| RsaPrimeFactor {
					factor: SecretBytes::owned(factor.to_bytes_be()),
					crt_exponent: None,
					crt_coefficient: None,
				})
				.collect(),
		};

		JsonWebKey::Rsa {
			modulus: Cow::Owned(key.n().to_bytes_be()),
			public_exponent: Cow::Owned(key.e().to_bytes_be()),
			private_parts: Some(private_parts),
		}
	}
}

/// ⚠ **Warning.** Contrary to [RFC 7518] (at least, in spirit), this conversion ignores
/// `dp`, `dq`, and `qi` fields from JWK, as well as `d` and `t` fields for additional factors.
///
/// [RFC 7518]: https://www.rfc-editor.org/rfc/rfc7518.html
impl TryFrom<&JsonWebKey<'_>> for RsaPrivateKey {
	type Error = JwkError;

	fn try_from(jwk: &JsonWebKey<'_>) -> Result<Self, Self::Error> {
		let JsonWebKey::Rsa { modulus, public_exponent, private_parts } = jwk else {
			return Err(JwkError::key_type(jwk, KeyType::Rsa));
		};

		let RsaPrivateParts { private_exponent: d, prime_factor_p, prime_factor_q, other_prime_factors, .. } =
			private_parts.as_ref().ok_or_else(|| JwkError::NoField("d".into()))?;

		let e = BigUint::from_bytes_be(public_exponent);
		let n = BigUint::from_bytes_be(modulus);
		let d = BigUint::from_bytes_be(d);

		let mut factors = Vec::with_capacity(2 + other_prime_factors.len());
		factors.push(BigUint::from_bytes_be(prime_factor_p));
		factors.push(BigUint::from_bytes_be(prime_factor_q));
		factors.extend(other_prime_factors.iter().map(|prime| BigUint::from_bytes_be(&prime.factor)));

		let key = Self::from_components(n, e, d, factors);
		let key = key.map_err(|err| JwkError::custom(anyhow::anyhow!(err)))?;
		key.validate().map_err(|err| JwkError::custom(anyhow::anyhow!(err)))?;
		Ok(key)
	}
}