luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-26 05:56:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clarify the use of the GError in g_tls_database_verify_chain*

Browse Source 
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
This commit is contained in:
Debarshi Ray 2017-03-22 19:23:46 +01:00
parent 69e448bc28
commit 4efb8b4f7b
1 changed files with 25 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
gio/gtlsdatabase.c
View File

@ -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.
*