Add comments to document this header

git-svn-id: http://svn.inspircd.org/repository/trunk/inspircd@5132 e03df62e-2008-0410-955e-edbf42e46eb7

src/modules/extra/ssl_cert.h

@@ -4,20 +4,43 @@
 #include <map>
 #include <string>
 
+/** A generic container for certificate data
+ */
 typedef std::map<std::string,std::string> ssl_data;
+
+/** A shorthand way of representing an iterator into ssl_data
+ */
 typedef ssl_data::iterator ssl_data_iter;
 
+/** ssl_cert is a class which abstracts SSL certificate
+ * and key information.
+ *
+ * Because gnutls and openssl represent key information in
+ * wildly different ways, this class allows it to be accessed
+ * in a unified manner. These classes are attached to ssl-
+ * connected local users using Extensible::Extend() and the
+ * key 'ssl_cert'.
+ */
 class ssl_cert
 {
+	/** Always contains an empty string
+	 */
 	const std::string empty;
 
  public:
+	/** The data for this certificate
+	 */
 	ssl_data data;
 
+	/** Default constructor, initializes 'empty'
+	 */
 	ssl_cert() : empty("")
 	{
 	}
-
+	
+	/** Get certificate distinguished name
+	 * @return Certificate DN
+	 */
 	const std::string& GetDN()
 	{
 		ssl_data_iter ssldi = data.find("dn");
@@ -28,6 +51,9 @@ class ssl_cert
 			return empty;
 	}
 
+	/** Get Certificate issuer
+	 * @return Certificate issuer
+	 */
 	const std::string& GetIssuer()
 	{
 		ssl_data_iter ssldi = data.find("issuer");
@@ -38,6 +64,10 @@ class ssl_cert
 			return empty;
 	}
 
+	/** Get error string if an error has occured
+	 * @return The error associated with this users certificate,
+	 * or an empty string if there is no error.
+	 */
 	const std::string& GetError()
 	{
 		ssl_data_iter ssldi = data.find("error");
@@ -48,6 +78,9 @@ class ssl_cert
 			return empty;
 	}
 
+	/** Get key fingerprint.
+	 * @return The key fingerprint as a hex string.
+	 */
 	const std::string& GetFingerprint()
 	{
 		ssl_data_iter ssldi = data.find("fingerprint");
@@ -58,6 +91,10 @@ class ssl_cert
 			return empty;
 	}
 
+	/** Get trust status
+	 * @return True if this is a trusted certificate
+	 * (the certificate chain validates)
+	 */
 	bool IsTrusted()
 	{
 		ssl_data_iter ssldi = data.find("trusted");
@@ -68,6 +105,10 @@ class ssl_cert
 			return false;
 	}
 
+	/** Get validity status
+	 * @return True if the certificate itself is
+	 * correctly formed.
+	 */
 	bool IsInvalid()
 	{
 		ssl_data_iter ssldi = data.find("invalid");
@@ -78,6 +119,10 @@ class ssl_cert
 			return false;
 	}
 
+	/** Get signer status
+	 * @return True if the certificate appears to be
+	 * self-signed.
+	 */
 	bool IsUnknownSigner()
 	{
 		ssl_data_iter ssldi = data.find("unknownsigner");
@@ -88,6 +133,11 @@ class ssl_cert
 			return false;
 	}
 
+	/** Get revokation status.
+	 * @return True if the certificate is revoked.
+	 * Note that this only works properly for GnuTLS
+	 * right now.
+	 */
 	bool IsRevoked()
 	{
 		ssl_data_iter ssldi = data.find("revoked");