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.TlsCertificate

Contents

- Exported types
- Methods
  - getIssuer
  - isSame
  - listNewFromFile
  - newFromFile
  - newFromFiles
  - newFromPem
  - verify
- Properties
  - certificate
  - certificatePem
  - issuer
  - privateKey
  - privateKeyPem

Description

A certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a `TlsServerConnection`).

Since: 2.28

Synopsis

- newtype TlsCertificate = TlsCertificate (ManagedPtr TlsCertificate)
- class GObject o => IsTlsCertificate o
- toTlsCertificate :: (MonadIO m, IsTlsCertificate o) => o -> m TlsCertificate
- noTlsCertificate :: Maybe TlsCertificate
- tlsCertificateGetIssuer :: (HasCallStack, MonadIO m, IsTlsCertificate a) => a -> m TlsCertificate
- tlsCertificateIsSame :: (HasCallStack, MonadIO m, IsTlsCertificate a, IsTlsCertificate b) => a -> b -> m Bool
- tlsCertificateListNewFromFile :: (HasCallStack, MonadIO m) => [Char] -> m [TlsCertificate]
- tlsCertificateNewFromFile :: (HasCallStack, MonadIO m) => [Char] -> m TlsCertificate
- tlsCertificateNewFromFiles :: (HasCallStack, MonadIO m) => [Char] -> [Char] -> m TlsCertificate
- tlsCertificateNewFromPem :: (HasCallStack, MonadIO m) => Text -> Int64 -> m TlsCertificate
- tlsCertificateVerify :: (HasCallStack, MonadIO m, IsTlsCertificate a, IsSocketConnectable b, IsTlsCertificate c) => a -> Maybe b -> Maybe c -> m [TlsCertificateFlags]
- constructTlsCertificateCertificate :: IsTlsCertificate o => ByteString -> IO (GValueConstruct o)
- getTlsCertificateCertificate :: (MonadIO m, IsTlsCertificate o) => o -> m (Maybe ByteString)
- constructTlsCertificateCertificatePem :: IsTlsCertificate o => Text -> IO (GValueConstruct o)
- getTlsCertificateCertificatePem :: (MonadIO m, IsTlsCertificate o) => o -> m (Maybe Text)
- constructTlsCertificateIssuer :: (IsTlsCertificate o, IsTlsCertificate a) => a -> IO (GValueConstruct o)
- getTlsCertificateIssuer :: (MonadIO m, IsTlsCertificate o) => o -> m TlsCertificate
- constructTlsCertificatePrivateKey :: IsTlsCertificate o => ByteString -> IO (GValueConstruct o)
- constructTlsCertificatePrivateKeyPem :: IsTlsCertificate o => Text -> IO (GValueConstruct o)

# Exported types

newtype TlsCertificate Source #

Memory-managed wrapper type.

Constructors

TlsCertificate (ManagedPtr TlsCertificate) |

Instances

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

class GObject o => IsTlsCertificate o Source #

Type class for types which can be safely cast to `TlsCertificate`, for instance with `toTlsCertificate`.

Instances

(GObject a, (UnknownAncestorError TlsCertificate a :: Constraint)) => IsTlsCertificate a Source # |
Instance details Defined in GI.Gio.Objects.TlsCertificate
IsTlsCertificate TlsCertificate Source # |
Instance details Defined in GI.Gio.Objects.TlsCertificate

toTlsCertificate :: (MonadIO m, IsTlsCertificate o) => o -> m TlsCertificate Source #

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

noTlsCertificate :: Maybe TlsCertificate Source #

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

# Methods

## getIssuer

tlsCertificateGetIssuer Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsCertificate a) |
=> a | `cert`: a `TlsCertificate`
-> m TlsCertificate | Returns: The certificate of `cert`'s issuer, or `Nothing` if `cert` is self-signed or signed with an unknown certificate.

Gets the `TlsCertificate` representing `cert`'s issuer, if known

Since: 2.28

## isSame

tlsCertificateIsSame Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsCertificate a, IsTlsCertificate b) |
=> a | `certOne`: first certificate to compare
-> b | `certTwo`: second certificate to compare
-> m Bool | Returns: whether the same or not

Check if two `TlsCertificate` objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their `TlsCertificate`:`issuer`, `TlsCertificate`:`private-key`, or `TlsCertificate`:`private-key-pem` properties differ.

Since: 2.34

## listNewFromFile

tlsCertificateListNewFromFile Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `file`: file containing PEM-encoded certificates to import
-> m [TlsCertificate] | Returns: a `List` containing `TlsCertificate` objects. You must free the list and its contents when you are done with it. (Can throw `GError`)

Creates one or more `GTlsCertificates` from the PEM-encoded data in `file`. If `file` cannot be read or parsed, the function will return `Nothing` and set `error`. If `file` does not contain any PEM-encoded certificates, this will return an empty list and not set `error`.

Since: 2.28

## newFromFile

tlsCertificateNewFromFile Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `file`: file containing a PEM-encoded certificate to import
-> m TlsCertificate | Returns: the new certificate, or `Nothing` on error (Can throw `GError`)

Creates a `TlsCertificate` from the PEM-encoded data in `file`. The returned certificate will be the first certificate found in `file`. As of GLib 2.44, if `file` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the `TlsCertificate`:`issuer` property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

