gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.TlsDatabase

Contents

- Exported types
- Methods
  - createCertificateHandle
  - lookupCertificateForHandle
  - lookupCertificateForHandleAsync
  - lookupCertificateForHandleFinish
  - lookupCertificateIssuer
  - lookupCertificateIssuerAsync
  - lookupCertificateIssuerFinish
  - lookupCertificatesIssuedBy
  - lookupCertificatesIssuedByAsync
  - lookupCertificatesIssuedByFinish
  - verifyChain
  - verifyChainAsync
  - verifyChainFinish

Description

`TlsDatabase` is used to lookup certificates and other information from a certificate or key store. It is an abstract base class which TLS library specific subtypes override.

A `TlsDatabase` may be accessed from multiple threads by the TLS backend. All implementations are required to be fully thread-safe.

Most common client applications will not directly interact with `TlsDatabase`. It is used internally by `TlsConnection`.

Since: 2.30

Synopsis

- newtype TlsDatabase = TlsDatabase (ManagedPtr TlsDatabase)
- class GObject o => IsTlsDatabase o
- toTlsDatabase :: (MonadIO m, IsTlsDatabase o) => o -> m TlsDatabase
- noTlsDatabase :: Maybe TlsDatabase
- tlsDatabaseCreateCertificateHandle :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b) => a -> b -> m (Maybe Text)
- tlsDatabaseLookupCertificateForHandle :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) => a -> Text -> Maybe b -> TlsDatabaseLookupFlags -> Maybe c -> m (Maybe TlsCertificate)
- tlsDatabaseLookupCertificateForHandleAsync :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) => a -> Text -> Maybe b -> TlsDatabaseLookupFlags -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- tlsDatabaseLookupCertificateForHandleFinish :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) => a -> b -> m TlsCertificate
- tlsDatabaseLookupCertificateIssuer :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsTlsInteraction c, IsCancellable d) => a -> b -> Maybe c -> TlsDatabaseLookupFlags -> Maybe d -> m TlsCertificate
- tlsDatabaseLookupCertificateIssuerAsync :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsTlsInteraction c, IsCancellable d) => a -> b -> Maybe c -> TlsDatabaseLookupFlags -> Maybe d -> Maybe AsyncReadyCallback -> m ()
- tlsDatabaseLookupCertificateIssuerFinish :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) => a -> b -> m TlsCertificate
- tlsDatabaseLookupCertificatesIssuedBy :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) => a -> ByteString -> Maybe b -> TlsDatabaseLookupFlags -> Maybe c -> m [TlsCertificate]
- tlsDatabaseLookupCertificatesIssuedByAsync :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) => a -> ByteString -> Maybe b -> TlsDatabaseLookupFlags -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- tlsDatabaseLookupCertificatesIssuedByFinish :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) => a -> b -> m [TlsCertificate]
- tlsDatabaseVerifyChain :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsSocketConnectable c, IsTlsInteraction d, IsCancellable e) => a -> b -> Text -> Maybe c -> Maybe d -> [TlsDatabaseVerifyFlags] -> Maybe e -> m [TlsCertificateFlags]
- tlsDatabaseVerifyChainAsync :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsSocketConnectable c, IsTlsInteraction d, IsCancellable e) => a -> b -> Text -> Maybe c -> Maybe d -> [TlsDatabaseVerifyFlags] -> Maybe e -> Maybe AsyncReadyCallback -> m ()
- tlsDatabaseVerifyChainFinish :: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) => a -> b -> m [TlsCertificateFlags]

# Exported types

newtype TlsDatabase Source #

Memory-managed wrapper type.

Constructors

TlsDatabase (ManagedPtr TlsDatabase) |

Instances

GObject TlsDatabase Source # |
Instance details Defined in GI.Gio.Objects.TlsDatabase Methods gobjectType :: TlsDatabase -> IO GType Source #
IsObject TlsDatabase Source # |
Instance details Defined in GI.Gio.Objects.TlsDatabase
IsTlsDatabase TlsDatabase Source # |
Instance details Defined in GI.Gio.Objects.TlsDatabase

class GObject o => IsTlsDatabase o Source #

Type class for types which can be safely cast to `TlsDatabase`, for instance with `toTlsDatabase`.

Instances

(GObject a, (UnknownAncestorError TlsDatabase a :: Constraint)) => IsTlsDatabase a Source # |
Instance details Defined in GI.Gio.Objects.TlsDatabase
IsTlsDatabase TlsDatabase Source # |
Instance details Defined in GI.Gio.Objects.TlsDatabase
IsTlsDatabase TlsFileDatabase Source # |
Instance details Defined in GI.Gio.Interfaces.TlsFileDatabase

toTlsDatabase :: (MonadIO m, IsTlsDatabase o) => o -> m TlsDatabase Source #

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

noTlsDatabase :: Maybe TlsDatabase Source #

A convenience alias for `Nothing` :: `Maybe` `TlsDatabase`.

# Methods

## createCertificateHandle

