## Trust Storage and Lookups

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

## Functions

gboolean | gcr_trust_is_certificate_anchored ()
void | gcr_trust_is_certificate_anchored_async ()
gboolean | gcr_trust_is_certificate_anchored_finish ()
gboolean | gcr_trust_is_certificate_pinned ()
void | gcr_trust_is_certificate_pinned_async ()
gboolean | gcr_trust_is_certificate_pinned_finish ()
gboolean | gcr_trust_add_pinned_certificate ()
void | gcr_trust_add_pinned_certificate_async ()
gboolean | gcr_trust_add_pinned_certificate_finish ()
gboolean | gcr_trust_remove_pinned_certificate ()
void | gcr_trust_remove_pinned_certificate_async ()
gboolean | gcr_trust_remove_pinned_certificate_finish ()

## Types and Values

#define | GCR_PURPOSE_SERVER_AUTH
#define | GCR_PURPOSE_CLIENT_AUTH
#define | GCR_PURPOSE_EMAIL
#define | GCR_PURPOSE_CODE_SIGNING

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

result | the GAsyncResult passed to the callback |
error | a GError, or `NULL` |

#### Returns

`TRUE` if the pinned certificate no longer exists

## Types and Values

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