Improve cert doxygen [ci skip]

12 files changed, 395 insertions, 146 deletions

diff --git a/src/lib/cert/x509/cert_status.h b/src/lib/cert/x509/cert_status.h
index 52b65fb57..b69bd1832 100644
--- a/src/lib/cert/x509/cert_status.h
+++ b/src/lib/cert/x509/cert_status.h
@@ -10,6 +10,9 @@
 
 namespace Botan {
 
+/**
+* Certificate validation status code
+*/
 enum class Certificate_Status_Code {
    VERIFIED = 0x00000000,
    OCSP_RESPONSE_GOOD,
diff --git a/src/lib/cert/x509/certstor.h b/src/lib/cert/x509/certstor.h
index 55f6b8c93..56176739b 100644
--- a/src/lib/cert/x509/certstor.h
+++ b/src/lib/cert/x509/certstor.h
@@ -22,13 +22,25 @@ class BOTAN_DLL Certificate_Store
       virtual ~Certificate_Store() {}
 
       /**
-      * Subject DN and (optionally) key identifier
+      * Find a certificate by Subject DN and (optionally) key identifier
+      * @param subject_dn the subject's distinguished name
+      * @param key_id an optional key id
+      * @return a matching certificate or nullptr otherwise
       */
       virtual std::shared_ptr<const X509_Certificate>
          find_cert(const X509_DN& subject_dn, const std::vector<byte>& key_id) const = 0;
 
+      /**
+      * Finds a CRL for the given certificate
+      * @param subject the subject certificate
+      * @return the CRL for subject or nullptr otherwise
+      */
       virtual std::shared_ptr<const X509_CRL> find_crl_for(const X509_Certificate& subject) const;
 
+      /**
+      * @return whether the certificate is known
+      * @param cert certififcate to be searched
+      */
       bool certificate_known(const X509_Certificate& cert) const
          {
          return find_cert(cert.subject_dn(), cert.subject_key_id()) != nullptr;
@@ -50,20 +62,43 @@ class BOTAN_DLL Certificate_Store_In_Memory : public Certificate_Store
       */
       explicit Certificate_Store_In_Memory(const std::string& dir);
 
+      /**
+      * Adds given certificate to the store.
+      */
       explicit Certificate_Store_In_Memory(const X509_Certificate& cert);
 
+      /**
+      * Create an empty store.
+      */
       Certificate_Store_In_Memory() {}
 
+      /**
+      * Add a certificate to the store.
+      * @param cert certificate to be added
+      */
       void add_certificate(const X509_Certificate& cert);
 
+      /**
+      * Add a certificate revocation list (CRL) to the store.
+      * @param crl CRL to be added
+      */
       void add_crl(const X509_CRL& crl);
 
+      /**
+      * @return DNs for all certificates managed by the store
+      */
       std::vector<X509_DN> all_subjects() const override;
 
+      /*
+      * Find a certificate by Subject DN and (optionally) key identifier
+      */
       std::shared_ptr<const X509_Certificate> find_cert(
          const X509_DN& subject_dn,
          const std::vector<byte>& key_id) const override;
 
+      /**
+      * Finds a CRL for the given certificate
+      */
       std::shared_ptr<const X509_CRL> find_crl_for(const X509_Certificate& subject) const override;
    private:
       // TODO: Add indexing on the DN and key id to avoid linear search
@@ -71,14 +106,23 @@ class BOTAN_DLL Certificate_Store_In_Memory : public Certificate_Store
       std::vector<std::shared_ptr<X509_CRL>> m_crls;
    };
 
+/**
+* FIXME add doc
+*/
 class BOTAN_DLL Certificate_Store_Overlay : public Certificate_Store
    {
    public:
       explicit Certificate_Store_Overlay(const std::vector<std::shared_ptr<const X509_Certificate>>& certs) :
          m_certs(certs) {}
 
+      /**
+      * @return DNs for all certificates managed by the store
+      */
       std::vector<X509_DN> all_subjects() const override;
 
+      /**
+      * Find a certificate by Subject DN and (optionally) key identifier
+      */
       std::shared_ptr<const X509_Certificate> find_cert(
          const X509_DN& subject_dn,
          const std::vector<byte>& key_id) const override;
diff --git a/src/lib/cert/x509/certstor_sql/certstor_sql.h b/src/lib/cert/x509/certstor_sql/certstor_sql.h
index 096426b7a..5b6a376c7 100644
--- a/src/lib/cert/x509/certstor_sql/certstor_sql.h
+++ b/src/lib/cert/x509/certstor_sql/certstor_sql.h
@@ -16,36 +16,42 @@
 namespace Botan {
 
 /**
- * Certificate and private key store backed an SQL database.
+ * Certificate and private key store backed by an SQL database.
  */
 class BOTAN_DLL Certificate_Store_In_SQL : public Certificate_Store
    {
    public:
       /**
-       * Create/open a certificate store backed by "db".
-       * Inserted private keys are encrypted using "passwd".
-       */
+      * Create/open a certificate store.
+      * @param db underlying database storage
+      * @param passwd password to encrypt private keys in the database
+      * @param table_prefix optional prefix for db table names
+      */
       explicit Certificate_Store_In_SQL(const std::shared_ptr<SQL_Database> db,
-                                         const std::string& passwd,
-                                         const std::string& table_prefix = "");
+                                        const std::string& passwd,
+                                        const std::string& table_prefix = "");
 
-      /// Returns the first certificate with matching subject DN and optional key ID.
+      /**
+      * Returns the first certificate with matching subject DN and optional key ID.
+      */
       virtual std::shared_ptr<const X509_Certificate>
          find_cert(const X509_DN& subject_dn, const std::vector<byte>& key_id) const override;
 
-      /// Returns all subject DNs known to the store instance,
+      /**
+      * Returns all subject DNs known to the store instance.
+      */
       virtual std::vector<X509_DN> all_subjects() const override;
 
       /**
-       * Inserts "cert" into the store, returns false if the certificate is
-       * already known and true if insertion was successful.
-       */
+      * Inserts "cert" into the store, returns false if the certificate is
+      * already known and true if insertion was successful.
+      */
       bool insert_cert(const X509_Certificate& cert);
 
       /**
-       * Removes "cert" from the store. Returns false if the certificate could not
-       * be found and true if removal was successful.
-       */
+      * Removes "cert" from the store. Returns false if the certificate could not
+      * be found and true if removal was successful.
+      */
       bool remove_cert(const X509_Certificate& cert);
 
       /// Returns the private key for "cert" or an empty shared_ptr if none was found.
@@ -56,27 +62,29 @@ class BOTAN_DLL Certificate_Store_In_SQL : public Certificate_Store
          find_certs_for_key(const Private_Key& key) const;
 
       /**
-       * Inserts "key" for "cert" into the store, returns false if the key is
-       * already known and true if insertion was successful.
-       */
+      * Inserts "key" for "cert" into the store, returns false if the key is
+      * already known and true if insertion was successful.
+      */
       bool insert_key(const X509_Certificate& cert, const Private_Key& key);
 
       /// Removes "key" from the store.
       void remove_key(const Private_Key& key);
 
       /// Marks "cert" as revoked starting from "time".
-      void revoke_cert(const X509_Certificate&,CRL_Code,const X509_Time& time = X509_Time());
+      void revoke_cert(const X509_Certificate&, CRL_Code, const X509_Time& time = X509_Time());
 
       /// Reverses the revokation for "cert".
       void affirm_cert(const X509_Certificate&);
 
       /**
-       * Generates Certificate Revocation Lists for all certificates marked as revoked.
-       * A CRL is returned for each unique issuer DN.
-       */
+      * Generates Certificate Revocation Lists for all certificates marked as revoked.
+      * A CRL is returned for each unique issuer DN.
+      */
       std::vector<X509_CRL> generate_crls() const;
 
-      /// Generates a CRL for all certificates issued by the given issuer.
+      /**
+      * Generates a CRL for all certificates issued by the given issuer.
+      */
       virtual std::shared_ptr<const X509_CRL>
          find_crl_for(const X509_Certificate& issuer) const override;
 
diff --git a/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h b/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h
index c7d686d89..c712b9526 100644
--- a/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h
+++ b/src/lib/cert/x509/certstor_sqlite3/certstor_sqlite.h
@@ -12,12 +12,21 @@
 
 namespace Botan {
 
+/**
+* Certificate and private key store backed by an sqlite (http://sqlite.org) database.
+*/
 class BOTAN_DLL Certificate_Store_In_SQLite : public Certificate_Store_In_SQL
    {
    public:
+      /**
+      * Create/open a certificate store.
+      * @param db underlying database storage
+      * @param passwd password to encrypt private keys in the database
+      * @param table_prefix optional prefix for db table names
+      */
       Certificate_Store_In_SQLite(const std::string& db_path,
-                                           const std::string& passwd,
-                                           const std::string& table_prefix = "");
+                                  const std::string& passwd,
+                                  const std::string& table_prefix = "");
    };
 }
 #endif
diff --git a/src/lib/cert/x509/crl_ent.h b/src/lib/cert/x509/crl_ent.h
index 4be508812..6600621e5 100644
--- a/src/lib/cert/x509/crl_ent.h
+++ b/src/lib/cert/x509/crl_ent.h
@@ -63,6 +63,8 @@ class BOTAN_DLL CRL_Entry final : public ASN1_Object
 
       /**
       * Construct an empty CRL entry.
+      * @param throw_on_unknown_critical_extension should we throw an exception
+      * if an unknown CRL extension marked as critical is encountered
       */
       explicit CRL_Entry(bool throw_on_unknown_critical_extension = false);
 
diff --git a/src/lib/cert/x509/name_constraint.cpp b/src/lib/cert/x509/name_constraint.cpp
index 83f6386ba..e4d69c6ac 100644
--- a/src/lib/cert/x509/name_constraint.cpp
+++ b/src/lib/cert/x509/name_constraint.cpp
@@ -16,14 +16,14 @@
 
 namespace Botan {
 
-GeneralName::GeneralName(const std::string& v) : GeneralName()
+GeneralName::GeneralName(const std::string& str) : GeneralName()
    {
-   size_t p = v.find(':');
+   size_t p = str.find(':');
 
    if(p != std::string::npos)
       {
-      m_type = v.substr(0,p);
-      m_name = v.substr(p + 1,std::string::npos);
+      m_type = str.substr(0, p);
+      m_name = str.substr(p + 1, std::string::npos);
       }
    else
       {
@@ -47,7 +47,7 @@ void GeneralName::decode_from(class BER_Decoder& ber)
 
    if(tag == 1 || tag == 2 || tag == 6)
       {
-      m_name = Charset::transcode(ASN1::to_string(obj),LATIN1_CHARSET,LOCAL_CHARSET);
+      m_name = Charset::transcode(ASN1::to_string(obj), LATIN1_CHARSET, LOCAL_CHARSET);
 
       if(tag == 1)
          {
@@ -79,10 +79,10 @@ void GeneralName::decode_from(class BER_Decoder& ber)
       {
       if(obj.value.size() == 8)
          {
-         const std::vector<byte> ip(obj.value.begin(),obj.value.begin() + 4);
-         const std::vector<byte> net(obj.value.begin() + 4,obj.value.end());
+         const std::vector<byte> ip(obj.value.begin(), obj.value.begin() + 4);
+         const std::vector<byte> net(obj.value.begin() + 4, obj.value.end());
          m_type = "IP";
-         m_name = ipv4_to_string(load_be<u32bit>(ip.data(),0)) + "/" + ipv4_to_string(load_be<u32bit>(net.data(),0));
+         m_name = ipv4_to_string(load_be<u32bit>(ip.data(), 0)) + "/" + ipv4_to_string(load_be<u32bit>(net.data(), 0));
          }
       else if(obj.value.size() == 32)
          {
@@ -103,7 +103,7 @@ void GeneralName::decode_from(class BER_Decoder& ber)
 GeneralName::MatchResult GeneralName::matches(const X509_Certificate& cert) const
    {
    std::vector<std::string> nam;
-   std::function<bool(const GeneralName*,const std::string&)> match_fn;
+   std::function<bool(const GeneralName*, const std::string&)> match_fn;
 
    if(type() == "DNS")
       {
@@ -143,7 +143,7 @@ GeneralName::MatchResult GeneralName::matches(const X509_Certificate& cert) cons
 
    for(const std::string& n: nam)
       {
-      bool m = match_fn(this,n);
+      bool m = match_fn(this, n);
 
       some |= m;
       all &= m;
@@ -177,7 +177,7 @@ bool GeneralName::matches_dns(const std::string& nam) const
       {
       std::string constr = name().front() == '.' ? name() : "." + name();
       // constr is suffix of nam
-      return constr == nam.substr(nam.size() - constr.size(),constr.size());
+      return constr == nam.substr(nam.size() - constr.size(), constr.size());
       }
    }
 
@@ -211,7 +211,7 @@ bool GeneralName::matches_dn(const std::string& nam) const
 bool GeneralName::matches_ip(const std::string& nam) const
    {
    u32bit ip = string_to_ipv4(nam);
-   std::vector<std::string> p = split_on(name(),'/');
+   std::vector<std::string> p = split_on(name(), '/');
 
    if(p.size() != 2)
       throw Decoding_Error("failed to parse IPv4 address");
@@ -228,12 +228,12 @@ std::ostream& operator<<(std::ostream& os, const GeneralName& gn)
    return os;
    }
 
-GeneralSubtree::GeneralSubtree(const std::string& v) : GeneralSubtree()
+GeneralSubtree::GeneralSubtree(const std::string& str) : GeneralSubtree()
    {
    size_t p0, p1;
-   size_t min = std::stoull(v, &p0, 10);
-   size_t max = std::stoull(v.substr(p0 + 1), &p1, 10);
-   GeneralName gn(v.substr(p0 + p1 + 2));
+   size_t min = std::stoull(str, &p0, 10);
+   size_t max = std::stoull(str.substr(p0 + 1), &p1, 10);
+   GeneralName gn(str.substr(p0 + p1 + 2));
 
    if(p0 > 0 && p1 > 0)
       {
@@ -256,7 +256,7 @@ void GeneralSubtree::decode_from(class BER_Decoder& ber)
    {
    ber.start_cons(SEQUENCE)
       .decode(m_base)
-      .decode_optional(m_minimum,ASN1_Tag(0),CONTEXT_SPECIFIC,size_t(0))
+      .decode_optional(m_minimum,ASN1_Tag(0), CONTEXT_SPECIFIC,size_t(0))
    .end_cons();
 
    if(m_minimum != 0)
diff --git a/src/lib/cert/x509/name_constraint.h b/src/lib/cert/x509/name_constraint.h
index 345e64ff5..43d7fcbcb 100644
--- a/src/lib/cert/x509/name_constraint.h
+++ b/src/lib/cert/x509/name_constraint.h
@@ -13,19 +13,19 @@
 
 namespace Botan {
 
-   class X509_Certificate;
-
-   /**
-    * @brief X.509 GeneralName Type
-    *
-    * Handles parsing GeneralName types in their BER and canonical string
-    * encoding. Allows matching GeneralNames against each other using
-    * the rules laid out in the X.509 4.2.1.10 (Name Contraints).
-    */
-   class BOTAN_DLL GeneralName : public ASN1_Object
-      {
-      public:
-         enum MatchResult : int
+class X509_Certificate;
+
+/**
+* @brief X.509 GeneralName Type
+*
+* Handles parsing GeneralName types in their BER and canonical string
+* encoding. Allows matching GeneralNames against each other using
+* the rules laid out in the RFC 5280, sec. 4.2.1.10 (Name Contraints).
+*/
+class BOTAN_DLL GeneralName : public ASN1_Object
+   {
+   public:
+      enum MatchResult : int
             {
             All,
             Some,
@@ -34,99 +34,146 @@ namespace Botan {
             UnknownType,
             };
 
-         GeneralName() : m_type(), m_name() {}
-
-         /// Constructs a new GeneralName for its string format.
-         GeneralName(const std::string& s);
-
-         void encode_into(class DER_Encoder&) const override;
-         void decode_from(class BER_Decoder&) override;
-
-         /// Type of the name. Can be DN, DNS, IP, RFC822, URI.
-         const std::string& type() const { return m_type; }
-
-         /// The name as string. Format depends on type.
-         const std::string& name() const { return m_name; }
-
-         /// Checks whenever a given certificate (partially) matches this name.
-         MatchResult matches(const X509_Certificate&) const;
-
-      private:
-         std::string m_type;
-         std::string m_name;
+      /**
+      * Creates an empty GeneralName.
+      */
+      GeneralName() : m_type(), m_name() {}
 
-         bool matches_dns(const std::string&) const;
-         bool matches_dn(const std::string&) const;
-         bool matches_ip(const std::string&) const;
-      };
+      /**
+      * Creates a new GeneralName for its string format.
+      * @param str type and name, colon-separated, e.g., "DNS:google.com"
+      */
+      GeneralName(const std::string& str);
 
-   std::ostream& operator<<(std::ostream& os, const GeneralName& gn);
+      void encode_into(class DER_Encoder&) const override;
 
-   /**
-    * @brief A single Name Constraints
-    *
-    * THe Name Constraint extension adds a minimum and maximum path
-    * length to a GeneralName to form a constraint. The length limits
-    * are currently unused.
-    */
-   class BOTAN_DLL GeneralSubtree : public ASN1_Object
-      {
-      public:
-         GeneralSubtree() : m_base(), m_minimum(0), m_maximum(std::numeric_limits<std::size_t>::max())
-         {}
+      void decode_from(class BER_Decoder&) override;
 
-         /// Constructs a new Name Constraint
-         GeneralSubtree(GeneralName b,size_t min,size_t max)
-         : m_base(b), m_minimum(min), m_maximum(max)
-         {}
+      /**
+      * @return Type of the name. Can be DN, DNS, IP, RFC822 or URI.
+      */
+      const std::string& type() const { return m_type; }
 
-         /// Constructs a new GeneralSubtree for its string format.
-         GeneralSubtree(const std::string&);
+      /**
+      * @return The name as string. Format depends on type.
+      */
+      const std::string& name() const { return m_name; }
 
-         void encode_into(class DER_Encoder&) const override;
-         void decode_from(class BER_Decoder&) override;
+      /**
+      * Checks whether a given certificate (partially) matches this name.
+      * @param cert certificate to be matched
+      * @return the match result
+      */
+      MatchResult matches(const X509_Certificate& cert) const;
 
-         /// Name
-         GeneralName base() const { return m_base; }
+   private:
+      std::string m_type;
+      std::string m_name;
 
-         // Minimum path length
-         size_t minimum() const { return m_minimum; }
+      bool matches_dns(const std::string&) const;
+      bool matches_dn(const std::string&) const;
+      bool matches_ip(const std::string&) const;
+   };
 
-         // Maximum path length
-         size_t maximum() const { return m_maximum; }
+std::ostream& operator<<(std::ostream& os, const GeneralName& gn);
 
-      private:
-         GeneralName m_base;
-         size_t m_minimum;
-         size_t m_maximum;
-      };
-
-   std::ostream& operator<<(std::ostream& os, const GeneralSubtree& gs);
-
-   /**
-    * @brief Name Constraints
-    *
-    * Wraps the Name Constraints associated with a certificate.
-    */
-   class BOTAN_DLL NameConstraints
-      {
-      public:
-         NameConstraints() : m_permitted_subtrees(), m_excluded_subtrees() {}
-
-         NameConstraints(std::vector<GeneralSubtree>&& ps, std::vector<GeneralSubtree>&& es)
-         : m_permitted_subtrees(ps), m_excluded_subtrees(es)
-         {}
-
-         /// Permitted names
-         const std::vector<GeneralSubtree>& permitted() const { return m_permitted_subtrees; }
-
-         /// Excluded names
-         const std::vector<GeneralSubtree>& excluded() const { return m_excluded_subtrees; }
+/**
+* @brief A single Name Constraint
+*
+* The Name Constraint extension adds a minimum and maximum path
+* length to a GeneralName to form a constraint. The length limits
+* are currently unused.
+*/
+class BOTAN_DLL GeneralSubtree : public ASN1_Object
+   {
+   public:
+      /**
+      * Creates an empty name constraint.
+      */
+      GeneralSubtree() : m_base(), m_minimum(0), m_maximum(std::numeric_limits<std::size_t>::max())
+      {}
+
+      /***
+      * Creates a new name constraint.
+      * @param base name
+      * @param min minimum path length
+      * @param max maximum path length
+      */
+      GeneralSubtree(GeneralName base, size_t min, size_t max)
+      : m_base(base), m_minimum(min), m_maximum(max)
+      {}
+
+      /**
+      * Creates a new name constraint for its string format.
+      * @param str name constraint
+      */
+      GeneralSubtree(const std::string& str);
+
+      void encode_into(class DER_Encoder&) const override;
+
+      void decode_from(class BER_Decoder&) override;
+
+      /**
+      * @return name
+      */
+      GeneralName base() const { return m_base; }
+
+      /**
+      * @return minimum path length
+      */
+      size_t minimum() const { return m_minimum; }
+
+      /**
+      * @return maximum path length
+      */
+      size_t maximum() const { return m_maximum; }
+
+   private:
+      GeneralName m_base;
+      size_t m_minimum;
+      size_t m_maximum;
+   };
+
+std::ostream& operator<<(std::ostream& os, const GeneralSubtree& gs);
+
+/**
+* @brief Name Constraints
+*
+* Wraps the Name Constraints associated with a certificate.
+*/
+class BOTAN_DLL NameConstraints
+   {
+   public:
+      /**
+      * Creates an empty name NameConstraints.
+      */
+      NameConstraints() : m_permitted_subtrees(), m_excluded_subtrees() {}
+
+      /**
+      * Creates NameConstraints from a list of permitted and excluded subtrees.
+      * @param permitted_subtrees names for which the certificate is permitted
+      * @param excluded_subtrees names for which the certificate is not permitted
+      */
+      NameConstraints(std::vector<GeneralSubtree>&& permitted_subtrees,
+                    std::vector<GeneralSubtree>&& excluded_subtrees)
+      : m_permitted_subtrees(permitted_subtrees), m_excluded_subtrees(excluded_subtrees)
+      {}
+
+      /**
+      * @return permitted names
+      */
+      const std::vector<GeneralSubtree>& permitted() const { return m_permitted_subtrees; }
+
+      /**
+      * @return excluded names
+      */
+      const std::vector<GeneralSubtree>& excluded() const { return m_excluded_subtrees; }
+
+   private:
+      std::vector<GeneralSubtree> m_permitted_subtrees;
+      std::vector<GeneralSubtree> m_excluded_subtrees;
+};
 
-      private:
-        std::vector<GeneralSubtree> m_permitted_subtrees;
-        std::vector<GeneralSubtree> m_excluded_subtrees;
-      };
 }
 
 #endif
diff --git a/src/lib/cert/x509/ocsp.h b/src/lib/cert/x509/ocsp.h
index af0f81403..fe1796984 100644
--- a/src/lib/cert/x509/ocsp.h
+++ b/src/lib/cert/x509/ocsp.h
@@ -17,41 +17,91 @@ class Certificate_Store;
 
 namespace OCSP {
 
+/**
+* An OCSP request.
+*/
 class BOTAN_DLL Request
    {
    public:
+      /**
+      * Create an OCSP request.
+      * @param issuer_cert issuer certificate
+      * @param subject_cert subject certificate
+      */
       Request(const X509_Certificate& issuer_cert,
               const X509_Certificate& subject_cert) :
          m_issuer(issuer_cert),
          m_subject(subject_cert)
          {}
 
+      /**
+      * @return BER-encoded OCSP request
+      */
       std::vector<byte> BER_encode() const;
 
+      /**
+      * @return Base64-encoded OCSP request
+      */
       std::string base64_encode() const;
 
+      /**
+      * @return issuer certificate
+      */
       const X509_Certificate& issuer() const { return m_issuer; }
 
+      /**
+      * @return subject certificate
+      */
       const X509_Certificate& subject() const { return m_subject; }
    private:
       X509_Certificate m_issuer, m_subject;
    };
 
+/**
+* An OCSP response.
+*/
 class BOTAN_DLL Response
    {
    public:
+      /**
+      * Creates an empty OCSP response.
+      */
       Response() {}
 
+      /**
+      * Creates an OCSP response.
+      * @param trusted_roots trusted roots for the OCSP response
+      * @param response_bits response bits received
+      */
       Response(const Certificate_Store& trusted_roots,
-               const std::vector<byte>& response);
-
+               const std::vector<byte>& response_bits);
+
+      /**
+       * Searches the OCSP response for issuer and subject certificate.
+       * @param issuer issuer certificate
+       * @param subject subject certificate
+       * @return OCSP status code, possible values:
+       *         CERT_IS_REVOKED,
+       *         OCSP_NOT_YET_VALID,
+       *         OCSP_HAS_EXPIRED,
+       *         OCSP_RESPONSE_GOOD,
+       *         OCSP_BAD_STATUS,
+       *         OCSP_CERT_NOT_LISTED
+       */
       Certificate_Status_Code status_for(const X509_Certificate& issuer,
-                                               const X509_Certificate& subject) const;
+                                         const X509_Certificate& subject) const;
 
    private:
       std::vector<SingleResponse> m_responses;
    };
 
+/**
+* Makes an online OCSP request via HTTP and returns the OCSP response.
+* @param issuer issuer certificate
+* @param subject subject certificate
+* @param trusted_roots trusted roots for the OCSP response
+* @return OCSP response
+*/
 BOTAN_DLL Response online_check(const X509_Certificate& issuer,
                                 const X509_Certificate& subject,
                                 const Certificate_Store* trusted_roots);
diff --git a/src/lib/cert/x509/x509_crl.h b/src/lib/cert/x509/x509_crl.h
index 2e05f98fb..7373e9936 100644
--- a/src/lib/cert/x509/x509_crl.h
+++ b/src/lib/cert/x509/x509_crl.h
@@ -100,6 +100,13 @@ class BOTAN_DLL X509_CRL final : public X509_Object
       X509_CRL(const std::vector<byte>& vec,
                bool throw_on_unknown_critical = false);
 
+      /**
+      * Construct a CRL
+      * @param issuer issuer of this CRL
+      * @param thisUpdate valid from
+      * @param nextUpdate valid until
+      * @param revoked entries to be included in the CRL
+      */
       X509_CRL(const X509_DN& issuer, const X509_Time& thisUpdate,
                const X509_Time& nextUpdate, const std::vector<CRL_Entry>& revoked);
 
diff --git a/src/lib/cert/x509/x509_obj.h b/src/lib/cert/x509/x509_obj.h
index eb929451c..8b561a142 100644
--- a/src/lib/cert/x509/x509_obj.h
+++ b/src/lib/cert/x509/x509_obj.h
@@ -71,8 +71,16 @@ class BOTAN_DLL X509_Object : public ASN1_Object
       */
       bool check_signature(const Public_Key* key) const;
 
+      /**
+      * DER encode an X509_Object
+      * See @ref ASN1_Object::encode_into()
+      */
       void encode_into(class DER_Encoder& to) const override;
 
+      /**
+      * Decode a BER encoded X509_Object
+      * See @ref ASN1_Object::decode_from()
+      */
       void decode_from(class BER_Decoder& from) override;
 
       /**
diff --git a/src/lib/cert/x509/x509cert.h b/src/lib/cert/x509/x509cert.h
index d64d8fd2b..12e99c44e 100644
--- a/src/lib/cert/x509/x509cert.h
+++ b/src/lib/cert/x509/x509cert.h
@@ -236,13 +236,15 @@ class BOTAN_DLL X509_Certificate : public X509_Object
       std::string to_string() const;
 
       /**
-      * Return a fingerprint of the certificate
+      * @return a fingerprint of the certificate
+      * @param hash_name hash function used to calculate the fingerprint
       */
-      std::string fingerprint(const std::string& = "SHA-1") const;
+      std::string fingerprint(const std::string& hash_name = "SHA-1") const;
 
       /**
       * Check if a certain DNS name matches up with the information in
       * the cert
+      * @param name DNS name to match
       */
       bool matches_dns_name(const std::string& name) const;
 
@@ -272,6 +274,10 @@ class BOTAN_DLL X509_Certificate : public X509_Object
       */
       explicit X509_Certificate(const std::string& filename);
 
+      /**
+      * Create a certificate from a buffer
+      * @param in the buffer containing the DER-encoded certificate
+      */
       explicit X509_Certificate(const std::vector<byte>& in);
 
       X509_Certificate(const X509_Certificate& other) = default;
@@ -292,16 +298,30 @@ class BOTAN_DLL X509_Certificate : public X509_Object
 
 /**
 * Check two certificates for inequality
+* @param cert1 The first certificate
+* @param cert2 The second certificate
 * @return true if the arguments represent different certificates,
 * false if they are binary identical
 */
-BOTAN_DLL bool operator!=(const X509_Certificate&, const X509_Certificate&);
+BOTAN_DLL bool operator!=(const X509_Certificate& cert1, const X509_Certificate& cert2);
 
 /*
 * Data Store Extraction Operations
 */
-BOTAN_DLL X509_DN create_dn(const Data_Store&);
-BOTAN_DLL AlternativeName create_alt_name(const Data_Store&);
+
+/*
+* Create and populate a X509_DN
+* @param info data store containing DN information
+* @return DN containing attributes from data store
+*/
+BOTAN_DLL X509_DN create_dn(const Data_Store& info);
+
+/*
+* Create and populate an AlternativeName
+* @param info data store containing AlternativeName information
+* @return AlternativeName containing attributes from data store
+*/
+BOTAN_DLL AlternativeName create_alt_name(const Data_Store& info);
 
 }
 
diff --git a/src/lib/cert/x509/x509path.h b/src/lib/cert/x509/x509path.h
index 60b7fa1a2..cfcf44511 100644
--- a/src/lib/cert/x509/x509path.h
+++ b/src/lib/cert/x509/x509path.h
@@ -27,6 +27,7 @@ class BOTAN_DLL Path_Validation_Restrictions
       *        operations, eg 80 means 2^80) of a signature. Signatures
       *        weaker than this are rejected. If more than 80, SHA-1
       *        signatures are also rejected.
+      * @param ocsp_all_intermediates
       */
       Path_Validation_Restrictions(bool require_rev = false,
                                    size_t minimum_key_strength = 80,
@@ -37,6 +38,7 @@ class BOTAN_DLL Path_Validation_Restrictions
       * @param minimum_key_strength is the minimum strength (in terms of
       *        operations, eg 80 means 2^80) of a signature. Signatures
       *        weaker than this are rejected.
+      * @param ocsp_all_intermediates
       * @param trusted_hashes a set of trusted hashes. Any signatures
       *        created using a hash other than one of these will be
       *        rejected.
@@ -50,15 +52,27 @@ class BOTAN_DLL Path_Validation_Restrictions
          m_trusted_hashes(trusted_hashes),
          m_minimum_key_strength(minimum_key_strength) {}
 
+      /**
+      * @return whether revocation information is required
+      */
       bool require_revocation_information() const
          { return m_require_revocation_information; }
 
+      /**
+      * FIXME add doc
+      */
       bool ocsp_all_intermediates() const
          { return m_ocsp_all_intermediates; }
 
+      /**
+      * @return trusted signature hash functions
+      */
       const std::set<std::string>& trusted_hashes() const
          { return m_trusted_hashes; }
 
+      /**
+      * @return minimum required key strength
+      */
       size_t minimum_key_strength() const
          { return m_minimum_key_strength; }
 
@@ -105,7 +119,7 @@ class BOTAN_DLL Path_Validation_Result
       Certificate_Status_Code result() const { return m_overall; }
 
       /**
-      * Return a set of status codes for each certificate in the chain
+      * @return a set of status codes for each certificate in the chain
       */
       const std::vector<std::set<Certificate_Status_Code>>& all_statuses() const
          { return m_all_status; }
@@ -115,11 +129,24 @@ class BOTAN_DLL Path_Validation_Result
       */
       std::string result_string() const;
 
+      /**
+      * @param validation status code
+      * @return corresponding validation status message
+      */
       static const char* status_string(Certificate_Status_Code code);
 
+      /**
+      * Create a Path_Validation_Result
+      * @param status list of validation status codes
+      * @param cert_chain the certificate chain that was validated
+      */
       Path_Validation_Result(std::vector<std::set<Certificate_Status_Code>> status,
                              std::vector<std::shared_ptr<const X509_Certificate>>&& cert_chain);
 
+      /**
+      * Create a Path_Validation_Result
+      * @status status validation status code
+      */
       explicit Path_Validation_Result(Certificate_Status_Code status) : m_overall(status) {}
 
    private:
@@ -136,6 +163,12 @@ class BOTAN_DLL Path_Validation_Result
 
 /**
 * PKIX Path Validation
+* @param end_certs certificate chain to validate
+* @param restrictions path validation restrictions
+* @param certstores list of certificate stores that contain trusted certificates
+* @param hostname if not empty, compared against the DNS name in end_certs[0]
+* @param usage if not set to UNSPECIFIED, compared against the key usage in end_certs[0]
+* @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
    const std::vector<X509_Certificate>& end_certs,
@@ -146,6 +179,12 @@ Path_Validation_Result BOTAN_DLL x509_path_validate(
 
 /**
 * PKIX Path Validation
+* @param end_cert certificate to validate
+* @param restrictions path validation restrictions
+* @param certstores list of stores that contain trusted certificates
+* @param hostname if not empty, compared against the DNS name in end_cert
+* @param usage if not set to UNSPECIFIED, compared against the key usage in end_cert
+* @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
    const X509_Certificate& end_cert,
@@ -156,6 +195,12 @@ Path_Validation_Result BOTAN_DLL x509_path_validate(
 
 /**
 * PKIX Path Validation
+* @param end_cert certificate to validate
+* @param restrictions path validation restrictions
+* @param store store that contains trusted certificates
+* @param hostname if not empty, compared against the DNS name in end_cert
+* @param usage if not set to UNSPECIFIED, compared against the key usage in end_cert
+* @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
    const X509_Certificate& end_cert,
@@ -166,6 +211,12 @@ Path_Validation_Result BOTAN_DLL x509_path_validate(
 
 /**
 * PKIX Path Validation
+* @param end_certs certificate chain to validate
+* @param restrictions path validation restrictions
+* @param store store that contains trusted certificates
+* @param hostname if not empty, compared against the DNS name in end_certs[0]
+* @param usage if not set to UNSPECIFIED, compared against the key usage in end_certs[0]
+* @return result of the path validation
 */
 Path_Validation_Result BOTAN_DLL x509_path_validate(
    const std::vector<X509_Certificate>& end_certs,