tlsDatabaseCreateCertificateHandle Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b) |
=> a | `self`: a `TlsDatabase`
-> b | `certificate`: certificate for which to create a handle.
-> m (Maybe Text) | Returns: a newly allocated string containing the handle.

Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, `Nothing` will be returned.

This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it.

Since: 2.30

## lookupCertificateForHandle

tlsDatabaseLookupCertificateForHandle Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) |
=> a | `self`: a `TlsDatabase`
-> Text | `handle`: a certificate handle
-> Maybe b | `interaction`: used to interact with the user if necessary
-> TlsDatabaseLookupFlags | `flags`: Flags which affect the lookup.
-> Maybe c | `cancellable`: a `Cancellable`, or `Nothing`
-> m (Maybe TlsCertificate) | Returns: a newly allocated `TlsCertificate`, or `Nothing`. Use `objectUnref` to release the certificate. (Can throw `GError`)

Lookup a certificate by its handle.

The handle should have been created by calling `tlsDatabaseCreateCertificateHandle` on a `TlsDatabase` object of the same TLS backend. The handle is designed to remain valid across instantiations of the database.

If the handle is no longer valid, or does not point to a certificate in this database, then `Nothing` will be returned.

This function can block, use `tlsDatabaseLookupCertificateForHandleAsync` to perform the lookup operation asynchronously.

Since: 2.30

## lookupCertificateForHandleAsync

tlsDatabaseLookupCertificateForHandleAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) |
=> a | `self`: a `TlsDatabase`
-> Text | `handle`: a certificate handle
-> Maybe b | `interaction`: used to interact with the user if necessary
-> TlsDatabaseLookupFlags | `flags`: Flags which affect the lookup.
-> Maybe c | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call when the operation completes
-> m () |

Asynchronously lookup a certificate by its handle in the database. See `tlsDatabaseLookupCertificateForHandle` for more information.

Since: 2.30

## lookupCertificateForHandleFinish

tlsDatabaseLookupCertificateForHandleFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) |
=> a | `self`: a `TlsDatabase`
-> b | `result`: a `AsyncResult`.
-> m TlsCertificate | Returns: a newly allocated `TlsCertificate` object. Use `objectUnref` to release the certificate. (Can throw `GError`)

Finish an asynchronous lookup of a certificate by its handle. See `g_tls_database_lookup_certificate_by_handle()` for more information.

If the handle is no longer valid, or does not point to a certificate in this database, then `Nothing` will be returned.

Since: 2.30

## lookupCertificateIssuer

tlsDatabaseLookupCertificateIssuer Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsTlsInteraction c, IsCancellable d) |
=> a | `self`: a `TlsDatabase`
-> b | `certificate`: a `TlsCertificate`
-> Maybe c | `interaction`: used to interact with the user if necessary
-> TlsDatabaseLookupFlags | `flags`: flags which affect the lookup operation
-> Maybe d | `cancellable`: a `Cancellable`, or `Nothing`
-> m TlsCertificate | Returns: a newly allocated issuer `TlsCertificate`, or `Nothing`. Use `objectUnref` to release the certificate. (Can throw `GError`)

Lookup the issuer of `certificate` in the database.

The `TlsCertificate`:`issuer` property of `certificate` is not modified, and the two certificates are not hooked into a chain.

This function can block, use `tlsDatabaseLookupCertificateIssuerAsync` to perform the lookup operation asynchronously.

Since: 2.30

## lookupCertificateIssuerAsync

tlsDatabaseLookupCertificateIssuerAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsTlsInteraction c, IsCancellable d) |
=> a | `self`: a `TlsDatabase`
-> b | `certificate`: a `TlsCertificate`
-> Maybe c | `interaction`: used to interact with the user if necessary
-> TlsDatabaseLookupFlags | `flags`: flags which affect the lookup operation
-> Maybe d | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call when the operation completes
-> m () |

Asynchronously lookup the issuer of `certificate` in the database. See `tlsDatabaseLookupCertificateIssuer` for more information.

Since: 2.30

## lookupCertificateIssuerFinish

tlsDatabaseLookupCertificateIssuerFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) |
=> a | `self`: a `TlsDatabase`
-> b | `result`: a `AsyncResult`.
-> m TlsCertificate | Returns: a newly allocated issuer `TlsCertificate`, or `Nothing`. Use `objectUnref` to release the certificate. (Can throw `GError`)

Finish an asynchronous lookup issuer operation. See `tlsDatabaseLookupCertificateIssuer` for more information.

Since: 2.30

## lookupCertificatesIssuedBy

tlsDatabaseLookupCertificatesIssuedBy Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) |
=> a | `self`: a `TlsDatabase`
-> ByteString | `issuerRawDn`: a `ByteArray` which holds the DER encoded issuer DN.
-> Maybe b | `interaction`: used to interact with the user if necessary
-> TlsDatabaseLookupFlags | `flags`: Flags which affect the lookup operation.
-> Maybe c | `cancellable`: a `Cancellable`, or `Nothing`
-> m [TlsCertificate] | Returns: a newly allocated list of `TlsCertificate` objects. Use `objectUnref` on each certificate, and `g_list_free()` on the release the list. (Can throw `GError`)

