Package org.gnome.gio

Class TlsConnection.Builder<B extends TlsConnection.Builder<B>>

java.lang.Object

io.github.jwharm.javagi.gobject.Builder<B>

org.gnome.gobject.GObject.Builder<B>

org.gnome.gio.IOStream.Builder<B>

org.gnome.gio.TlsConnection.Builder<B>

Type Parameters:

B - the type of the Builder that is returned

All Implemented Interfaces:

BuilderInterface

Enclosing class:

TlsConnection

public static class TlsConnection.Builder<B extends TlsConnection.Builder<B>>
extends IOStream.Builder<B>

Inner class implementing a builder pattern to construct a GObject with properties.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Builder()	Default constructor for a Builder object.

Method Summary

Modifier and Type	Method	Description
TlsConnection	build()	Finish building the TlsConnection object.
B	onAcceptCertificate(TlsConnection.AcceptCertificateCallback handler)	Emitted during the TLS handshake after the peer certificate has been received.
B	setAdvertisedProtocols(String[] advertisedProtocols)	The list of application-layer protocols that the connection advertises that it is willing to speak.
B	setBaseIoStream(IOStream baseIoStream)	The GIOStream that the connection wraps.
B	setCertificate(TlsCertificate certificate)	The connection's certificate; see g_tls_connection_set_certificate().
B	setDatabase(TlsDatabase database)	The certificate database to use when verifying this TLS connection.
B	setInteraction(TlsInteraction interaction)	A GTlsInteraction object to be used when the connection or certificate database need to interact with the user.
B	setRehandshakeMode(TlsRehandshakeMode rehandshakeMode)	Deprecated.
B	setRequireCloseNotify(boolean requireCloseNotify)	Whether or not proper TLS close notification is required.
B	setUseSystemCertdb(boolean useSystemCertdb)	Deprecated.

Methods inherited from class org.gnome.gobject.GObject.Builder

onNotify

Methods inherited from class io.github.jwharm.javagi.gobject.Builder

addBuilderProperty, connect, connect, connectSignals, getArena, getNames, getValues

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Builder

protected Builder()

Default constructor for a Builder object.

Method Details

build

public TlsConnection build()

Finish building the TlsConnection object. This will call GObject.withProperties(org.gnome.glib.Type, java.lang.String[], org.gnome.gobject.Value[]) to create a new GObject instance, which is then cast to TlsConnection.

Overrides:

build in class IOStream.Builder<B extends TlsConnection.Builder<B>>

Returns:

a new instance of TlsConnection with the properties that were set in the Builder object.

setAdvertisedProtocols

public B setAdvertisedProtocols(String[] advertisedProtocols)

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

Parameters:

advertisedProtocols - the value for the advertised-protocols property

Returns:

the Builder instance is returned, to allow method chaining

setBaseIoStream

public B setBaseIoStream(IOStream baseIoStream)

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:

baseIoStream - the value for the base-io-stream property

Returns:

the Builder instance is returned, to allow method chaining

setCertificate

public B setCertificate(TlsCertificate certificate)

The connection's certificate; see g_tls_connection_set_certificate().

Parameters:

certificate - the value for the certificate property

Returns:

the Builder instance is returned, to allow method chaining

setDatabase

public B setDatabase(TlsDatabase database)

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, GTlsConnection must fall back to using the GTlsDatabase 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 GTlsDatabase that just wraps the default GTlsDatabase, you might expect that you have not changed anything, but this is not true because you may have altered the behavior of GTlsConnection 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:

database - the value for the database property

Returns:

the Builder instance is returned, to allow method chaining

setInteraction

public B setInteraction(TlsInteraction interaction)

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.

Parameters:

interaction - the value for the interaction property

Returns:

the Builder instance is returned, to allow method chaining

setRehandshakeMode

@Deprecated
public B setRehandshakeMode(TlsRehandshakeMode rehandshakeMode)

Deprecated.

The rehandshaking mode. See g_tls_connection_set_rehandshake_mode().

Parameters:

rehandshakeMode - the value for the rehandshake-mode property

Returns:

the Builder instance is returned, to allow method chaining

setRequireCloseNotify

public B setRequireCloseNotify(boolean requireCloseNotify)

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

Parameters:

requireCloseNotify - the value for the require-close-notify property

Returns:

the Builder instance is returned, to allow method chaining

setUseSystemCertdb

@Deprecated
public B setUseSystemCertdb(boolean useSystemCertdb)

Deprecated.

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

Parameters:

useSystemCertdb - the value for the use-system-certdb property

Returns:

the Builder instance is returned, to allow method chaining

onAcceptCertificate

public B onAcceptCertificate(TlsConnection.AcceptCertificateCallback handler)

Emitted during the TLS handshake after the peer certificate has been received. You can examine peerCert's certification path by calling g_tls_certificate_get_issuer() on it.

For a client-side connection, peerCert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to conn's GTlsClientConnection:validation_flags. If you would like the certificate to be accepted despite errors, return true from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with TlsError.BAD_CERTIFICATE.

GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in errors, 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 ignore TlsCertificateFlags.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.

For a server-side connection, peerCert is the certificate presented by the client, if this was requested via the server's GTlsServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns true.

Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return false from the signal handler on the first attempt, and then after the connection attempt returns a TlsError.BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return true from the signal handler the next time.

If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• TlsConnection.AcceptCertificateCallback.run(org.gnome.gio.TlsCertificate, java.util.Set<org.gnome.gio.TlsCertificateFlags>)