Package org.gnome.gio

Interface TlsClientConnection

All Superinterfaces:

Proxy

All Known Implementing Classes:

TlsClientConnection.TlsClientConnection$Impl

@Generated("io.github.jwharm.JavaGI")
public interface TlsClientConnection
extends Proxy

GTlsClientConnection is the client-side subclass of TlsConnection, representing a client-side TLS connection.

Since:

2.28

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	TlsClientConnection.Builder<B extends Builder<B>>
static class	TlsClientConnection.TlsClientConnection$Impl	The TlsClientConnection$Impl type represents a native instance of the TlsClientConnection interface.
static class	TlsClientConnection.TlsClientConnectionInterface	vtable for a GTlsClientConnection implementation.

Method Summary

Modifier and Type	Method	Description
default void	copySessionState(TlsClientConnection source)	Possibly copies session state from one connection to another, for use in TLS session resumption.
default List<MemorySegment>	getAcceptedCas()	Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from.
default SocketConnectable	getServerIdentity()	Gets this TlsClientConnection's expected server identity
static Type	getType()	Get the GType of the TlsClientConnection class
default boolean	getUseSsl3()	Deprecated. SSL 3.0 is insecure.
default Set<TlsCertificateFlags>	getValidationFlags()	Deprecated. Do not attempt to ignore validation errors.
static TlsClientConnection	new_(IOStream baseIoStream, @Nullable SocketConnectable serverIdentity)	Creates a new GTlsClientConnection wrapping baseIoStream (which must have pollable input and output streams) which is assumed to communicate with the server identified by serverIdentity.
default void	setServerIdentity(SocketConnectable identity)	Sets this TlsClientConnection's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let this TlsClientConnection know what name to look for in the certificate when performing TlsCertificateFlags.BAD_IDENTITY validation, if enabled.
default void	setUseSsl3(boolean useSsl3)	Deprecated. SSL 3.0 is insecure.
default void	setValidationFlags(Set<TlsCertificateFlags> flags)	Deprecated. Do not attempt to ignore validation errors.
default void	setValidationFlags(TlsCertificateFlags... flags)	Deprecated. Do not attempt to ignore validation errors.

Methods inherited from interface org.javagi.base.Proxy

handle

Method Details

getType

static Type getType()

Get the GType of the TlsClientConnection class

Returns:

the GType

new_

static TlsClientConnection new_(IOStream baseIoStream,
 @Nullable
 @Nullable SocketConnectable serverIdentity)
                         throws GErrorException

Creates a new GTlsClientConnection wrapping baseIoStream (which must have pollable input and output streams) which is assumed to communicate with the server identified by serverIdentity.

See the documentation for GTlsConnection:base-io-stream for restrictions on when application code can run operations on the baseIoStream after this function has returned.

Parameters:

baseIoStream - the GIOStream to wrap

serverIdentity - the expected identity of the server

Returns:

the new GTlsClientConnection, or null on error

Throws:

GErrorException - see GError

Since:

2.28

copySessionState

default void copySessionState(TlsClientConnection source)

Possibly copies session state from one connection to another, for use in TLS session resumption. This is not normally needed, but may be used when the same session needs to be used between different endpoints, as is required by some protocols, such as FTP over TLS. source should have already completed a handshake and, since TLS 1.3, it should have been used to read data at least once. this TlsClientConnection should not have completed a handshake.

It is not possible to know whether a call to this function will actually do anything. Because session resumption is normally used only for performance benefit, the TLS backend might not implement this function. Even if implemented, it may not actually succeed in allowing this TlsClientConnection to resume source's TLS session, because the server may not have sent a session resumption token to source, or it may refuse to accept the token from this TlsClientConnection. There is no way to know whether a call to this function is actually successful.

Using this function is not required to benefit from session resumption. If the TLS backend supports session resumption, the session will be resumed automatically if it is possible to do so without weakening the privacy guarantees normally provided by TLS, without need to call this function. For example, with TLS 1.3, a session ticket will be automatically copied from any GTlsClientConnection that has previously received session tickets from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations.

Parameters:

source - a GTlsClientConnection

Since:

2.46

getAcceptedCas

default List<MemorySegment> getAcceptedCas()

Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. Otherwise, it will be null.

Each item in the list is a GByteArray which contains the complete subject DN of the certificate authority.

Returns:

the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free().

Since:

2.28

getServerIdentity

default SocketConnectable getServerIdentity()

Gets this TlsClientConnection's expected server identity

Returns:

a GSocketConnectable describing the expected server identity, or null if the expected identity is not known.

Since:

2.28

getUseSsl3

@Deprecated
default boolean getUseSsl3()

Deprecated.

SSL 3.0 is insecure.

SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details.

Returns:

false

Since:

2.28

getValidationFlags

@Deprecated
default Set<TlsCertificateFlags> getValidationFlags()

Deprecated.

Do not attempt to ignore validation errors.

Gets this TlsClientConnection's validation flags

This function does not work as originally designed and is impossible to use correctly. See GTlsClientConnection:validation-flags for more information.

Returns:

the validation flags

Since:

2.28

setServerIdentity

default void setServerIdentity(SocketConnectable identity)

Sets this TlsClientConnection's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let this TlsClientConnection know what name to look for in the certificate when performing TlsCertificateFlags.BAD_IDENTITY validation, if enabled.

Parameters:

identity - a GSocketConnectable describing the expected server identity

Since:

2.28

setUseSsl3

@Deprecated
default void setUseSsl3(boolean useSsl3)

Deprecated.

SSL 3.0 is insecure.

Since GLib 2.42.1, SSL 3.0 is no longer supported.

From GLib 2.42.1 through GLib 2.62, this function could be used to force use of TLS 1.0, the lowest-supported TLS protocol version at the time. In the past, this was needed to connect to broken TLS servers that exhibited protocol version intolerance. Such servers are no longer common, and using TLS 1.0 is no longer considered acceptable.

Since GLib 2.64, this function does nothing.

Parameters:

useSsl3 - a gboolean, ignored

Since:

2.28

setValidationFlags

@Deprecated
default void setValidationFlags(Set<TlsCertificateFlags> flags)

Deprecated.

Do not attempt to ignore validation errors.

Sets this TlsClientConnection's validation flags, to override the default set of checks performed when validating a server certificate. By default, TlsCertificateFlags.VALIDATE_ALL is used.

This function does not work as originally designed and is impossible to use correctly. See GTlsClientConnection:validation-flags for more information.

Parameters:

flags - the GTlsCertificateFlags to use

Since:

2.28

setValidationFlags

@Deprecated
default void setValidationFlags(TlsCertificateFlags... flags)

Deprecated.

Do not attempt to ignore validation errors.

Sets this TlsClientConnection's validation flags, to override the default set of checks performed when validating a server certificate. By default, TlsCertificateFlags.VALIDATE_ALL is used.

This function does not work as originally designed and is impossible to use correctly. See GTlsClientConnection:validation-flags for more information.

Parameters:

flags - the GTlsCertificateFlags to use

Since:

2.28