gi-gio-2.0.27: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.TlsClientConnection

Contents

- Exported types
- Methods
  - Overloaded methods
  - copySessionState
  - getAcceptedCas
  - getServerIdentity
  - getUseSsl3
  - getValidationFlags
  - new
  - setServerIdentity
  - setUseSsl3
  - setValidationFlags
- Properties
  - acceptedCas
  - serverIdentity
  - useSsl3
  - validationFlags

Description

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

Since: 2.28

Synopsis

- newtype TlsClientConnection = TlsClientConnection (ManagedPtr TlsClientConnection)
- class (GObject o, IsDescendantOf TlsClientConnection o) => IsTlsClientConnection o
- toTlsClientConnection :: (MonadIO m, IsTlsClientConnection o) => o -> m TlsClientConnection
- tlsClientConnectionCopySessionState :: (HasCallStack, MonadIO m, IsTlsClientConnection a, IsTlsClientConnection b) => a -> b -> m ()
- tlsClientConnectionGetAcceptedCas :: (HasCallStack, MonadIO m, IsTlsClientConnection a) => a -> m [ByteString]
- tlsClientConnectionGetServerIdentity :: (HasCallStack, MonadIO m, IsTlsClientConnection a) => a -> m SocketConnectable
- tlsClientConnectionGetUseSsl3 :: (HasCallStack, MonadIO m, IsTlsClientConnection a) => a -> m Bool
- tlsClientConnectionGetValidationFlags :: (HasCallStack, MonadIO m, IsTlsClientConnection a) => a -> m [TlsCertificateFlags]
- tlsClientConnectionNew :: (HasCallStack, MonadIO m, IsIOStream a, IsSocketConnectable b) => a -> Maybe b -> m TlsClientConnection
- tlsClientConnectionSetServerIdentity :: (HasCallStack, MonadIO m, IsTlsClientConnection a, IsSocketConnectable b) => a -> b -> m ()
- tlsClientConnectionSetUseSsl3 :: (HasCallStack, MonadIO m, IsTlsClientConnection a) => a -> Bool -> m ()
- tlsClientConnectionSetValidationFlags :: (HasCallStack, MonadIO m, IsTlsClientConnection a) => a -> [TlsCertificateFlags] -> m ()
- getTlsClientConnectionAcceptedCas :: (MonadIO m, IsTlsClientConnection o) => o -> m [Ptr ()]
- constructTlsClientConnectionServerIdentity :: (IsTlsClientConnection o, MonadIO m, IsSocketConnectable a) => a -> m (GValueConstruct o)
- getTlsClientConnectionServerIdentity :: (MonadIO m, IsTlsClientConnection o) => o -> m SocketConnectable
- setTlsClientConnectionServerIdentity :: (MonadIO m, IsTlsClientConnection o, IsSocketConnectable a) => o -> a -> m ()
- constructTlsClientConnectionUseSsl3 :: (IsTlsClientConnection o, MonadIO m) => Bool -> m (GValueConstruct o)
- getTlsClientConnectionUseSsl3 :: (MonadIO m, IsTlsClientConnection o) => o -> m Bool
- setTlsClientConnectionUseSsl3 :: (MonadIO m, IsTlsClientConnection o) => o -> Bool -> m ()
- constructTlsClientConnectionValidationFlags :: (IsTlsClientConnection o, MonadIO m) => [TlsCertificateFlags] -> m (GValueConstruct o)
- getTlsClientConnectionValidationFlags :: (MonadIO m, IsTlsClientConnection o) => o -> m [TlsCertificateFlags]
- setTlsClientConnectionValidationFlags :: (MonadIO m, IsTlsClientConnection o) => o -> [TlsCertificateFlags] -> m ()

# Exported types

newtype TlsClientConnection Source #

Memory-managed wrapper type.

Constructors

TlsClientConnection (ManagedPtr TlsClientConnection) |

#### Instances

Instances details

