![]() |
![]() |
![]() |
GIO Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <gio/gio.h> GTlsConnection; void g_tls_connection_set_certificate (GTlsConnection *conn, GTlsCertificate *certificate); GTlsCertificate * g_tls_connection_get_certificate (GTlsConnection *conn); GTlsCertificate * g_tls_connection_get_peer_certificate (GTlsConnection *conn); GTlsCertificateFlags g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn); void g_tls_connection_set_require_close_notify (GTlsConnection *conn, gboolean require_close_notify); gboolean g_tls_connection_get_require_close_notify (GTlsConnection *conn); enum GTlsRehandshakeMode; void g_tls_connection_set_rehandshake_mode (GTlsConnection *conn, GTlsRehandshakeMode mode); GTlsRehandshakeMode g_tls_connection_get_rehandshake_mode (GTlsConnection *conn); void g_tls_connection_set_use_system_certdb (GTlsConnection *conn, gboolean use_system_certdb); gboolean g_tls_connection_get_use_system_certdb (GTlsConnection *conn); gboolean g_tls_connection_handshake (GTlsConnection *conn, GCancellable *cancellable, GError **error); void g_tls_connection_handshake_async (GTlsConnection *conn, int io_priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean g_tls_connection_handshake_finish (GTlsConnection *conn, GAsyncResult *result, GError **error); gboolean g_tls_connection_emit_accept_certificate (GTlsConnection *conn, GTlsCertificate *peer_cert, GTlsCertificateFlags errors);
GTlsConnection is the base TLS connection class type, which wraps a GIOStream and provides TLS encryption on top of it. Its subclasses, GTlsClientConnection and GTlsServerConnection, implement client-side and server-side TLS, respectively.
typedef struct { GIOStream parent_instance; GTlsConnectionPrivate *priv; } GTlsConnection;
TLS connection. This is an abstract type that will be subclassed by a TLS-library-specific subtype.
Since 2.28
void g_tls_connection_set_certificate (GTlsConnection *conn, GTlsCertificate *certificate);
This sets the certificate that conn
will present to its peer
during the TLS handshake. For a GTlsServerConnection, it is
mandatory to set this, and that will normally be done at construct
time.
For a GTlsClientConnection, this is optional. If a handshake fails
with G_TLS_ERROR_CERTIFICATE_REQUIRED
, that means that the server
requires a certificate, and if you try connecting again, you should
call this method first. You can call
g_tls_client_connection_get_accepted_cas()
on the failed connection
to get a list of Certificate Authorities that the server will
accept certificates from.
(It is also possible that a server will allow the connection with
or without a certificate; in that case, if you don't provide a
certificate, you can tell that the server requested one by the fact
that g_tls_client_connection_get_accepted_cas()
will return
non-NULL
.)
|
a GTlsConnection |
|
the certificate to use for conn
|
Since 2.28
GTlsCertificate * g_tls_connection_get_certificate (GTlsConnection *conn);
Gets conn
's certificate, as set by
g_tls_connection_set_certificate()
.
|
a GTlsConnection |
Returns : |
conn 's certificate, or NULL . transfer none. |
Since 2.28
GTlsCertificate * g_tls_connection_get_peer_certificate (GTlsConnection *conn);
Gets conn
's peer's certificate after the handshake has completed.
(It is not set during the emission of
"accept-certificate".)
|
a GTlsConnection |
Returns : |
conn 's peer's certificate, or NULL . transfer none. |
Since 2.28
GTlsCertificateFlags g_tls_connection_get_peer_certificate_errors (GTlsConnection *conn);
Gets the errors associated with validating conn
's peer's
certificate, after the handshake has completed. (It is not set
during the emission of "accept-certificate".)
|
a GTlsConnection |
Returns : |
conn 's peer's certificate errors
|
Since 2.28
void g_tls_connection_set_require_close_notify (GTlsConnection *conn, gboolean require_close_notify);
Sets whether or not conn
expects a proper TLS close notification
before the connection is closed. If this is TRUE
(the default),
then conn
will expect to receive a TLS close notification from its
peer before the connection is closed, and will return a
G_TLS_ERROR_EOF
error if the connection is closed without proper
notification (since this may indicate a network error, or
man-in-the-middle attack).
In some protocols, the application will know whether or not the
connection was closed cleanly based on application-level data
(because the application-level data includes a length field, or is
somehow self-delimiting); in this case, the close notify is
redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
in TLS 1.0 it is technically an error, but often done anyway.) You
can use g_tls_connection_set_require_close_notify()
to tell conn
to allow an "unannounced" connection close, in which case the close
will show up as a 0-length read, as in a non-TLS
GSocketConnection, and it is up to the application to check that
the data has been fully received.
Note that this only affects the behavior when the peer closes the
connection; when the application calls g_io_stream_close()
itself
on conn
, this will send a close notification regardless of the
setting of this property. If you explicitly want to do an unclean
close, you can close conn
's "base-io-stream" rather
than closing conn
itself.
|
a GTlsConnection |
|
whether or not to require close notification |
Since 2.28
gboolean g_tls_connection_get_require_close_notify (GTlsConnection *conn);
Tests whether or not conn
expects a proper TLS close notification
when the connection is closed. See
g_tls_connection_set_require_close_notify()
for details.
|
a GTlsConnection |
Returns : |
TRUE if conn requires a proper TLS close
notification.
|
Since 2.28
typedef enum { G_TLS_REHANDSHAKE_NEVER, G_TLS_REHANDSHAKE_SAFELY, G_TLS_REHANDSHAKE_UNSAFELY } GTlsRehandshakeMode;
When to allow rehandshaking. See
g_tls_connection_set_rehandshake_mode()
.
Never allow rehandshaking | |
Allow safe rehandshaking only | |
Allow unsafe rehandshaking |
Since 2.28
void g_tls_connection_set_rehandshake_mode (GTlsConnection *conn, GTlsRehandshakeMode mode);
Sets how conn
behaves with respect to rehandshaking requests.
G_TLS_REHANDSHAKE_NEVER
means that it will never agree to
rehandshake after the initial handshake is complete. (For a client,
this means it will refuse rehandshake requests from the server, and
for a server, this means it will close the connection with an error
if the client attempts to rehandshake.)
G_TLS_REHANDSHAKE_SAFELY
means that the connection will allow a
rehandshake only if the other end of the connection supports the
TLS renegotiation_info
extension. This is the
default behavior, but means that rehandshaking will not work
against older implementations that do not support that extension.
G_TLS_REHANDSHAKE_UNSAFELY
means that the connection will allow
rehandshaking even without the
renegotiation_info
extension. On the server side
in particular, this is not recommended, since it leaves the server
open to certain attacks. However, this mode is necessary if you
need to allow renegotiation with older client software.
|
a GTlsConnection |
|
the rehandshaking mode |
Since 2.28
GTlsRehandshakeMode g_tls_connection_get_rehandshake_mode (GTlsConnection *conn);
Gets conn
rehandshaking mode. See
g_tls_connection_set_rehandshake()
for details.
|
a GTlsConnection |
Returns : |
conn 's rehandshaking mode
|
Since 2.28
void g_tls_connection_set_use_system_certdb (GTlsConnection *conn, gboolean use_system_certdb);
Sets whether conn
uses the system certificate database to verify
peer certificates. This is TRUE
by default. If set to FALSE
, then
peer certificate validation will always set the
G_TLS_CERTIFICATE_UNKNOWN_CA
error (meaning
"accept-certificate" will always be emitted on
client-side connections, unless that bit is not set in
"validation-flags").
|
a GTlsConnection |
|
whether to use the system certificate database |
Since 2.28
gboolean g_tls_connection_get_use_system_certdb (GTlsConnection *conn);
Gets whether conn
uses the system certificate database to verify
peer certificates. See g_tls_connection_set_use_system_certdb()
.
|
a GTlsConnection |
Returns : |
whether conn uses the system certificate database
|
Since 2.28
gboolean g_tls_connection_handshake (GTlsConnection *conn, GCancellable *cancellable, GError **error);
Attempts a TLS handshake on conn
.
On the client side, it is never necessary to call this method;
although the connection needs to perform a handshake after
connecting (or after sending a "STARTTLS"-type command) and may
need to rehandshake later if the server requests it,
GTlsConnection will handle this for you automatically when you try
to send or receive data on the connection. However, you can call
g_tls_connection_handshake()
manually if you want to know for sure
whether the initial handshake succeeded or failed (as opposed to
just immediately trying to write to conn
's output stream, in which
case if it fails, it may not be possible to tell if it failed
before or after completing the handshake).
Likewise, on the server side, although a handshake is necessary at
the beginning of the communication, you do not need to call this
function explicitly unless you want clearer error reporting.
However, you may call g_tls_connection_handshake()
later on to
renegotiate parameters (encryption methods, etc) with the client.
"accept_certificate" may be emitted during the handshake.
|
a GTlsConnection |
|
a GCancellable, or NULL
|
|
a GError, or NULL
|
Returns : |
success or failure |
Since 2.28
void g_tls_connection_handshake_async (GTlsConnection *conn, int io_priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data);
Asynchronously performs a TLS handshake on conn
. See
g_tls_connection_handshake()
for more information.
|
a GTlsConnection |
|
the I/O priority of the request. |
|
a GCancellable, or NULL
|
|
callback to call when the handshake is complete |
|
the data to pass to the callback function |
Since 2.28
gboolean g_tls_connection_handshake_finish (GTlsConnection *conn, GAsyncResult *result, GError **error);
Finish an asynchronous TLS handshake operation. See
g_tls_connection_handshake()
for more information.
|
a GTlsConnection |
|
a GAsyncResult. |
|
a GError pointer, or NULL
|
Returns : |
TRUE on success, FALSE on failure, in which
case error will be set.
|
Since 2.28
gboolean g_tls_connection_emit_accept_certificate (GTlsConnection *conn, GTlsCertificate *peer_cert, GTlsCertificateFlags errors);
Used by GTlsConnection implementations to emit the "accept-certificate" signal.
|
a GTlsConnection |
|
the peer's GTlsCertificate |
|
the problems with peer_cert
|
Returns : |
TRUE if one of the signal handlers has returned
TRUE to accept peer_cert
|
Since 2.28