[gnutls-devel] [PATCH] improve docs for gnutls_certificate_verify_peers*()

[Daniel Kahn Gillmor]

The gnutls_certificate_verify_peers{,2,3}() functions all return
GNUTLS_E_SUCCESS (0) even in situations when the peer's certificate
was not verified.  This is explained in the first paragraphs
("i.e. failure to trust a certificate does not imply a negative return
value"), but the Returns: line isn't comparably clear.
---
 lib/cert.c | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/lib/cert.c b/lib/cert.c
index fb01d1b..2d79c96 100644
--- a/lib/cert.c
+++ b/lib/cert.c
@@ -597,7 +597,9 @@ _gnutls_openpgp_crt_verify_peers(gnutls_session_t session,
  * the verified certificate belongs to the actual peer, see gnutls_x509_crt_check_hostname(),
  * or use gnutls_certificate_verify_peers3().
  *
- * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0) on success.
+ * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0)
+ * when the peer's certificate was successfully parsed, whether or not
+ * it was verified.
  **/
 int
 gnutls_certificate_verify_peers2(gnutls_session_t session,
@@ -629,7 +631,9 @@ gnutls_certificate_verify_peers2(gnutls_session_t session,
  * In order to verify the purpose of the end-certificate (by checking the extended
  * key usage), use gnutls_certificate_verify_peers().
  *
- * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0) on success.
+ * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0) 
+ * when the peer's certificate was successfully parsed, whether or not
+ * it was verified.
  *
  * Since: 3.1.4
  **/
@@ -673,7 +677,9 @@ gnutls_typed_vdata_st data;
  * usage PKIX extension, it will be required to be have the provided key purpose 
  * or be marked for any purpose, otherwise verification will fail with %GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE status.
  *
- * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0) on success.
+ * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0)
+ * when the peer's certificate was successfully parsed, whether or not
+ * it was verified.
  *
  * Since: 3.3.0
  **/
-- 
2.5.1