From 6f91e705d30803d1d2d49a2def954606083e42e9 Mon Sep 17 00:00:00 2001
From: DarkCat09 <gh@dc09.ru>
Date: Thu, 8 Aug 2024 17:32:28 +0400
Subject: [PATCH] docs: add doc-comments for crate::certs

---
 src/certs/fingerprint.rs | 10 ++++++++--
 src/certs/insecure.rs    | 13 +++++++++++++
 src/certs/mod.rs         |  8 ++++++++
 src/certs/verifier.rs    |  4 ++++
 4 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/src/certs/fingerprint.rs b/src/certs/fingerprint.rs
index 2846b3e..94f0680 100644
--- a/src/certs/fingerprint.rs
+++ b/src/certs/fingerprint.rs
@@ -1,17 +1,23 @@
+//! Helpers for TLS cert fingerprint generating
+
 use base64ct::{Base64Unpadded, Encoding};
 use sha2::{Digest, Sha256, Sha512};
 
 use super::verifier::CertificateDer;
 
-const SHA256_B64_LEN: usize = 44; // 4 * ((256 / 8) as f64 / 3 as f64).ceil()
-const SHA512_B64_LEN: usize = 88; // 4 * ((512 / 8) as f64 / 3 as f64).ceil()
+pub const SHA256_B64_LEN: usize = 44; // 4 * ((256 / 8) as f64 / 3 as f64).ceil()
+pub const SHA512_B64_LEN: usize = 88; // 4 * ((512 / 8) as f64 / 3 as f64).ceil()
 
+/// Certificate hashing algorithms
+/// supported in this library
 #[derive(Debug, Clone, Copy)]
 pub enum Algorithm {
     Sha256,
     Sha512,
 }
 
+/// Generate a fingerprint for the provided certificate
+/// using the specified algorithm + base64
 pub fn generate_fingerprint(cert: &CertificateDer, algo: Algorithm) -> String {
     match algo {
         Algorithm::Sha256 => {
diff --git a/src/certs/insecure.rs b/src/certs/insecure.rs
index 5aa594e..8322c65 100644
--- a/src/certs/insecure.rs
+++ b/src/certs/insecure.rs
@@ -1,13 +1,26 @@
+//! Custom verifier for Rustls accepting any TLS cert
+//! (usually called "insecure mode")
+
 use tokio_rustls::rustls::{
     self,
     client::danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier},
     crypto::CryptoProvider,
 };
 
+/// Custom verifier for Rustls accepting any TLS certificate
 #[derive(Debug)]
 pub struct AllowAllCertVerifier(std::sync::Arc<CryptoProvider>);
 
 impl AllowAllCertVerifier {
+    /// Constructor for this verifier.
+    /// Use only if you know what you are doing.
+    ///
+    /// # Examples
+    /// ```
+    /// let client = tokio_gemini::Client::builder()
+    ///     .with_custom_verifier(AllowAllCertVerifier::yes_i_know_what_i_am_doing())
+    ///     .build()
+    /// ```
     pub fn yes_i_know_what_i_am_doing() -> Self {
         AllowAllCertVerifier(
             CryptoProvider::get_default()
diff --git a/src/certs/mod.rs b/src/certs/mod.rs
index 7931c3c..898888e 100644
--- a/src/certs/mod.rs
+++ b/src/certs/mod.rs
@@ -1,3 +1,5 @@
+//! Everything related to TLS certs verification
+
 pub mod fingerprint;
 pub mod insecure;
 
@@ -10,6 +12,9 @@ pub use tokio_rustls::rustls::pki_types::{CertificateDer, ServerName, UnixTime};
 
 use tokio_rustls::rustls;
 
+/// Trait for implementing self-signed cert verifiers
+/// like [`file_sscv::FileBasedCertVerifier`]
+/// (probably via known_hosts with TOFU policy or DANE verification)
 pub trait SelfsignedCertVerifier: Send + Sync {
     fn verify(
         &self,
@@ -19,6 +24,9 @@ pub trait SelfsignedCertVerifier: Send + Sync {
     ) -> Result<bool, rustls::Error>;
 }
 
+/// Structure holding a cert fingerprint and expiry date,
+/// suggested for using in a [`SelfsignedCertVerifier`] cert storage
+/// (like `HashMap<String, SelfsignedCert>`, as a known_hosts parsing result)
 pub struct SelfsignedCert {
     pub algo: crate::certs::fingerprint::Algorithm,
     pub fingerprint: String,
diff --git a/src/certs/verifier.rs b/src/certs/verifier.rs
index f1eb257..d09935f 100644
--- a/src/certs/verifier.rs
+++ b/src/certs/verifier.rs
@@ -1,3 +1,7 @@
+//! Internal custom Rustls verifier
+//! allowing verification both with webpki trust roots (when enabled)
+//! and with implementaions of our own [`SelfsignedCertVerifier`]
+
 use crate::certs::SelfsignedCertVerifier;
 
 use std::sync::Arc;