Functions
g_dtls_connection_set_certificate ()
void
g_dtls_connection_set_certificate (GDtlsConnection *conn,
GTlsCertificate *certificate);
This sets the certificate that conn
will present to its peer
during the TLS handshake. For a GDtlsServerConnection, it is
mandatory to set this, and that will normally be done at construct
time.
For a GDtlsClientConnection, 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_dtls_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_dtls_client_connection_get_accepted_cas() will return
non-NULL.)
Since: 2.48
g_dtls_connection_get_peer_certificate ()
GTlsCertificate *
g_dtls_connection_get_peer_certificate
(GDtlsConnection *conn);
Gets conn
's peer's certificate after the handshake has completed.
(It is not set during the emission of
“accept-certificate”.)
Returns
conn
's peer's certificate, or NULL.
[transfer none]
Since: 2.48
g_dtls_connection_get_peer_certificate_errors ()
GTlsCertificateFlags
g_dtls_connection_get_peer_certificate_errors
(GDtlsConnection *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”.)
Returns
conn
's peer's certificate errors
Since: 2.48
g_dtls_connection_set_require_close_notify ()
void
g_dtls_connection_set_require_close_notify
(GDtlsConnection *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 may be omitted. You
can use g_dtls_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
GDatagramBased, 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_dtls_connection_close_async() on
conn
itself, 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-socket” rather
than closing conn
itself.
Since: 2.48
g_dtls_connection_get_require_close_notify ()
gboolean
g_dtls_connection_get_require_close_notify
(GDtlsConnection *conn);
Tests whether or not conn
expects a proper TLS close notification
when the connection is closed. See
g_dtls_connection_set_require_close_notify() for details.
Returns
TRUE if conn
requires a proper TLS close notification.
Since: 2.48
g_dtls_connection_set_rehandshake_mode ()
void
g_dtls_connection_set_rehandshake_mode
(GDtlsConnection *conn,
GTlsRehandshakeMode mode);
g_dtls_connection_set_rehandshake_mode has been deprecated since version 2.60. and should not be used in newly-written code.
Changing the rehandshake mode is no longer
required for compatibility. Also, rehandshaking has been removed
from the TLS protocol in TLS 1.3.
Since GLib 2.64, changing the rehandshake mode is no longer supported
and will have no effect. With TLS 1.3, rehandshaking has been removed from
the TLS protocol, replaced by separate post-handshake authentication and
rekey operations.
Since: 2.48
g_dtls_connection_get_rehandshake_mode ()
GTlsRehandshakeMode
g_dtls_connection_get_rehandshake_mode
(GDtlsConnection *conn);
g_dtls_connection_get_rehandshake_mode has been deprecated since version 2.64. and should not be used in newly-written code.
Changing the rehandshake mode is no longer
required for compatibility. Also, rehandshaking has been removed
from the TLS protocol in TLS 1.3.
Gets conn
rehandshaking mode. See
g_dtls_connection_set_rehandshake_mode() for details.
Since: 2.48
g_dtls_connection_set_advertised_protocols ()
void
g_dtls_connection_set_advertised_protocols
(GDtlsConnection *conn,
const gchar * const *protocols);
Sets the list of application-layer protocols to advertise that the
caller is willing to speak on this connection. The
Application-Layer Protocol Negotiation (ALPN) extension will be
used to negotiate a compatible protocol with the peer; use
g_dtls_connection_get_negotiated_protocol() to find the negotiated
protocol after the handshake. Specifying NULL for the the value
of protocols
will disable ALPN negotiation.
See IANA TLS ALPN Protocol IDs
for a list of registered protocol IDs.
Since: 2.60
g_dtls_connection_get_negotiated_protocol ()
const gchar *
g_dtls_connection_get_negotiated_protocol
(GDtlsConnection *conn);
Gets the name of the application-layer protocol negotiated during
the handshake.
If the peer did not use the ALPN extension, or did not advertise a
protocol that matched one of conn
's protocols, or the TLS backend
does not support ALPN, then this will be NULL. See
g_dtls_connection_set_advertised_protocols().
Returns
the negotiated protocol, or NULL.
[nullable]
Since: 2.60
g_dtls_connection_get_interaction ()
GTlsInteraction *
g_dtls_connection_get_interaction (GDtlsConnection *conn);
Get the object that will be used to interact with the user. It will be used
for things like prompting the user for passwords. If NULL is returned, then
no user interaction will occur for this connection.
Returns
The interaction object.
[transfer none]
Since: 2.48
g_dtls_connection_set_interaction ()
void
g_dtls_connection_set_interaction (GDtlsConnection *conn,
GTlsInteraction *interaction);
Set the object that will be used to interact with the user. It will be used
for things like prompting the user for passwords.
The interaction
argument will normally be a derived subclass of
GTlsInteraction. NULL can also be provided if no user interaction
should occur for this connection.
Since: 2.48
g_dtls_connection_handshake ()
gboolean
g_dtls_connection_handshake (GDtlsConnection *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, GDtlsConnection will handle this for you automatically
when you try to send or receive data on the connection. You can call
g_dtls_connection_handshake() manually if you want to know whether
the initial handshake succeeded or failed (as opposed to just
immediately trying to use conn
to read or write, in which case,
if it fails, it may not be possible to tell if it failed before
or after completing the handshake), but beware that servers may reject
client authentication after the handshake has completed, so a
successful handshake does not indicate the connection will be usable.
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.
Previously, calling g_dtls_connection_handshake() after the initial
handshake would trigger a rehandshake; however, this usage was
deprecated in GLib 2.60 because rehandshaking was removed from the
TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after
the initial handshake will no longer do anything.
“accept_certificate” may be emitted during the
handshake.
Returns
success or failure
Since: 2.48
g_dtls_connection_handshake_finish ()
gboolean
g_dtls_connection_handshake_finish (GDtlsConnection *conn,
GAsyncResult *result,
GError **error);
Finish an asynchronous TLS handshake operation. See
g_dtls_connection_handshake() for more information.
Returns
TRUE on success, FALSE on failure, in which
case error
will be set.
Since: 2.48
g_dtls_connection_shutdown_finish ()
gboolean
g_dtls_connection_shutdown_finish (GDtlsConnection *conn,
GAsyncResult *result,
GError **error);
Finish an asynchronous TLS shutdown operation. See
g_dtls_connection_shutdown() for more information.
Returns
TRUE on success, FALSE on failure, in which
case error
will be set
Since: 2.48
g_dtls_connection_close ()
gboolean
g_dtls_connection_close (GDtlsConnection *conn,
GCancellable *cancellable,
GError **error);
Close the DTLS connection. This is equivalent to calling
g_dtls_connection_shutdown() to shut down both sides of the connection.
Closing a GDtlsConnection waits for all buffered but untransmitted data to
be sent before it completes. It then sends a close_notify DTLS alert to the
peer and may wait for a close_notify to be received from the peer. It does
not close the underlying “base-socket”; that must be closed
separately.
Once conn
is closed, all other operations will return G_IO_ERROR_CLOSED.
Closing a GDtlsConnection multiple times will not return an error.
GDtlsConnections will be automatically closed when the last reference is
dropped, but you might want to call this function to make sure resources are
released as early as possible.
If cancellable
is cancelled, the GDtlsConnection may be left
partially-closed and any pending untransmitted data may be lost. Call
g_dtls_connection_close() again to complete closing the GDtlsConnection.
Returns
TRUE on success, FALSE otherwise
Since: 2.48
g_dtls_connection_close_finish ()
gboolean
g_dtls_connection_close_finish (GDtlsConnection *conn,
GAsyncResult *result,
GError **error);
Finish an asynchronous TLS close operation. See g_dtls_connection_close()
for more information.
Returns
TRUE on success, FALSE on failure, in which
case error
will be set
Since: 2.48
Property Details
The “advertised-protocols” property
“advertised-protocols” GStrv
The list of application-layer protocols that the connection
advertises that it is willing to speak. See
g_dtls_connection_set_advertised_protocols().
Owner: GDtlsConnection
Flags: Read / Write
Since: 2.60
The “database” property
“database” GTlsDatabase *
The certificate database to use when verifying this TLS connection.
If no certificate database is set, then the default database will be
used. See g_tls_backend_get_default_database().
Owner: GDtlsConnection
Flags: Read / Write
Since: 2.48
The “interaction” property
“interaction” GTlsInteraction *
A GTlsInteraction object to be used when the connection or certificate
database need to interact with the user. This will be used to prompt the
user for passwords where necessary.
Owner: GDtlsConnection
Flags: Read / Write
Since: 2.48
The “negotiated-protocol” property
“negotiated-protocol” gchar *
The application-layer protocol negotiated during the TLS
handshake. See g_dtls_connection_get_negotiated_protocol().
Owner: GDtlsConnection
Flags: Read
Default value: NULL
Since: 2.60
The “peer-certificate” property
“peer-certificate” GTlsCertificate *
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
“accept-certificate”.
(You can watch for a “notify” signal on this property to
detect when a handshake has occurred.)
Owner: GDtlsConnection
Flags: Read
Since: 2.48
The “rehandshake-mode” property
“rehandshake-mode” GTlsRehandshakeMode
The rehandshaking mode. See
g_dtls_connection_set_rehandshake_mode().
GDtlsConnection:rehandshake-mode has been deprecated since version 2.60 and should not be used in newly-written code.
The rehandshake mode is ignored.
Owner: GDtlsConnection
Flags: Read / Write / Construct
Default value: G_TLS_REHANDSHAKE_NEVER
Since: 2.48
The “require-close-notify” property
“require-close-notify” gboolean
Whether or not proper TLS close notification is required.
See g_dtls_connection_set_require_close_notify().
Owner: GDtlsConnection
Flags: Read / Write / Construct
Default value: TRUE
Since: 2.48