luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-03-23 16:10:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'mcatanzaro/issuer-docs' into 'main'

Browse Source 
Improve documentation of various TLS stuff

See merge request GNOME/glib!2211
This commit is contained in:
Philip Withnall 2021-08-05 12:14:57 +00:00
commit 7451140688
2 changed files with 61 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
gio/gtlscertificate.c
View File

@ -226,6 +226,18 @@ g_tls_certificate_class_init (GTlsCertificateClass *class)
* self-signed, or else the certificate of the issuer is not * self-signed, or else the certificate of the issuer is not
* available. * available.
* *
* Beware the issuer certificate may not be the same as the
* certificate that would actually be used to construct a valid
* certification path during certificate verification.
* [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
* why an issuer certificate cannot be naively assumed to be part of the
* the certification path (though GLib's TLS backends may not follow the
* path building strategies outlined in this RFC). Due to the complexity
* of certification path building, GLib does not provide any way to know
* which certification path will actually be used. Accordingly, this
* property cannot be used to make security-related decisions. Only
* GLib itself should make security decisions about TLS certificates.
*
* Since: 2.28 * Since: 2.28
*/ */
g_object_class_install_property (gobject_class, PROP_ISSUER, g_object_class_install_property (gobject_class, PROP_ISSUER,
@ -950,6 +962,13 @@ g_tls_certificate_get_issuer (GTlsCertificate *cert)
* (All other #GTlsCertificateFlags values will always be set or unset * (All other #GTlsCertificateFlags values will always be set or unset
* as appropriate.) * as appropriate.)
* *
* Because TLS session context is not used, #GTlsCertificate may not
* perform as many checks on the certificates as #GTlsConnection would.
* For example, certificate constraints cannot be honored, and some
* revocation checks cannot be performed. The best way to verify TLS
* certificates used by a TLS connection is to let #GTlsConnection
* handle the verification.
*
* Returns: the appropriate #GTlsCertificateFlags * Returns: the appropriate #GTlsCertificateFlags
* *
* Since: 2.28 * Since: 2.28

57
gio/gtlsdatabase.c
View File

@ -462,15 +462,11 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
* @cancellable: (nullable): a #GCancellable, or %NULL * @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a #GError, or %NULL * @error: (nullable): a #GError, or %NULL
* *
* Determines the validity of a certificate chain after looking up and * Determines the validity of a certificate chain, outside the context
* adding any missing certificates to the chain. * of a TLS session.
* *
* @chain is a chain of #GTlsCertificate objects each pointing to the next * @chain is a chain of #GTlsCertificate objects each pointing to the next
* certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially * certificate in the chain by its #GTlsCertificate:issuer property.
* consist of one or more certificates. After the verification process is
* complete, @chain may be modified by adding missing certificates, or removing
* extra certificates. If a certificate anchor was found, then it is added to
* the @chain.
* *
* @purpose describes the purpose (or usage) for which the certificate * @purpose describes the purpose (or usage) for which the certificate
* is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
@ -497,8 +493,27 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
* accordingly. @error is not set when @chain is successfully analyzed * accordingly. @error is not set when @chain is successfully analyzed
* but found to be invalid. * but found to be invalid.
* *
* This function can block, use g_tls_database_verify_chain_async() to perform * Prior to GLib 2.48, GLib's default TLS backend modified @chain to
* the verification operation asynchronously. * represent the certification path built by #GTlsDatabase during
* certificate verification by adjusting the #GTlsCertificate:issuer
* property of each certificate in @chain. Since GLib 2.48, this no
* longer occurs, so you cannot rely on #GTlsCertificate:issuer to
* represent the actual certification path used during certificate
* verification.
*
* Because TLS session context is not used, #GTlsDatabase may not
* perform as many checks on the certificates as #GTlsConnection would.
* For example, certificate constraints cannot be honored, and some
* revocation checks cannot be performed. The best way to verify TLS
* certificates used by a TLS connection is to let #GTlsConnection
* handle the verification.
*
* The TLS backend may attempt to look up and add missing certificates
* to the chain. Since GLib 2.70, this may involve HTTP requests to
* download missing certificates.
*
* This function can block. Use g_tls_database_verify_chain_async() to
* perform the verification operation asynchronously.
* *
* Returns: the appropriate #GTlsCertificateFlags which represents the * Returns: the appropriate #GTlsCertificateFlags which represents the
* result of verification. * result of verification.
@ -783,14 +798,26 @@ g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase *se
* @cancellable: (nullable): a #GCancellable, or %NULL * @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a #GError, or %NULL * @error: (nullable): a #GError, or %NULL
* *
* Look up the issuer of @certificate in the database. * Look up the issuer of @certificate in the database. The
* #GTlsCertificate:issuer property of @certificate is not modified, and
* the two certificates are not hooked into a chain.
* *
* The #GTlsCertificate:issuer property * This function can block. Use g_tls_database_lookup_certificate_issuer_async()
* of @certificate is not modified, and the two certificates are not hooked * to perform the lookup operation asynchronously.
* into a chain.
* *
* This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform * Beware this function cannot be used to build certification paths. The
* the lookup operation asynchronously. * issuer certificate returned by this function may not be the same as
* the certificate that would actually be used to construct a valid
* certification path during certificate verification.
* [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
* why an issuer certificate cannot be naively assumed to be part of the
* the certification path (though GLib's TLS backends may not follow the
* path building strategies outlined in this RFC). Due to the complexity
* of certification path building, GLib does not provide any way to know
* which certification path will actually be used when verifying a TLS
* certificate. Accordingly, this function cannot be used to make
* security-related decisions. Only GLib itself should make security
* decisions about TLS certificates.
* *
* Returns: (transfer full): a newly allocated issuer #GTlsCertificate, * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
* or %NULL. Use g_object_unref() to release the certificate. * or %NULL. Use g_object_unref() to release the certificate.