From 33c9c305e30aea9d3147882bac07df373a5043b4 Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Mon, 4 May 2020 17:13:39 -0500 Subject: [PATCH] Improve documentation of g_tls_database_verify_chain() It is critical to mention how the identity parameter is expected to be handled. In particular, if identity is not passed, then the identity of the server certificate will not be checked at all. This is in contrast to the connection-level APIs, which are supposed to be fail-safe. The database and certificate-level APIs are more manual. --- gio/gtlsdatabase.c | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c index f06dabf0a..256369da3 100644 --- a/gio/gtlsdatabase.c +++ b/gio/gtlsdatabase.c @@ -473,9 +473,13 @@ g_tls_database_class_init (GTlsDatabaseClass *klass) * which means that the certificate is being used to authenticate a server * (and we are acting as the client). * - * The @identity is used to check for pinned certificates (trust exceptions) - * in the database. These will override the normal verification process on a - * host by host basis. + * The @identity is used to ensure the server certificate is valid for + * the expected peer identity. If the identity does not match the + * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the + * return value. If @identity is %NULL, that bit will never be set in + * the return value. The peer identity may also be used to check for + * pinned certificates (trust exceptions) in the database. These may + * override the normal verification process on a host-by-host basis. * * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be * used.