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"


GCR_PURPOSE_CODE_SIGNING

#define GCR_PURPOSE_CODE_SIGNING "1.3.6.1.5.5.7.3.3"

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


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