Add Doxygen comments from InSiTo to x509self.h

1 files changed, 148 insertions, 27 deletions

diff --git a/src/cert/x509/x509self.h b/src/cert/x509/x509self.h
index 2f83a12be..8e912ae83 100644
--- a/src/cert/x509/x509self.h
+++ b/src/cert/x509/x509self.h
@@ -12,60 +12,181 @@
 
 namespace Botan {
 
-/*************************************************
-* Options for X.509 Certificates                 *
-*************************************************/
+/**
+* Options for X.509 certificates.
+*/
 class BOTAN_DLL X509_Cert_Options
    {
    public:
+      /**
+      * the subject common name
+      */
       std::string common_name;
+
+      /**
+      * the subject counry
+      */
       std::string country;
+
+      /**
+      * the subject organization
+      */
       std::string organization;
+
+      /**
+      * the subject organizational unit
+      */
       std::string org_unit;
+
+      /**
+      * the subject locality
+      */
       std::string locality;
+
+      /**
+      * the subject state
+      */
       std::string state;
-      std::string serial_number;
 
-      std::string email, uri, dns, ip, xmpp;
+      /**
+      * the subject serial number
+      */
+      std::string serial_number;
 
+      /**
+      * the subject email adress
+      */
+      std::string email;
+
+      /**
+      * the subject URI
+      */
+      std::string uri;
+
+      /**
+      * the subject IPv4 address
+      */
+      std::string ip;
+
+      /**
+      * the subject DNS
+      */
+      std::string dns;
+
+      /**
+      * the subject XMPP
+      */
+      std::string xmpp;
+
+      /**
+      * the subject challenge password
+      */
       std::string challenge;
 
-      X509_Time start, end;
-
+      /**
+      * the subject notBefore
+      */
+      X509_Time start;
+      /**
+      * the subject notAfter
+      */
+      X509_Time end;
+
+      /**
+      * Indicates whether the certificate request
+      */
       bool is_CA;
+
+      /**
+      * Indicates the BasicConstraints path limit
+      */
       u32bit path_limit;
+
+      /**
+      * The key constraints for the subject public key
+      */
       Key_Constraints constraints;
+
+      /**
+      * The key extended constraints for the subject public key
+      */
       std::vector<OID> ex_constraints;
 
+      /**
+      * Check the options set in this object for validity.
+      */
       void sanity_check() const;
 
-      void CA_key(u32bit = 8);
-      void not_before(const std::string&);
-      void not_after(const std::string&);
-
-      void add_constraints(Key_Constraints);
-      void add_ex_constraint(const OID&);
-      void add_ex_constraint(const std::string&);
-
-      X509_Cert_Options(const std::string& = "",
-                        u32bit expire = 365 * 24 * 60 * 60);
+      /**
+      * Mark the certificate as a CA certificate and set the path limit.
+      * @param limit the path limit to be set in the BasicConstraints extension.
+      */
+      void CA_key(u32bit limit = 1);
+
+      /**
+      * Set the notBefore of the certificate.
+      * @param time the notBefore value of the certificate
+      */
+      void not_before(const std::string& time);
+
+      /**
+      * Set the notAfter of the certificate.
+      * @param time the notAfter value of the certificate
+      */
+      void not_after(const std::string& time);
+
+      /**
+      * Add the key constraints of the KeyUsage extension.
+      * @param constr the constraints to set
+      */
+      void add_constraints(Key_Constraints constr);
+
+      /**
+      * Add constraints to the ExtendedKeyUsage extension.
+      * @param oid the oid to add
+      */
+      void add_ex_constraint(const OID& oid);
+
+      /**
+      * Add constraints to the ExtendedKeyUsage extension.
+      * @param name the name to look up the oid to add
+      */
+      void add_ex_constraint(const std::string& name);
+
+      /**
+      * Construct a new options object
+      * @param opts define the common name of this object. An example for this
+      * parameter would be "common_name/country/organization/organizational_unit".
+      * @param expire_time the expiration time (from the current clock in seconds)
+      */
+      X509_Cert_Options(const std::string& opts = "",
+                        u32bit expire_time = 365 * 24 * 60 * 60);
    };
 
 namespace X509 {
 
-/*************************************************
-* Create a self-signed X.509 certificate         *
-*************************************************/
+/**
+* Create a self-signed X.509 certificate.
+* @param opts the options defining the certificate to create
+* @param key the private key used for signing, i.e. the key
+* associated with this self-signed certificate
+* @param rng the rng to use
+* @return the newly created self-signed certificate
+*/
 BOTAN_DLL X509_Certificate
-create_self_signed_cert(const X509_Cert_Options&,
-                        const Private_Key&,
+create_self_signed_cert(const X509_Cert_Options& opts,
+                        const Private_Key& key,
                         RandomNumberGenerator& rng);
 
-/*************************************************
-* Create a PKCS #10 certificate request          *
-*************************************************/
-BOTAN_DLL PKCS10_Request create_cert_req(const X509_Cert_Options&,
-                                         const Private_Key&,
+/**
+* Create a PKCS#10 certificate request.
+* @param opts the options defining the request to create
+* @param key the key used to sign this request
+* @param rng the rng to use
+* @return the newly created PKCS#10 request
+*/
+BOTAN_DLL PKCS10_Request create_cert_req(const X509_Cert_Options& opts,
+                                         const Private_Key& key,
                                          RandomNumberGenerator& rng);
 
 }