diff --git a/x509-cert/src/builder.rs b/x509-cert/src/builder.rs index 9a1f1f921..82c6ddbbb 100644 --- a/x509-cert/src/builder.rs +++ b/x509-cert/src/builder.rs @@ -243,6 +243,42 @@ pub trait Builder: Sized { S::VerifyingKey: EncodePublicKey; /// Run the object through the signer and build it. + /// + /// # Notes + /// + /// When using ECDSA signers, the `Signature` parameter will need to be explicit + /// as multiple implementation of [`signature::Signer`] with various signature + /// are available. + /// + /// This would look like: + #[cfg_attr(feature = "std", doc = "```no_run")] + #[cfg_attr(not(feature = "std"), doc = "```ignore")] + /// # use rand::rng; + /// # use std::{ + /// # str::FromStr, + /// # time::Duration + /// # }; + /// # use x509_cert::{ + /// # builder::{self, CertificateBuilder, Builder}, + /// # name::Name, + /// # serial_number::SerialNumber, + /// # spki::SubjectPublicKeyInfo, + /// # time::Validity + /// # }; + /// # + /// # let mut rng = rng(); + /// # let signer = p256::ecdsa::SigningKey::random(&mut rng); + /// # let builder = CertificateBuilder::new( + /// # builder::profile::cabf::Root::new( + /// # false, + /// # Name::from_str("CN=World domination corporation").unwrap() + /// # ).unwrap(), + /// # SerialNumber::from(42u32), + /// # Validity::from_now(Duration::new(5, 0)).unwrap(), + /// # SubjectPublicKeyInfo::from_key(signer.verifying_key()).unwrap() + /// # ).unwrap(); + /// let certificate = builder.build::<_, ecdsa::der::Signature<_>>(&signer).unwrap(); + /// ``` fn build(mut self, signer: &S) -> Result where S: Signer, @@ -258,6 +294,45 @@ pub trait Builder: Sized { } /// Run the object through the signer and build it. + /// + /// # Notes + /// + /// When using ECDSA signers, the `Signature` parameter will need to be explicit + /// as multiple implementation of [`signature::Signer`] with various signature + /// are available. + /// + /// This would look like: + #[cfg_attr(feature = "std", doc = "```no_run")] + #[cfg_attr(not(feature = "std"), doc = "```ignore")] + /// # use rand::rng; + /// # use std::{ + /// # str::FromStr, + /// # time::Duration + /// # }; + /// # use x509_cert::{ + /// # builder::{self, CertificateBuilder, Builder}, + /// # name::Name, + /// # serial_number::SerialNumber, + /// # spki::SubjectPublicKeyInfo, + /// # time::Validity + /// # }; + /// # + /// # let mut rng = rng(); + /// # let signer = p256::ecdsa::SigningKey::random(&mut rng); + /// # let builder = CertificateBuilder::new( + /// # builder::profile::cabf::Root::new( + /// # false, + /// # Name::from_str("CN=World domination corporation").unwrap() + /// # ).unwrap(), + /// # SerialNumber::from(42u32), + /// # Validity::from_now(Duration::new(5, 0)).unwrap(), + /// # SubjectPublicKeyInfo::from_key(signer.verifying_key()).unwrap() + /// # ).unwrap(); + /// let certificate = builder.build_with_rng::<_, ecdsa::der::Signature<_>, _>( + /// &signer, + /// &mut rng + /// ).unwrap(); + /// ``` fn build_with_rng(mut self, signer: &S, rng: &mut R) -> Result where S: RandomizedSigner, @@ -351,6 +426,45 @@ pub trait AsyncBuilder: Sized { S::VerifyingKey: EncodePublicKey; /// Run the object through the signer and build it. + /// + /// # Notes + /// + /// When using ECDSA signers, the `Signature` parameter will need to be explicit + /// as multiple implementation of [`signature::AsyncSigner`] with various signature + /// are available. + /// + /// This would look like: + #[cfg_attr(feature = "std", doc = "```no_run")] + #[cfg_attr(not(feature = "std"), doc = "```ignore")] + /// # use rand::rng; + /// # use std::{ + /// # str::FromStr, + /// # time::Duration + /// # }; + /// # use x509_cert::{ + /// # builder::{self, CertificateBuilder, AsyncBuilder}, + /// # name::Name, + /// # serial_number::SerialNumber, + /// # spki::SubjectPublicKeyInfo, + /// # time::Validity + /// # }; + /// # + /// # async fn build() -> builder::Result<()> { + /// # let mut rng = rng(); + /// # let signer = p256::ecdsa::SigningKey::random(&mut rng); + /// # let builder = CertificateBuilder::new( + /// # builder::profile::cabf::Root::new( + /// # false, + /// # Name::from_str("CN=World domination corporation").unwrap() + /// # ).unwrap(), + /// # SerialNumber::from(42u32), + /// # Validity::from_now(Duration::new(5, 0)).unwrap(), + /// # SubjectPublicKeyInfo::from_key(signer.verifying_key()).unwrap() + /// # ).unwrap(); + /// let certificate = builder.build_async::<_, ecdsa::der::Signature<_>>(&signer).await?; + /// # Ok(()) + /// # } + /// ``` async fn build_async(mut self, signer: &S) -> Result where S: AsyncSigner, @@ -366,6 +480,45 @@ pub trait AsyncBuilder: Sized { } /// Run the object through the signer and build it. + /// + /// # Notes + /// + /// When using ECDSA signers, the `Signature` parameter will need to be explicit + /// as multiple implementation of [`signature::AsyncSigner`] with various signature + /// are available. + /// + /// This would look like: + #[cfg_attr(feature = "std", doc = "```no_run")] + #[cfg_attr(not(feature = "std"), doc = "```ignore")] + /// # use rand::rng; + /// # use std::{ + /// # str::FromStr, + /// # time::Duration + /// # }; + /// # use x509_cert::{ + /// # builder::{self, CertificateBuilder, AsyncBuilder}, + /// # name::Name, + /// # serial_number::SerialNumber, + /// # spki::SubjectPublicKeyInfo, + /// # time::Validity + /// # }; + /// # + /// # async fn build() -> builder::Result<()> { + /// # let mut rng = rng(); + /// # let signer = p256::ecdsa::SigningKey::random(&mut rng); + /// # let builder = CertificateBuilder::new( + /// # builder::profile::cabf::Root::new( + /// # false, + /// # Name::from_str("CN=World domination corporation").unwrap() + /// # ).unwrap(), + /// # SerialNumber::from(42u32), + /// # Validity::from_now(Duration::new(5, 0)).unwrap(), + /// # SubjectPublicKeyInfo::from_key(signer.verifying_key()).unwrap() + /// # ).unwrap(); + /// let certificate = builder.build_with_rng_async::<_, ecdsa::der::Signature<_>, _>(&signer, &mut rng).await?; + /// # Ok(()) + /// # } + /// ``` async fn build_with_rng_async( mut self, signer: &S,