Class: Gio::TlsConnection

Inherits:
IOStream show all
Defined in:
(unknown)

Overview

The class structure for the GTls::Connection type.

Instance Method Summary collapse

Methods inherited from IOStream

#clear_pending, #close, #close_async, #close_finish, #closed=, #closed?, #has_pending, #input_stream, #input_stream=, #is_closed, #output_stream, #output_stream=, #set_pending, #splice_async, splice_finish

Instance Method Details

#advertised_protocols ⇒ Gio::

The list of application-layer protocols that the connection
advertises that it is willing to speak. See
g_tls_connection_set_advertised_protocols().

Returns:

  • (Gio::) —

    advertised-protocols

#advertised_protocols=(advertised_protocols) ⇒ Gio::

The list of application-layer protocols that the connection
advertises that it is willing to speak. See
g_tls_connection_set_advertised_protocols().

Parameters:

  • advertised_protocols (Gio::)

Returns:

  • (Gio::) —

    advertised-protocols

  • (Gio::) —

    advertised-protocols

#base_io_stream ⇒ Gio::IOStream

The #GIOStream that the connection wraps. The connection holds a reference
to this stream, and may run operations on the stream from other threads
throughout its lifetime. Consequently, after the #GIOStream has been
constructed, application code may only run its own operations on this
stream when no #GIOStream operations are running.

Returns:

#base_io_stream=(base_io_stream) ⇒ Gio::IOStream

The #GIOStream that the connection wraps. The connection holds a reference
to this stream, and may run operations on the stream from other threads
throughout its lifetime. Consequently, after the #GIOStream has been
constructed, application code may only run its own operations on this
stream when no #GIOStream operations are running.

Parameters:

Returns:

#certificate ⇒ Gio::TlsCertificate

The connection's certificate; see
g_tls_connection_set_certificate().

Returns:

#certificate=(certificate) ⇒ Gio::TlsCertificate

The connection's certificate; see
g_tls_connection_set_certificate().

Parameters:

Returns:

#ciphersuite_name ⇒ String

The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name().

Returns:

  • (String) —

    ciphersuite-name

#ciphersuite_name=(ciphersuite_name) ⇒ String

The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name().

Parameters:

  • ciphersuite_name (String)

Returns:

  • (String) —

    ciphersuite-name

  • (String) —

    ciphersuite-name

#database ⇒ Gio::TlsDatabase

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().

When using a non-default database, GTls::Connection must fall back to using
the GTls::Database to perform certificate verification using
g_tls_database_verify_chain(), which means certificate verification will
not be able to make use of TLS session context. This may be less secure.
For example, if you create your own GTls::Database that just wraps the
default GTls::Database, you might expect that you have not changed anything,
but this is not true because you may have altered the behavior of
GTls::Connection by causing it to use g_tls_database_verify_chain(). See the
documentation of g_tls_database_verify_chain() for more details on specific
security checks that may not be performed. Accordingly, setting a
non-default database is discouraged except for specialty applications with
unusual security requirements.

Returns:

#database=(database) ⇒ Gio::TlsDatabase

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().

When using a non-default database, GTls::Connection must fall back to using
the GTls::Database to perform certificate verification using
g_tls_database_verify_chain(), which means certificate verification will
not be able to make use of TLS session context. This may be less secure.
For example, if you create your own GTls::Database that just wraps the
default GTls::Database, you might expect that you have not changed anything,
but this is not true because you may have altered the behavior of
GTls::Connection by causing it to use g_tls_database_verify_chain(). See the
documentation of g_tls_database_verify_chain() for more details on specific
security checks that may not be performed. Accordingly, setting a
non-default database is discouraged except for specialty applications with
unusual security requirements.

Parameters:

Returns:

#emit_accept_certificate(peer_cert, errors) ⇒ Boolean

Used by GTls::Connection implementations to emit the
GTls::Connection::accept-certificate signal.

Parameters:

Returns:

  • (Boolean) —

    true if one of the signal handlers has returned
    true to accept peer_cert

#get_channel_binding_data(type, data) ⇒ Boolean

Query the TLS backend for TLS channel binding data of type for conn.

This call retrieves TLS channel binding data as specified in RFC
5056, RFC
5929, and related RFCs. The
binding data is returned in data. The data is resized by the callee
using GByte::Array buffer management and will be freed when the data
is destroyed by g_byte_array_unref(). If data is nil, it will only
check whether TLS backend is able to fetch the data (e.g. whether type
is supported by the TLS backend). It does not guarantee that the data
will be available though. That could happen if TLS connection does not
support type or the binding data is not available yet due to additional
negotiation or input required.

Parameters:

  • type (Gio::TlsChannelBindingType) —

    GTls::ChannelBindingType type of data to fetch

  • data (Array<Integer>) —

    GByte::Array is
    filled with the binding data, or nil

Returns:

  • (Boolean) —

    true on success, false otherwise

#handshake(cancellable) ⇒ Boolean

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),
GTls::Connection will handle this for you automatically when you try
to send or receive data on the connection. You can call
g_tls_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_tls_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.

When using a GTls::Connection created by #GSocketClient, the
GSocket::Client performs the initial handshake, so calling this
function manually is not recommended.

GTls::Connection::accept_certificate may be emitted during the
handshake.

Parameters:

Returns:

  • (Boolean) —

    success or failure

#handshake_async(io_priority, cancellable, callback, user_data) ⇒ nil

Asynchronously performs a TLS handshake on conn. See
g_tls_connection_handshake() for more information.

