From 4db1336ff681ef69aac97844bafc8a61275f266f Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Wed, 10 Jun 2020 09:56:47 -0500 Subject: [PATCH] gtlsconnection: Improve documentation of peer-certificate[-errors] In glib-networking#127, it was reported that we don't properly implement the documented behavior of these properties. However, we cannot fix it because libsoup relies on the implemented behavior, and it's hard to change that without cascading breakage. The practical solution is to adjust our documentation to match reality. There should be no downsides to this, and compat risk of changing the documentation is much smaller than risk of changing the implementation, so I think this is the best we can make of an unfortunate situation. See glib-networking#127 for full discussion and glib-networking#129 for the regression when we attempted to match the documented behavior. --- gio/gdtlsconnection.c | 15 +++++++-------- gio/gtlsconnection.c | 15 +++++++-------- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c index c186a2613..2704133ff 100644 --- a/gio/gdtlsconnection.c +++ b/gio/gdtlsconnection.c @@ -195,9 +195,8 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface) * GDtlsConnection:peer-certificate: (nullable) * * The connection's peer's certificate, after the TLS handshake has - * completed and the certificate has been accepted. Note in - * particular that this is not yet set during the emission of - * #GDtlsConnection::accept-certificate. + * completed or failed. Note in particular that this is not yet set + * during the emission of #GDtlsConnection::accept-certificate. * * (You can watch for a #GObject::notify signal on this property to * detect when a handshake has occurred.) @@ -214,7 +213,7 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface) /** * GDtlsConnection:peer-certificate-errors: * - * The errors noticed-and-ignored while verifying + * The errors noticed while verifying * #GDtlsConnection:peer-certificate. Normally this should be 0, but * it may not be if #GDtlsClientConnection:validation-flags is not * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -494,8 +493,8 @@ g_dtls_connection_get_interaction (GDtlsConnection *conn) * g_dtls_connection_get_peer_certificate: * @conn: a #GDtlsConnection * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of + * Gets @conn's peer's certificate after the handshake has completed + * or failed. (It is not set during the emission of * #GDtlsConnection::accept-certificate.) * * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL @@ -521,8 +520,8 @@ g_dtls_connection_get_peer_certificate (GDtlsConnection *conn) * @conn: a #GDtlsConnection * * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GDtlsConnection::accept-certificate.) + * certificate, after the handshake has completed or failed. (It is + * not set during the emission of #GDtlsConnection::accept-certificate.) * * Returns: @conn's peer's certificate errors * diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c index 4d5e1c247..f01e492d5 100644 --- a/gio/gtlsconnection.c +++ b/gio/gtlsconnection.c @@ -228,9 +228,8 @@ g_tls_connection_class_init (GTlsConnectionClass *klass) * GTlsConnection:peer-certificate: (nullable) * * The connection's peer's certificate, after the TLS handshake has - * completed and the certificate has been accepted. Note in - * particular that this is not yet set during the emission of - * #GTlsConnection::accept-certificate. + * completed or failed. Note in particular that this is not yet set + * during the emission of #GTlsConnection::accept-certificate. * * (You can watch for a #GObject::notify signal on this property to * detect when a handshake has occurred.) @@ -247,7 +246,7 @@ g_tls_connection_class_init (GTlsConnectionClass *klass) /** * GTlsConnection:peer-certificate-errors: * - * The errors noticed-and-ignored while verifying + * The errors noticed while verifying * #GTlsConnection:peer-certificate. Normally this should be 0, but * it may not be if #GTlsClientConnection:validation-flags is not * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -611,8 +610,8 @@ g_tls_connection_get_interaction (GTlsConnection *conn) * g_tls_connection_get_peer_certificate: * @conn: a #GTlsConnection * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of + * Gets @conn's peer's certificate after the handshake has completed + * or failed. (It is not set during the emission of * #GTlsConnection::accept-certificate.) * * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL @@ -638,8 +637,8 @@ g_tls_connection_get_peer_certificate (GTlsConnection *conn) * @conn: a #GTlsConnection * * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GTlsConnection::accept-certificate.) + * certificate, after the handshake has completed or failed. (It is + * not set during the emission of #GTlsConnection::accept-certificate.) * * Returns: @conn's peer's certificate errors *