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