Lookup certificates issued by this issuer in the database.

This function can block, use `tlsDatabaseLookupCertificatesIssuedByAsync` to perform the lookup operation asynchronously.

Since: 2.30

## lookupCertificatesIssuedByAsync

tlsDatabaseLookupCertificatesIssuedByAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsInteraction b, IsCancellable c) |
=> a | `self`: a `TlsDatabase`
-> ByteString | `issuerRawDn`: a `ByteArray` which holds the DER encoded issuer DN.
-> Maybe b | `interaction`: used to interact with the user if necessary
-> TlsDatabaseLookupFlags | `flags`: Flags which affect the lookup operation.
-> Maybe c | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call when the operation completes
-> m () |

Asynchronously lookup certificates issued by this issuer in the database. See `tlsDatabaseLookupCertificatesIssuedBy` for more information.

The database may choose to hold a reference to the issuer byte array for the duration of of this asynchronous operation. The byte array should not be modified during this time.

Since: 2.30

## lookupCertificatesIssuedByFinish

tlsDatabaseLookupCertificatesIssuedByFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) |
=> a | `self`: a `TlsDatabase`
-> b | `result`: a `AsyncResult`.
-> m [TlsCertificate] | Returns: a newly allocated list of `TlsCertificate` objects. Use `objectUnref` on each certificate, and `g_list_free()` on the release the list. (Can throw `GError`)

Finish an asynchronous lookup of certificates. See `tlsDatabaseLookupCertificatesIssuedBy` for more information.

Since: 2.30

## verifyChain

tlsDatabaseVerifyChain Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsSocketConnectable c, IsTlsInteraction d, IsCancellable e) |
=> a | `self`: a `TlsDatabase`
-> b | `chain`: a `TlsCertificate` chain
-> Text | `purpose`: the purpose that this certificate chain will be used for.
-> Maybe c | `identity`: the expected peer identity
-> Maybe d | `interaction`: used to interact with the user if necessary
-> [TlsDatabaseVerifyFlags] | `flags`: additional verify flags
-> Maybe e | `cancellable`: a `Cancellable`, or `Nothing`
-> m [TlsCertificateFlags] | Returns: the appropriate `TlsCertificateFlags` which represents the result of verification. (Can throw `GError`)

Determines the validity of a certificate chain after looking up and adding any missing certificates to the chain.

`chain` is a chain of `TlsCertificate` objects each pointing to the next certificate in the chain by its `TlsCertificate`:`issuer` property. The chain may initially consist of one or more certificates. After the verification process is complete, `chain` may be modified by adding missing certificates, or removing extra certificates. If a certificate anchor was found, then it is added to the `chain`.

`purpose` describes the purpose (or usage) for which the certificate is being used. Typically `purpose` will be set to `TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER` which means that the certificate is being used to authenticate a server (and we are acting as the client).

The `identity` is used to check for pinned certificates (trust exceptions) in the database. These will override the normal verification process on a host by host basis.

Currently there are no `flags`, and `TlsDatabaseVerifyFlagsNone` should be used.

If `chain` is found to be valid, then the return value will be 0. If `chain` is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether `chain` is valid or not (eg, because `cancellable` is triggered before it completes) then the return value will be `TlsCertificateFlagsGenericError` and `error` will be set accordingly. `error` is not set when `chain` is successfully analyzed but found to be invalid.

This function can block, use `tlsDatabaseVerifyChainAsync` to perform the verification operation asynchronously.

Since: 2.30

## verifyChainAsync

tlsDatabaseVerifyChainAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsTlsCertificate b, IsSocketConnectable c, IsTlsInteraction d, IsCancellable e) |
=> a | `self`: a `TlsDatabase`
-> b | `chain`: a `TlsCertificate` chain
-> Text | `purpose`: the purpose that this certificate chain will be used for.
-> Maybe c | `identity`: the expected peer identity
-> Maybe d | `interaction`: used to interact with the user if necessary
-> [TlsDatabaseVerifyFlags] | `flags`: additional verify flags
-> Maybe e | `cancellable`: a `Cancellable`, or `Nothing`
-> Maybe AsyncReadyCallback | `callback`: callback to call when the operation completes
-> m () |

Asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See `tlsDatabaseVerifyChain` for more information.

Since: 2.30

## verifyChainFinish

tlsDatabaseVerifyChainFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsDatabase a, IsAsyncResult b) |
=> a | `self`: a `TlsDatabase`
-> b | `result`: a `AsyncResult`.
-> m [TlsCertificateFlags] | Returns: the appropriate `TlsCertificateFlags` which represents the result of verification. (Can throw `GError`)

Finish an asynchronous verify chain operation. See `tlsDatabaseVerifyChain` for more information.

If `chain` is found to be valid, then the return value will be 0. If `chain` is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether `chain` is valid or not (eg, because `cancellable` is triggered before it completes) then the return value will be `TlsCertificateFlagsGenericError` and `error` will be set accordingly. `error` is not set when `chain` is successfully analyzed but found to be invalid.

Since: 2.30