Eq TlsClientConnection Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection Methods (==) :: TlsClientConnection -> TlsClientConnection -> Bool # (/=) :: TlsClientConnection -> TlsClientConnection -> Bool #
GObject TlsClientConnection Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection
TypedObject TlsClientConnection Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection Methods glibType :: IO GType Source #
ManagedPtrNewtype TlsClientConnection Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection Methods toManagedPtr :: TlsClientConnection -> ManagedPtr TlsClientConnection Source #
IsGValue TlsClientConnection Source # | Convert `TlsClientConnection` to and from `GValue` with `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection Methods toGValue :: TlsClientConnection -> IO GValue Source # fromGValue :: GValue -> IO TlsClientConnection Source #
HasParentTypes TlsClientConnection Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection
type ParentTypes TlsClientConnection Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection type ParentTypes TlsClientConnection = '[Object, TlsConnection, IOStream]

class (GObject o, IsDescendantOf TlsClientConnection o) => IsTlsClientConnection o Source #

Type class for types which can be safely cast to `TlsClientConnection`, for instance with `toTlsClientConnection`.

#### Instances

Instances details

(GObject o, IsDescendantOf TlsClientConnection o) => IsTlsClientConnection o Source # |
Instance details Defined in GI.Gio.Interfaces.TlsClientConnection

toTlsClientConnection :: (MonadIO m, IsTlsClientConnection o) => o -> m TlsClientConnection Source #

Cast to `TlsClientConnection`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

## Overloaded methods

## copySessionState

tlsClientConnectionCopySessionState Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a, IsTlsClientConnection b) |
=> a | `conn`: a `TlsClientConnection`
-> b | `source`: a `TlsClientConnection`
-> m () |

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. `conn` 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 `conn` 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 `conn`. 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 `TlsClientConnection` 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.

Since: 2.46

## getAcceptedCas

tlsClientConnectionGetAcceptedCas Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a) |
=> a | `conn`: the `TlsClientConnection`
-> m [ByteString] | Returns: the list of CA DNs. You should unref each element with `byteArrayUnref` and then the free the list with `g_list_free()`.

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 `Nothing`.

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

Since: 2.28

## getServerIdentity

tlsClientConnectionGetServerIdentity Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a) |
=> a | `conn`: the `TlsClientConnection`
-> m SocketConnectable | Returns: a `SocketConnectable` describing the expected server identity, or `Nothing` if the expected identity is not known.

Gets `conn`'s expected server identity

Since: 2.28

## getUseSsl3

tlsClientConnectionGetUseSsl3 Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a) |
=> a | `conn`: the `TlsClientConnection`
-> m Bool | Returns: `False`

Deprecated: (Since version 2.56)SSL 3.0 is insecure.

SSL 3.0 is no longer supported. See `tlsClientConnectionSetUseSsl3` for details.

Since: 2.28

## getValidationFlags

tlsClientConnectionGetValidationFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a) |
=> a | `conn`: the `TlsClientConnection`
-> m [TlsCertificateFlags] | Returns: the validation flags

Gets `conn`'s validation flags

Since: 2.28

## new

tlsClientConnectionNew Source #

Arguments

:: (HasCallStack, MonadIO m, IsIOStream a, IsSocketConnectable b) |
=> a | `baseIoStream`: the `IOStream` to wrap
-> Maybe b | `serverIdentity`: the expected identity of the server
-> m TlsClientConnection | Returns: the new `TlsClientConnection`, or `Nothing` on error (Can throw `GError`)

Creates a new `TlsClientConnection` 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 `TlsConnection`:`base-io-stream` for restrictions on when application code can run operations on the `baseIoStream` after this function has returned.

Since: 2.28

## setServerIdentity

tlsClientConnectionSetServerIdentity Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a, IsSocketConnectable b) |
=> a | `conn`: the `TlsClientConnection`
-> b | `identity`: a `SocketConnectable` describing the expected server identity
-> m () |

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

Since: 2.28

## setUseSsl3

tlsClientConnectionSetUseSsl3 Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a) |
=> a | `conn`: the `TlsClientConnection`
-> Bool | `useSsl3`: a `Bool`, ignored
-> m () |

