From 4efb8b4f7be8cdc53586d43a8f3d76acae298777 Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Wed, 22 Mar 2017 19:23:46 +0100 Subject: [PATCH] docs: Clarify the use of the GError in g_tls_database_verify_chain* Being able to determine that a certificate chain is invalid is not considered an error, but success. This might not be obvious at first due to the way the method is named and described currently. Since we cannot change the name, let's improve the description and clarify this aspect of its behaviour. https://bugzilla.gnome.org/show_bug.cgi?id=780310 --- gio/gtlsdatabase.c | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c index 16d4a3720..590aef211 100644 --- a/gio/gtlsdatabase.c +++ b/gio/gtlsdatabase.c @@ -455,8 +455,8 @@ g_tls_database_class_init (GTlsDatabaseClass *klass) * @cancellable: (nullable): a #GCancellable, or %NULL * @error: (nullable): a #GError, or %NULL * - * Verify's a certificate chain after looking up and adding any missing - * certificates to the chain. + * Determines the validity of a certificate chain after looking up and + * adding any missing certificates to the chain. * * @chain is a chain of #GTlsCertificate objects each pointing to the next * certificate in the chain by its %issuer property. The chain may initially @@ -477,6 +477,15 @@ g_tls_database_class_init (GTlsDatabaseClass *klass) * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be * used. * + * If @chain is found to be valid, then the return value will be 0. If + * @chain is found to be invalid, then the return value will indicate + * the problems found. If the function is unable to determine whether + * @chain is valid or not (eg, because @cancellable is triggered + * before it completes) then the return value will be + * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set + * accordingly. @error is not set when @chain is successfully analyzed + * but found to be invalid. + * * This function can block, use g_tls_database_verify_chain_async() to perform * the verification operation asynchronously. * @@ -532,9 +541,9 @@ g_tls_database_verify_chain (GTlsDatabase *self, * @callback: callback to call when the operation completes * @user_data: the data to pass to the callback function * - * Asynchronously verify's a certificate chain after looking up and adding - * any missing certificates to the chain. See g_tls_database_verify_chain() - * for more information. + * Asynchronously determines the validity of a certificate chain after + * looking up and adding any missing certificates to the chain. See + * g_tls_database_verify_chain() for more information. * * Since: 2.30 */ @@ -576,7 +585,17 @@ g_tls_database_verify_chain_async (GTlsDatabase *self, * @error: a #GError pointer, or %NULL * * Finish an asynchronous verify chain operation. See - * g_tls_database_verify_chain() for more information. * + * g_tls_database_verify_chain() for more information. + * + * If @chain is found to be valid, then the return value will be 0. If + * @chain is found to be invalid, then the return value will indicate + * the problems found. If the function is unable to determine whether + * @chain is valid or not (eg, because @cancellable is triggered + * before it completes) then the return value will be + * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set + * accordingly. @error is not set when @chain is successfully analyzed + * but found to be invalid. + * * Returns: the appropriate #GTlsCertificateFlags which represents the * result of verification. *