If `file` cannot be read or parsed, the function will return `Nothing` and set `error`. Otherwise, this behaves like `tlsCertificateNewFromPem`.

Since: 2.28

## newFromFiles

tlsCertificateNewFromFiles Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `certFile`: file containing one or more PEM-encoded certificates to import
-> [Char] | `keyFile`: file containing a PEM-encoded private key to import
-> m TlsCertificate | Returns: the new certificate, or `Nothing` on error (Can throw `GError`)

Creates a `TlsCertificate` from the PEM-encoded data in `certFile` and `keyFile`. The returned certificate will be the first certificate found in `certFile`. As of GLib 2.44, if `certFile` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the `TlsCertificate`:`issuer` property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

If either file cannot be read or parsed, the function will return `Nothing` and set `error`. Otherwise, this behaves like `tlsCertificateNewFromPem`.

Since: 2.28

## newFromPem

tlsCertificateNewFromPem Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `data`: PEM-encoded certificate data
-> Int64 | `length`: the length of `data`, or -1 if it's 0-terminated.
-> m TlsCertificate | Returns: the new certificate, or `Nothing` if `data` is invalid (Can throw `GError`)

Creates a `TlsCertificate` from the PEM-encoded data in `data`. If `data` includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the `TlsCertificate`:`private-key-pem` property for information about supported formats.)

The returned certificate will be the first certificate found in `data`. As of GLib 2.44, if `data` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the `TlsCertificate`:`issuer` property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

Since: 2.28

## verify

tlsCertificateVerify Source #

Arguments

:: (HasCallStack, MonadIO m, IsTlsCertificate a, IsSocketConnectable b, IsTlsCertificate c) |
=> a | `cert`: a `TlsCertificate`
-> Maybe b | `identity`: the expected peer identity
-> Maybe c | `trustedCa`: the certificate of a trusted authority
-> m [TlsCertificateFlags] | Returns: the appropriate `TlsCertificateFlags`

This verifies `cert` and returns a set of `TlsCertificateFlags` indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database.

If `identity` is not `Nothing`, `cert`'s name(s) will be compared against it, and `TlsCertificateFlagsBadIdentity` will be set in the return value if it does not match. If `identity` is `Nothing`, that bit will never be set in the return value.

If `trustedCa` is not `Nothing`, then `cert` (or one of the certificates in its chain) must be signed by it, or else `TlsCertificateFlagsUnknownCa` will be set in the return value. If `trustedCa` is `Nothing`, that bit will never be set in the return value.

(All other `TlsCertificateFlags` values will always be set or unset as appropriate.)

Since: 2.28

# Properties

## certificate

The DER (binary) encoded representation of the certificate. This property and the `TlsCertificate`:`certificate-pem` property represent the same data, just in different forms.

Since: 2.28

constructTlsCertificateCertificate :: IsTlsCertificate o => ByteString -> IO (GValueConstruct o) Source #

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

getTlsCertificateCertificate :: (MonadIO m, IsTlsCertificate o) => o -> m (Maybe ByteString) Source #

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

    get tlsCertificate #certificate

## certificatePem

The PEM (ASCII) encoded representation of the certificate. This property and the `TlsCertificate`:`certificate` property represent the same data, just in different forms.

Since: 2.28

constructTlsCertificateCertificatePem :: IsTlsCertificate o => Text -> IO (GValueConstruct o) Source #

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

getTlsCertificateCertificatePem :: (MonadIO m, IsTlsCertificate o) => o -> m (Maybe Text) Source #

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

    get tlsCertificate #certificatePem

## issuer

A `TlsCertificate` representing the entity that issued this certificate. If `Nothing`, this means that the certificate is either self-signed, or else the certificate of the issuer is not available.

Since: 2.28

constructTlsCertificateIssuer :: (IsTlsCertificate o, IsTlsCertificate a) => a -> IO (GValueConstruct o) Source #

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

getTlsCertificateIssuer :: (MonadIO m, IsTlsCertificate o) => o -> m TlsCertificate Source #

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

    get tlsCertificate #issuer

## privateKey

The DER (binary) encoded representation of the certificate's private key, in either PKCS`1` format or unencrypted PKCS`8` format. This property (or the `TlsCertificate`:`private-key-pem` property) can be set when constructing a key (eg, from a file), but cannot be read.

PKCS`8` format is supported since 2.32; earlier releases only support PKCS`1`. You can use the `openssl rsa` tool to convert PKCS`8` keys to PKCS`1`.

Since: 2.28

constructTlsCertificatePrivateKey :: IsTlsCertificate o => ByteString -> IO (GValueConstruct o) Source #

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

## privateKeyPem

The PEM (ASCII) encoded representation of the certificate's private key in either PKCS`1` format ("`BEGIN RSA PRIVATE KEY`") or unencrypted PKCS`8` format ("`BEGIN PRIVATE KEY`"). This property (or the `TlsCertificate`:`private-key` property) can be set when constructing a key (eg, from a file), but cannot be read.

PKCS`8` format is supported since 2.32; earlier releases only support PKCS`1`. You can use the `openssl rsa` tool to convert PKCS`8` keys to PKCS`1`.

Since: 2.28

constructTlsCertificatePrivateKeyPem :: IsTlsCertificate o => Text -> IO (GValueConstruct o) Source #

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