Trust Storage and Lookups: Gcr Library Reference Manual

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);

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.