## Trust Storage and Lookups

Trust Storage and Lookups — Store and lookup bits of information used for verifying certificates.

## Synopsis

    #define             GCR_PURPOSE_SERVER_AUTH
    #define             GCR_PURPOSE_CLIENT_AUTH
    #define             GCR_PURPOSE_EMAIL
    #define             GCR_PURPOSE_CODE_SIGNING
    gboolean            gcr_trust_is_certificate_anchored   (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_trust_is_certificate_anchored_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_trust_is_certificate_anchored_finish
                                                            (GAsyncResult *result,
                                                             GError **error);
    gboolean            gcr_trust_is_certificate_pinned     (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_trust_is_certificate_pinned_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_trust_is_certificate_pinned_finish
                                                            (GAsyncResult *result,
                                                             GError **error);
    gboolean            gcr_trust_add_pinned_certificate    (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_trust_add_pinned_certificate_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_trust_add_pinned_certificate_finish
                                                            (GAsyncResult *result,
                                                             GError **error);
    gboolean            gcr_trust_remove_pinned_certificate (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gcr_trust_remove_pinned_certificate_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_trust_remove_pinned_certificate_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

## Description

These functions provide access to stored information about which certificates the system and user trusts as certificate authority trust anchors, or overrides to the normal verification of certificates.

Trust anchors are used to verify the certificate authority in a certificate chain. Trust anchors are always valid for a given purpose. The most common purpose is the GCR_PURPOSE_SERVER_AUTH and is used for a client application to verify that the certificate at the server side of a TLS connection is authorized to act as such. To check if a certificate is a trust anchor use `gcr_trust_is_certificate_anchored()`.

Pinned certificates are used when a user overrides the default trust decision for a given certificate. They're often used with self-signed certificates. Pinned certificates are always only valid for a single peer such as the remote host with which TLS is being performed. To lookup pinned certificates use `gcr_trust_is_certificate_pinned()`.

After the user has requested to override the trust decision about a given certificate then a pinned certificates can be added by using the `gcr_trust_add_pinned_certificate()` function.

These functions do not constitute a viable method for verifying certificates used in TLS or other locations. Instead they support such verification by providing some of the needed data for a trust decision.

The storage is provided by pluggable PKCS#11 modules.

## Details

### GCR_PURPOSE_SERVER_AUTH

    #define GCR_PURPOSE_SERVER_AUTH "1.3.6.1.5.5.7.3.1"

The purpose used to verify the server certificate in a TLS connection. This is the most common purpose in use.

### GCR_PURPOSE_CLIENT_AUTH

    #define GCR_PURPOSE_CLIENT_AUTH "1.3.6.1.5.5.7.3.2"

The purpose used to verify the client certificate in a TLS connection.

### GCR_PURPOSE_EMAIL

    #define GCR_PURPOSE_EMAIL "1.3.6.1.5.5.7.3.4"

The purpose used to verify certificates that are used in email communication such as S/MIME.

### GCR_PURPOSE_CODE_SIGNING

    #define GCR_PURPOSE_CODE_SIGNING "1.3.6.1.5.5.7.3.3"

The purpose used to verify certificate used for the signature on signed code.

### gcr_trust_is_certificate_anchored ()

    gboolean            gcr_trust_is_certificate_anchored   (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             GCancellable *cancellable,
                                                             GError **error);

Check if the `certificate` is a trust anchor for the given `purpose`. A trust anchor is used to verify the signatures on other certificates when verifying a certificate chain. Also known as a trusted certificate authority.

This call may block, see `gcr_trust_is_certificate_anchored_async()` for the non-blocking version.

In the case of an error, `FALSE` is also returned. Check `error` to detect if an error occurred.

`certificate` : | a GcrCertificate to check
`purpose` : | the purpose string
`cancellable` : | a GCancellable
`error` : | a GError, or NULL
Returns : | `TRUE` if the certificate is a trust anchor

### gcr_trust_is_certificate_anchored_async ()

    void                gcr_trust_is_certificate_anchored_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Check if the `certificate` is a trust anchor for the given `purpose`. A trust anchor is used to verify the signatures on other certificates when verifying a certificate chain. Also known as a trusted certificate authority.

When the operation is finished, callback will be called. You can then call `gcr_trust_is_certificate_anchored_finish()` to get the result of the operation.

`certificate` : | a GcrCertificate to check
`purpose` : | the purpose string
`cancellable` : | a GCancellable
`callback` : | a GAsyncReadyCallback to call when the operation completes
`user_data` : | the data to pass to callback function

### gcr_trust_is_certificate_anchored_finish ()

    gboolean            gcr_trust_is_certificate_anchored_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous operation started by `gcr_trust_is_certificate_anchored_async()`.

In the case of an error, `FALSE` is also returned. Check `error` to detect if an error occurred.

`result` : | the GAsyncResult passed to the callback
`error` : | a GError, or NULL
Returns : | `TRUE` if the certificate is a trust anchor

### gcr_trust_is_certificate_pinned ()

    gboolean            gcr_trust_is_certificate_pinned     (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GError **error);

Check if `certificate` is pinned for `purpose` to communicate with `peer`. A pinned certificate overrides all other certificate verification.

This call may block, see `gcr_trust_is_certificate_pinned_async()` for the non-blocking version.

In the case of an error, `FALSE` is also returned. Check `error` to detect if an error occurred.

`certificate` : | a GcrCertificate to check
`purpose` : | the purpose string
`peer` : | the peer for this pinned
`cancellable` : | a GCancellable
`error` : | a GError, or NULL
Returns : | `TRUE` if the certificate is pinned for the host and purpose

### gcr_trust_is_certificate_pinned_async ()

    void                gcr_trust_is_certificate_pinned_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Check if `certificate` is pinned for `purpose` to communicate with `peer`. A pinned certificate overrides all other certificate verification.

When the operation is finished, callback will be called. You can then call `gcr_trust_is_certificate_pinned_finish()` to get the result of the operation.

`certificate` : | a GcrCertificate to check
`purpose` : | the purpose string
`peer` : | the peer for this pinned
`cancellable` : | a GCancellable
`callback` : | a GAsyncReadyCallback to call when the operation completes
`user_data` : | the data to pass to callback function

### gcr_trust_is_certificate_pinned_finish ()

    gboolean            gcr_trust_is_certificate_pinned_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous operation started by `gcr_trust_is_certificate_pinned_async()`.

In the case of an error, `FALSE` is also returned. Check `error` to detect if an error occurred.

`result` : | the GAsyncResult passed to the callback
`error` : | a GError, or NULL
Returns : | `TRUE` if the certificate is pinned.

### gcr_trust_add_pinned_certificate ()

    gboolean            gcr_trust_add_pinned_certificate    (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GError **error);

Add a pinned `certificate` for connections to `peer` for `purpose`. A pinned certificate overrides all other certificate verification and should be used with care.

If the same pinned certificate already exists, then this operation does not add another, and succeeds without error.

This call may block, see `gcr_trust_add_pinned_certificate_async()` for the non-blocking version.

`certificate` : | a GcrCertificate
`purpose` : | the purpose string
`peer` : | the peer for this pinned certificate
`cancellable` : | a GCancellable
`error` : | a GError, or NULL
Returns : | `TRUE` if the pinned certificate is recorded successfully

### gcr_trust_add_pinned_certificate_async ()

    void                gcr_trust_add_pinned_certificate_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Add a pinned certificate for communication with `peer` for `purpose`. A pinned certificate overrides all other certificate verification and should be used with care.

If the same pinned certificate already exists, then this operation does not add another, and succeeds without error.

When the operation is finished, callback will be called. You can then call `gcr_trust_add_pinned_certificate_finish()` to get the result of the operation.

`certificate` : | a GcrCertificate
`purpose` : | the purpose string
`peer` : | the peer for this pinned certificate
`cancellable` : | a GCancellable
`callback` : | a GAsyncReadyCallback to call when the operation completes
`user_data` : | the data to pass to callback function

### gcr_trust_add_pinned_certificate_finish ()

    gboolean            gcr_trust_add_pinned_certificate_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous operation started by `gcr_trust_add_pinned_certificate_async()`.

`result` : | the GAsyncResult passed to the callback
`error` : | a GError, or NULL
Returns : | `TRUE` if the pinned certificate is recorded successfully

### gcr_trust_remove_pinned_certificate ()

    gboolean            gcr_trust_remove_pinned_certificate (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GError **error);

Remove a pinned certificate for communication with `peer` for `purpose`.

If the same pinned certificate does not exist, or was already removed, then this operation succeeds without error.

This call may block, see `gcr_trust_remove_pinned_certificate_async()` for the non-blocking version.

`certificate` : | a GcrCertificate
`purpose` : | the purpose string
`peer` : | the peer for this pinned certificate
`cancellable` : | a GCancellable
`error` : | a GError, or NULL
Returns : | `TRUE` if the pinned certificate no longer exists

### gcr_trust_remove_pinned_certificate_async ()

    void                gcr_trust_remove_pinned_certificate_async
                                                            (GcrCertificate *certificate,
                                                             const gchar *purpose,
                                                             const gchar *peer,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Remove a pinned certificate for communication with `peer` for `purpose`.

If the same pinned certificate does not exist, or was already removed, then this operation succeeds without error.

When the operation is finished, callback will be called. You can then call `gcr_trust_remove_pinned_certificate_finish()` to get the result of the operation.

`certificate` : | a GcrCertificate
`purpose` : | the purpose string
`peer` : | the peer for this pinned certificate
`cancellable` : | a GCancellable
`callback` : | a GAsyncReadyCallback to call when the operation completes
`user_data` : | the data to pass to callback function

### gcr_trust_remove_pinned_certificate_finish ()

    gboolean            gcr_trust_remove_pinned_certificate_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous operation started by `gcr_trust_remove_pinned_certificate_async()`.

`result` : | the GAsyncResult passed to the callback
`error` : | a GError, or NULL
Returns : | `TRUE` if the pinned certificate no longer exists