From cba32cd4f3f8b0ec21dde7fdbdea1ac99d17e991 Mon Sep 17 00:00:00 2001
From: Techassi <sascha.lautenschlaeger@stackable.tech>
Date: Mon, 4 Mar 2024 14:52:28 +0100
Subject: [PATCH] Add a few more (doc) comments

---
 stackable-certs/src/ca/mod.rs | 12 ++++++++++++
 stackable-certs/src/lib.rs    |  3 +++
 2 files changed, 15 insertions(+)

diff --git a/stackable-certs/src/ca/mod.rs b/stackable-certs/src/ca/mod.rs
index ee01e4757..d24da6217 100644
--- a/stackable-certs/src/ca/mod.rs
+++ b/stackable-certs/src/ca/mod.rs
@@ -232,7 +232,14 @@ where
         T: KeypairExt,
         <T::SigningKey as signature::Keypair>::VerifyingKey: EncodePublicKey,
     {
+        // We generate a random serial number, but ensure the same CA didn't
+        // issue another certificate with the same serial number. We try to
+        // generate a unique serial number at max five times before giving up
+        // and returning an error.
         let serial_number = self.generate_serial_number()?;
+
+        // NOTE (@Techassi): Should we validate that the validity is shorter
+        // than the validity of the issuing CA?
         let validity = Validity::from_now(*validity).context(ParseValiditySnafu)?;
         let subject = format_leaf_certificate_subject(name, scope)?;
 
@@ -244,6 +251,8 @@ where
         let spki = SubjectPublicKeyInfoOwned::from_pem(spki_pem.as_bytes())
             .context(DecodeSpkiFromPemSnafu)?;
 
+        // The leaf certificate can be used for WWW client and server
+        // authentication. This is a base requirement for TLS certs.
         let eku = ExtendedKeyUsage(vec![ID_KP_CLIENT_AUTH, ID_KP_SERVER_AUTH]);
         let aki = AuthorityKeyIdentifier::try_from(spki.owned_to_ref())
             .context(ParseAuthorityKeyIdentifierSnafu)?;
@@ -268,6 +277,7 @@ where
         )
         .context(CreateCertificateBuilderSnafu)?;
 
+        // Again, add the extension created above.
         builder
             .add_extension(&eku)
             .context(AddCertificateExtensionSnafu)?;
@@ -305,6 +315,7 @@ where
 }
 
 impl CertificateAuthority<rsa::SigningKey> {
+    /// High-level function to create a new CA using a RSA key pair.
     #[instrument(name = "create_certificate_authority_with_rsa")]
     pub fn new_rsa() -> Result<Self> {
         Self::new(rsa::SigningKey::new(None).context(GenerateRsaSigningKeySnafu)?)
@@ -312,6 +323,7 @@ impl CertificateAuthority<rsa::SigningKey> {
 }
 
 impl CertificateAuthority<ecdsa::SigningKey> {
+    /// High-level function to create a new CA using a ECDSA key pair.
     #[instrument(name = "create_certificate_authority_with_ecdsa")]
     pub fn new_ecdsa() -> Result<Self> {
         Self::new(ecdsa::SigningKey::new().context(GenerateEcdsaSigningKeySnafu)?)
diff --git a/stackable-certs/src/lib.rs b/stackable-certs/src/lib.rs
index 64a193c0e..1ece3e10d 100644
--- a/stackable-certs/src/lib.rs
+++ b/stackable-certs/src/lib.rs
@@ -50,6 +50,8 @@ pub mod keys;
 pub const CERTIFICATE_FILE_EXT: &str = "crt";
 pub const PRIVATE_KEY_FILE_EXT: &str = "key";
 
+/// Error variants which can be encountered when creating a new
+/// [`CertificatePair`].
 #[derive(Debug, Snafu)]
 pub enum CertificatePairError<E>
 where
@@ -338,6 +340,7 @@ pub enum PrivateKeyType {
     Rsa,
 }
 
+/// Private and public key encoding, either DER or PEM.
 #[derive(Debug)]
 pub enum KeyEncoding {
     Pem,