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

gtlsdatabase: improve documentation

Browse Source 
Because TLS certificate verification is extremely complex, the lookup
issuer function may be tempting to misuse even by experienced
developers. There is a notion that the issuer certificate will always be
used in the final certification path, but it's just not always true.
Trying to make security decisions based on the results of this function is
a trap, so let's document that.

It turns out that old versions of glib-networking actually reordered the
certificate chain to match the final verification path. This no longer
happens since a long time ago, because it was a buggy mess. Instead, we
rely on the TLS library to build the final verification path. Their path
building is not very good, but at least it's consistent. The point of
these doc updates is to clarify that only the TLS library can make
security decisions.

Document that HTTP requests may be performed to look up missing
certificates.

Finally, let's document that certificate verification using GTlsDatabase
cannot be as smart as certificate verification performed directly by
GTlsConnection.
This commit is contained in:
Michael Catanzaro 2021-08-04 09:35:16 -05:00
parent 709df8eeb4
commit 235401b056
1 changed files with 42 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
gio/gtlsdatabase.c
View File

@ -462,15 +462,11 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
* @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a #GError, or %NULL
*
* Determines the validity of a certificate chain after looking up and
* adding any missing certificates to the chain.
* Determines the validity of a certificate chain, outside the context
* of a TLS session.
*
* @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
* 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.
* certificate in the chain by its #GTlsCertificate:issuer property.
*
* @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
@ -497,8 +493,27 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
* 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.
* Prior to GLib 2.48, GLib's default TLS backend modified @chain to
* 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
* result of verification.
@ -783,14 +798,26 @@ g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase *se
* @cancellable: (nullable): a #GCancellable, 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
* of @certificate is not modified, and the two certificates are not hooked
* into a chain.
* This function can block. Use g_tls_database_lookup_certificate_issuer_async()
* to perform the lookup operation asynchronously.
*
* This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
* the lookup operation asynchronously.
* Beware this function cannot be used to build certification paths. The
* 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,
* or %NULL. Use g_object_unref() to release the certificate.