Parameters:

  • io_priority (Integer) —

    the [I/O priority][io-priority] of the request

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    callback to call when the handshake is complete

  • user_data (GObject) —

    the data to pass to the callback function

Returns:

  • (nil)

#handshake_finish(result) ⇒ Boolean

Finish an asynchronous TLS handshake operation. See
g_tls_connection_handshake() for more information.
case error will be set.

Parameters:

Returns:

  • (Boolean) —

    true on success, false on failure, in which

#interaction ⇒ Gio::TlsInteraction

A GTls::Interaction 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.

Returns:

#interaction=(interaction) ⇒ Gio::TlsInteraction

A GTls::Interaction 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.

Parameters:

Returns:

#negotiated_protocol ⇒ String

The application-layer protocol negotiated during the TLS
handshake. See g_tls_connection_get_negotiated_protocol().

Returns:

  • (String) —

    negotiated-protocol

#negotiated_protocol=(negotiated_protocol) ⇒ String

The application-layer protocol negotiated during the TLS
handshake. See g_tls_connection_get_negotiated_protocol().

Parameters:

  • negotiated_protocol (String)

Returns:

  • (String) —

    negotiated-protocol

  • (String) —

    negotiated-protocol

#peer_certificate ⇒ Gio::TlsCertificate

The connection's peer's certificate, after the TLS handshake has
completed or failed. Note in particular that this is not yet set
during the emission of GTls::Connection::accept-certificate.

(You can watch for a #GObject::notify signal on this property to
detect when a handshake has occurred.)

Returns:

#peer_certificate=(peer_certificate) ⇒ Gio::TlsCertificate

The connection's peer's certificate, after the TLS handshake has
completed or failed. Note in particular that this is not yet set
during the emission of GTls::Connection::accept-certificate.

(You can watch for a #GObject::notify signal on this property to
detect when a handshake has occurred.)

Parameters:

Returns:

#peer_certificate_errors ⇒ Gio::TlsCertificateFlags

The errors noticed while verifying
GTls::Connection:peer-certificate. Normally this should be 0, but
it may not be if GTls::ClientConnection:validation-flags is not
%G_TLS_CERTIFICATE_VALIDATE_ALL, or if
GTls::Connection::accept-certificate overrode the default
behavior.

GLib guarantees that if certificate verification fails, at least
one error will be set, but it does not guarantee that all possible
errors will be set. Accordingly, you may not safely decide to
ignore any particular type of error. For example, it would be
incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
expired certificates, because this could potentially be the only
error flag set even if other problems exist with the certificate.

Returns:

#peer_certificate_errors=(peer_certificate_errors) ⇒ Gio::TlsCertificateFlags

The errors noticed while verifying
GTls::Connection:peer-certificate. Normally this should be 0, but
it may not be if GTls::ClientConnection:validation-flags is not
%G_TLS_CERTIFICATE_VALIDATE_ALL, or if
GTls::Connection::accept-certificate overrode the default
behavior.

GLib guarantees that if certificate verification fails, at least
one error will be set, but it does not guarantee that all possible
errors will be set. Accordingly, you may not safely decide to
ignore any particular type of error. For example, it would be
incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
expired certificates, because this could potentially be the only
error flag set even if other problems exist with the certificate.

Parameters:

Returns:

#protocol_version ⇒ Gio::TlsProtocolVersion

The TLS protocol version in use. See g_tls_connection_get_protocol_version().

Returns:

#protocol_version=(protocol_version) ⇒ Gio::TlsProtocolVersion

The TLS protocol version in use. See g_tls_connection_get_protocol_version().

Parameters:

Returns:

#rehandshake_mode ⇒ Gio::TlsRehandshakeMode

The rehandshaking mode. See
g_tls_connection_set_rehandshake_mode().

Returns:

#rehandshake_mode=(rehandshake_mode) ⇒ Gio::TlsRehandshakeMode

The rehandshaking mode. See
g_tls_connection_set_rehandshake_mode().

Parameters:

Returns:

#require_close_notify ⇒ Boolean

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.
notification.

Returns:

  • (Boolean) —

    true if conn requires a proper TLS close

#require_close_notify=(require_close_notify) ⇒ Boolean

Whether or not proper TLS close notification is required.
See g_tls_connection_set_require_close_notify().

Parameters:

  • require_close_notify (Boolean)

Returns:

  • (Boolean) —

    require-close-notify

  • (Boolean) —

    require-close-notify

#require_close_notify? ⇒ Boolean

Whether or not proper TLS close notification is required.
See g_tls_connection_set_require_close_notify().

Returns:

  • (Boolean) —

    require-close-notify

#use_system_certdb ⇒ Boolean

Gets whether conn uses the system certificate database to verify
peer certificates. See g_tls_connection_set_use_system_certdb().

Returns:

  • (Boolean) —

    whether conn uses the system certificate database

#use_system_certdb=(use_system_certdb) ⇒ Boolean

Whether or not the system certificate database will be used to
verify peer certificates. See
g_tls_connection_set_use_system_certdb().

Parameters:

  • use_system_certdb (Boolean)

Returns:

  • (Boolean) —

    use-system-certdb

  • (Boolean) —

    use-system-certdb

#use_system_certdb? ⇒ Boolean

Whether or not the system certificate database will be used to
verify peer certificates. See
g_tls_connection_set_use_system_certdb().

Returns:

  • (Boolean) —

    use-system-certdb