lib-ssl-iostream: Add comment about using ssl_iostream_check_cert_validity

diff --git a/src/lib-ssl-iostream/iostream-ssl.h b/src/lib-ssl-iostream/iostream-ssl.h
index f8cfa5152554a684afde0b28e05f7af20f2fa8d9..7ef4ef003b4185fcc0edbf354b7e25a75ec57897 100644 (file)
--- a/src/lib-ssl-iostream/iostream-ssl.h
+++ b/src/lib-ssl-iostream/iostream-ssl.h
@@ -100,6 +100,16 @@ bool ssl_iostream_is_handshaked(const struct ssl_iostream *ssl_io);
 bool ssl_iostream_has_handshake_failed(const struct ssl_iostream *ssl_io);
 bool ssl_iostream_has_valid_client_cert(const struct ssl_iostream *ssl_io);
 bool ssl_iostream_has_broken_client_cert(struct ssl_iostream *ssl_io);
+/* Checks certificate validity based, also performs name checking. Called by
+   default in handshake, unless handshake callback is set with
+   ssl_iostream_check_cert_validity().
+
+   Host should be set as the name you want to validate the certificate name(s)
+   against. Usually this is the host name you connected to.
+
+   This function is same as calling ssl_iostream_has_valid_client_cert()
+   and ssl_iostream_cert_match_name().
+ */
 int ssl_iostream_check_cert_validity(struct ssl_iostream *ssl_io,
                                     const char *host, const char **error_r);
 /* Returns TRUE if the given name matches the SSL stream's certificate.