Cary over some docs

Author: sbernauer

crates/stackable-certs/src/ca/ca_builder.rs

@@ -59,6 +59,17 @@ where
 
 /// This builder builds certificate authorities of type [`CertificateAuthority`].
 ///
+/// It has many default values, notably;
+///
+/// - A default validity of [`DEFAULT_CA_VALIDITY`]
+/// - A default subject of [`SDP_ROOT_CA_SUBJECT`]
+/// - A randomly generated serial number
+/// - In case no `signing_key_pair` was provided, a fresh keypair will be created. The algorithm
+/// (`rsa`/`ecdsa`) is chosen by the generic [`CertificateKeypair`] type of this struct.
+///
+/// The CA contains the public half of the provided `signing_key_pair` and is signed by the private
+/// half of said key.
+///
 /// Example code to construct a CA:
 ///
 /// ```no_run
@@ -101,7 +112,7 @@ where
 {
     /// Convenience function to avoid calling `builder().finish_builder().build()`
     pub fn build(
-        self: Self,
+        self,
     ) -> Result<CertificateAuthority<SKP>, CreateCertificateAuthorityError<SKP::Error>> {
         self.finish_builder().build()
     }
@@ -128,6 +139,9 @@ where
             Some(signing_key_pair) => signing_key_pair,
             None => SKP::new().context(CreateSigningKeyPairSnafu)?,
         };
+
+        // By choosing a random serial number we can make the reasonable assumption that we generate
+        // a unique serial for each CA.
         let serial_number = SerialNumber::from(rand::random::<u64>());
 
         let spki_pem = signing_key_pair

crates/stackable-certs/src/cert_builder.rs

@@ -66,7 +66,21 @@ where
 
 /// This builder builds certificates of type [`CertificatePair`].
 ///
-/// Example code to construct a certificate:
+/// Currently you are required to specify a [`CertificateAuthority`], which is used to create a leaf
+/// certificate, which is signed by this CA.
+///
+/// These leaf certificates can be used for client/server authentication, because they include
+/// [`ID_KP_CLIENT_AUTH`] and [`ID_KP_SERVER_AUTH`] in the extended key usage extension.
+///
+/// This builder has many default values, notably;
+///
+/// - A default validity of [`DEFAULT_CERTIFICATE_VALIDITY`]
+/// - A randomly generated serial number
+/// - In case no `key_pair` was provided, a fresh keypair will be created. The algorithm
+/// (`rsa`/`ecdsa`) is chosen by the generic [`CertificateKeypair`] type of this struct,
+/// which is normally inferred from the [`CertificateAuthority`].
+///
+/// Example code to construct a CA and a signed certificate:
 ///
 /// ```no_run
 /// use stackable_certs::{
@@ -92,7 +106,7 @@ where
     KP: CertificateKeypair,
     <KP::SigningKey as signature::Keypair>::VerifyingKey: EncodePublicKey,
 {
-    /// Required subject of the certificate, usually starts with `CN=`.
+    /// Required subject of the certificate, usually starts with `CN=`, e.g. `CN=mypod`.
     subject: &'a str,
 
     /// Optional list of subject alternative name DNS entries
@@ -151,6 +165,9 @@ where
             Some(key_pair) => key_pair,
             None => SKP::new().context(CreateKeyPairSnafu)?,
         };
+
+        // By choosing a random serial number we can make the reasonable assumption that we generate
+        // a unique serial for each certificate.
         let serial_number = SerialNumber::from(rand::random::<u64>());
 
         let ca_validity = self.signed_by.ca_cert().tbs_certificate.validity;