Deprecated: (Since version 2.56)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.

Since: 2.28

## setValidationFlags

tlsClientConnectionSetValidationFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsClientConnection a) |
=> a | `conn`: the `TlsClientConnection`
-> [TlsCertificateFlags] | `flags`: the `TlsCertificateFlags` to use
-> m () |

Sets `conn`'s validation flags, to override the default set of checks performed when validating a server certificate. By default, `TlsCertificateFlagsValidateAll` is used.

Since: 2.28

# Properties

## acceptedCas

A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then this property will be set after the handshake completes.

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

Since: 2.28

getTlsClientConnectionAcceptedCas :: (MonadIO m, IsTlsClientConnection o) => o -> m [Ptr ()] Source #

Get the value of the “`accepted-cas`” property. When overloading is enabled, this is equivalent to

    get tlsClientConnection #acceptedCas

## serverIdentity

A `SocketConnectable` describing the identity of the server that is expected on the other end of the connection.

If the `TlsCertificateFlagsBadIdentity` flag is set in `TlsClientConnection`:`validation-flags`, this object will be used to determine the expected identify of the remote end of the connection; if `TlsClientConnection`:`server-identity` is not set, or does not match the identity presented by the server, then the `TlsCertificateFlagsBadIdentity` validation will fail.

In addition to its use in verifying the server certificate, this is also used to give a hint to the server about what certificate we expect, which is useful for servers that serve virtual hosts.

Since: 2.28

constructTlsClientConnectionServerIdentity :: (IsTlsClientConnection o, MonadIO m, IsSocketConnectable a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`server-identity`” property. This is rarely needed directly, but it is used by `new`.

getTlsClientConnectionServerIdentity :: (MonadIO m, IsTlsClientConnection o) => o -> m SocketConnectable Source #

Get the value of the “`server-identity`” property. When overloading is enabled, this is equivalent to

    get tlsClientConnection #serverIdentity

setTlsClientConnectionServerIdentity :: (MonadIO m, IsTlsClientConnection o, IsSocketConnectable a) => o -> a -> m () Source #

Set the value of the “`server-identity`” property. When overloading is enabled, this is equivalent to

    set tlsClientConnection [ #serverIdentity := value ]

## useSsl3

SSL 3.0 is no longer supported. See `tlsClientConnectionSetUseSsl3` for details.

Since: 2.28

constructTlsClientConnectionUseSsl3 :: (IsTlsClientConnection o, MonadIO m) => Bool -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`use-ssl3`” property. This is rarely needed directly, but it is used by `new`.

getTlsClientConnectionUseSsl3 :: (MonadIO m, IsTlsClientConnection o) => o -> m Bool Source #

Get the value of the “`use-ssl3`” property. When overloading is enabled, this is equivalent to

    get tlsClientConnection #useSsl3

setTlsClientConnectionUseSsl3 :: (MonadIO m, IsTlsClientConnection o) => o -> Bool -> m () Source #

Set the value of the “`use-ssl3`” property. When overloading is enabled, this is equivalent to

    set tlsClientConnection [ #useSsl3 := value ]

## validationFlags

What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via acceptCertificate.

Since: 2.28

constructTlsClientConnectionValidationFlags :: (IsTlsClientConnection o, MonadIO m) => [TlsCertificateFlags] -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`validation-flags`” property. This is rarely needed directly, but it is used by `new`.

getTlsClientConnectionValidationFlags :: (MonadIO m, IsTlsClientConnection o) => o -> m [TlsCertificateFlags] Source #

Get the value of the “`validation-flags`” property. When overloading is enabled, this is equivalent to

    get tlsClientConnection #validationFlags

setTlsClientConnectionValidationFlags :: (MonadIO m, IsTlsClientConnection o) => o -> [TlsCertificateFlags] -> m () Source #

Set the value of the “`validation-flags`” property. When overloading is enabled, this is equivalent to

    set tlsClientConnection [ #validationFlags := value ]