From afae15f7cf212c993da8264a4ae89cf8729b3f86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Remko=20Tron=C3=A7on?= <git@el-tramo.be>
Date: Tue, 9 Nov 2010 23:12:48 +0100
Subject: Added Doxygen documentation for some certificate APIs.


diff --git a/Swiften/Client/Client.h b/Swiften/Client/Client.h
index 1a6700e..fa45fdd 100644
--- a/Swiften/Client/Client.h
+++ b/Swiften/Client/Client.h
@@ -127,6 +127,12 @@ namespace Swift {
 				return discoManager;
 			}
 
+			/**
+			 * Configures the client to always trust a non-validating
+			 * TLS certificate from the server.
+			 * This is equivalent to setting a BlindCertificateTrustChecker
+			 * using setCertificateTrustChecker().
+			 */
 			void setAlwaysTrustCertificates();
 		
 		public:
diff --git a/Swiften/Client/CoreClient.h b/Swiften/Client/CoreClient.h
index 211f84f..628ced0 100644
--- a/Swiften/Client/CoreClient.h
+++ b/Swiften/Client/CoreClient.h
@@ -133,6 +133,14 @@ namespace Swift {
 				return stanzaChannel_;
 			}
 
+			/**
+			 * Sets the certificate trust checker.
+			 *
+			 * This checker will be called when the server sends a
+			 * TLS certificate that does not validate. If the trust checker
+			 * says the certificate is trusted, then connecting will proceed;
+			 * if not, the connection will end with an error.
+			 */
 			void setCertificateTrustChecker(CertificateTrustChecker*);
 
 		public:
diff --git a/Swiften/TLS/BlindCertificateTrustChecker.h b/Swiften/TLS/BlindCertificateTrustChecker.h
index 26a7f94..fc7fbe8 100644
--- a/Swiften/TLS/BlindCertificateTrustChecker.h
+++ b/Swiften/TLS/BlindCertificateTrustChecker.h
@@ -9,6 +9,14 @@
 #include "Swiften/TLS/CertificateTrustChecker.h"
 
 namespace Swift {
+	/**
+	 * A certificate trust checker that trusts any ceritficate.
+	 *
+	 * This can be used to ignore any TLS certificate errors occurring 
+	 * during connection.
+	 *
+	 * \see Client::setAlwaysTrustCertificates()
+	 */
 	class BlindCertificateTrustChecker : public CertificateTrustChecker {
 		public:
 			virtual bool isCertificateTrusted(Certificate::ref, const String&) {
diff --git a/Swiften/TLS/Certificate.h b/Swiften/TLS/Certificate.h
index 4a3cc8b..89c1de6 100644
--- a/Swiften/TLS/Certificate.h
+++ b/Swiften/TLS/Certificate.h
@@ -18,6 +18,10 @@ namespace Swift {
 
 			virtual ~Certificate();
 
+			/**
+			 * Returns the textual representation of the full Subject
+			 * name.
+			 */
 			virtual String getSubjectName() const = 0;
 
 			virtual std::vector<String> getCommonNames() const = 0;
diff --git a/Swiften/TLS/CertificateTrustChecker.h b/Swiften/TLS/CertificateTrustChecker.h
index 070c4bb..7400dac 100644
--- a/Swiften/TLS/CertificateTrustChecker.h
+++ b/Swiften/TLS/CertificateTrustChecker.h
@@ -12,10 +12,18 @@
 #include "Swiften/TLS/Certificate.h"
 
 namespace Swift {
+	/**
+	 * A class to implement a check for certificate trust.
+	 */
 	class CertificateTrustChecker {
 		public:
 			virtual ~CertificateTrustChecker();
 
+			/**
+			 * This method is called to find out whether a certificate is
+			 * trusted. This usually happens when a certificate's validation
+			 * fails, to check whether to proceed with the connection or not.
+			 */
 			virtual bool isCertificateTrusted(Certificate::ref certificate, const String& domain) = 0;
 	};
 }
-- 
cgit v0.10.2-6-g49f6