GcrCertificateChain

GcrCertificateChain — A certificate chain

Synopsis

struct              GcrCertificateChain;
struct              GcrCertificateChainClass;
enum                GcrCertificateChainStatus;
GcrCertificateChain * gcr_certificate_chain_new         (void);
void                gcr_certificate_chain_add           (GcrCertificateChain *self,
                                                         GcrCertificate *certificate);
GcrCertificate *    gcr_certificate_chain_get_certificate
                                                        (GcrCertificateChain *self,
                                                         guint index);
GcrCertificateChainStatus gcr_certificate_chain_get_status
                                                        (GcrCertificateChain *self);
GcrCertificate *    gcr_certificate_chain_get_anchor    (GcrCertificateChain *self);
GcrCertificate *    gcr_certificate_chain_get_endpoint  (GcrCertificateChain *self);
guint               gcr_certificate_chain_get_length    (GcrCertificateChain *self);
enum                GcrCertificateChainFlags;
gboolean            gcr_certificate_chain_build         (GcrCertificateChain *self,
                                                         const gchar *purpose,
                                                         const gchar *peer,
                                                         guint flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gcr_certificate_chain_build_async   (GcrCertificateChain *self,
                                                         const gchar *purpose,
                                                         const gchar *peer,
                                                         guint flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gcr_certificate_chain_build_finish  (GcrCertificateChain *self,
                                                         GAsyncResult *result,
                                                         GError **error);
#define             GCR_TYPE_CERTIFICATE_CHAIN_FLAGS
#define             GCR_TYPE_CERTIFICATE_CHAIN_STATUS

Object Hierarchy

  GObject
   +----GcrCertificateChain

Properties

  "length"                   guint                 : Read
  "status"                   GcrCertificateChainStatus  : Read

Description

GcrCertificateChain represents a chain of certificates, normally used to validate the trust in a certificate. An X.509 certificate chain has one endpoint certificate (the one for which trust is being verified) and then in turn the certificate that issued each previous certificate in the chain.

This functionality is for building of certificate chains not for validating them. Use your favorite crypto library to validate trust in a certificate chain once its built.

The order of certificates in the chain should be first the endpoint certificates and then the signing certificates.

Create a new certificate chain with gcr_certificate_chain_new() and then add the certificates with gcr_certificate_chain_add().

You can then use gcr_certificate_chain_build() to build the remainder of the chain. This will lookup missing certificates in PKCS#11 modules and also check that each certificate in the chain is the signer of the previous one. If a trust anchor, pinned certificate, or self-signed certificate is found, then the chain is considered built. Any extra certificates are removed from the chain.

Once the certificate chain has been built, you can access its status through gcr_certificate_chain_get_status(). The status signifies whether the chain is anchored on a trust root, self-signed, incomplete etc. See GcrCertificateChainStatus for information on the various statuses.

It's important to understand that the building of a certificate chain is merely the first step towards verifying trust in a certificate.

Details

struct GcrCertificateChain

struct GcrCertificateChain;

A chain of certificates.

struct GcrCertificateChainClass

struct GcrCertificateChainClass {
	GObjectClass parent_class;
};

The class for GcrCertificateChain.

GObjectClass parent_class;

 The parent class

enum GcrCertificateChainStatus

typedef enum {
	GCR_CERTIFICATE_CHAIN_UNKNOWN,
	GCR_CERTIFICATE_CHAIN_INCOMPLETE,
	GCR_CERTIFICATE_CHAIN_DISTRUSTED,
	GCR_CERTIFICATE_CHAIN_SELFSIGNED,
	GCR_CERTIFICATE_CHAIN_PINNED,
	GCR_CERTIFICATE_CHAIN_ANCHORED,
} GcrCertificateChainStatus;

The status of a built certificate chain. Will be set to GCR_CERTIFICATE_CHAIN_UNKNOWN for certificate chains that have not been built.

GCR_CERTIFICATE_CHAIN_UNKNOWN

 The certificate chain's status is unknown. When a chain is not yet built it has this status. If a chain is modified after being built, it has this status.

GCR_CERTIFICATE_CHAIN_INCOMPLETE

 A full chain could not be loaded. The chain does not end with a self-signed certificate, a trusted anchor, or a pinned certificate.

GCR_CERTIFICATE_CHAIN_DISTRUSTED

 The certificate chain contains a revoked or otherwise explicitly distrusted certificate. The entire chain should be distrusted.

GCR_CERTIFICATE_CHAIN_SELFSIGNED

 The chain ends with a self-signed certificate. No trust anchor was found.

GCR_CERTIFICATE_CHAIN_PINNED

 The chain represents a pinned certificate. A pinned certificate is an exception which trusts a given certificate explicitly for a purpose and communication with a certain peer.

GCR_CERTIFICATE_CHAIN_ANCHORED

 The chain ends with an anchored certificate. The anchored certificate is not necessarily self-signed.

gcr_certificate_chain_new ()

GcrCertificateChain * gcr_certificate_chain_new         (void);

Create a new GcrCertificateChain.

Returns :

 A newly allocated GcrCertificateChain

gcr_certificate_chain_add ()

void                gcr_certificate_chain_add           (GcrCertificateChain *self,
                                                         GcrCertificate *certificate);

Add certificate to the chain. The order of certificates in the chain are important. The first certificate should be the endpoint certificate, and then come the signers (certificate authorities) each in turn. If a root certificate authority is present, it should come last.

Adding a certificate an already built chain (see gcr_certificate_chain_build()) resets the type of the certificate chain to GCR_CERTIFICATE_CHAIN_UNKNOWN

self :

 the GcrCertificateChain

certificate :

 a GcrCertificate to add to the chain

gcr_certificate_chain_get_certificate ()

GcrCertificate *    gcr_certificate_chain_get_certificate
                                                        (GcrCertificateChain *self,
                                                         guint index);

Get a certificate in the chain. It is an error to call this function with an invalid index.

self :

 the GcrCertificateChain

index :

 index of the certificate to get

Returns :

 the certificate

gcr_certificate_chain_get_status ()

GcrCertificateChainStatus gcr_certificate_chain_get_status
                                                        (GcrCertificateChain *self);

Get the status of a certificate chain. If the certificate chain has not been built, then the status will be GCR_CERTIFICATE_CHAIN_UNKNOWN.

A status of GCR_CERTIFICATE_CHAIN_ANCHORED does not mean that the certificate chain has been verified, but merely that an anchor has been found.

self :

 the GcrCertificateChain

Returns :

 the status of the certificate chain.

gcr_certificate_chain_get_anchor ()

GcrCertificate *    gcr_certificate_chain_get_anchor    (GcrCertificateChain *self);

If the certificate chain has been built and is of status GCR_CERTIFICATE_CHAIN_ANCHORED, then this will return the anchor certificate that was found. This is not necessarily a root certificate authority. If an intermediate certificate authority in the chain was found to be anchored, then that certificate will be returned.

If an anchor is returned it does not mean that the certificate chain has been verified, but merely that an anchor has been found.

self :

 the GcrCertificateChain

Returns :

 the anchor certificate, or NULL if not anchored.

gcr_certificate_chain_get_endpoint ()

GcrCertificate *    gcr_certificate_chain_get_endpoint  (GcrCertificateChain *self);

Get the endpoint certificate in the chain. This is always the first certificate in the chain. The endpoint certificate cannot be anchored.

self :

 the GcrCertificateChain

Returns :

 the endpoint certificate, or NULL if the chain is empty.

gcr_certificate_chain_get_length ()

guint               gcr_certificate_chain_get_length    (GcrCertificateChain *self);

Get the length of the certificate chain.

self :

 the GcrCertificateChain

Returns :

 the length of the certificate chain

enum GcrCertificateChainFlags

typedef enum {
	GCR_CERTIFICATE_CHAIN_FLAG_NO_LOOKUPS = 1 << 0,
} GcrCertificateChainFlags;

Flags to be used with the gcr_certificate_chain_build() operation.

GCR_CERTIFICATE_CHAIN_FLAG_NO_LOOKUPS

 If this flag is specified then no lookups for anchors or pinned certificates are done, and the resulting chain will be neither anchored or pinned. Additionally no missing certificate authorities are looked up in PKCS#11.

gcr_certificate_chain_build ()

gboolean            gcr_certificate_chain_build         (GcrCertificateChain *self,
                                                         const gchar *purpose,
                                                         const gchar *peer,
                                                         guint flags,
                                                         GCancellable *cancellable,
                                                         GError **error);

Complete a certificate chain. Once a certificate chain has been built its status can be examined.

This operation will lookup missing certificates in PKCS#11 modules and also that each certificate in the chain is the signer of the previous one. If a trust anchor, pinned certificate, or self-signed certificate is found, then the chain is considered built. Any extra certificates are removed from the chain.

It's important to understand that building of a certificate chain does not constitute verifying that chain. This is merely the first step towards trust verification.

The purpose is a string like GCR_PURPOSE_CLIENT_AUTH and is the purpose for which the certificate chain will be used. Trust anchors are looked up for this purpose. This argument is required.

The peer is usually the host name of the peer whith which this certificate chain is being used. It is used to look up pinned certificates that have been stored for this peer. If NULL then no pinned certificates will be considered.

If the GCR_CERTIFICATE_CHAIN_FLAG_NO_LOOKUPS flag is specified then no lookups for anchors or pinned certificates are done, and the resulting chain will be neither anchored or pinned. Additionally no missing certificate authorities are looked up in PKCS#11

This call will block, see gcr_certificate_chain_build_async() for the asynchronous version.

self :

 the GcrCertificateChain

purpose :

 the purpose the certificate chain will be used for

peer :

 the peer the certificate chain will be used with, or NULL

flags :

 chain completion flags

cancellable :

 a GCancellable or NULL

error :

 a GError or NULL

Returns :

 whether the operation completed successfully

gcr_certificate_chain_build_async ()

void                gcr_certificate_chain_build_async   (GcrCertificateChain *self,
                                                         const gchar *purpose,
                                                         const gchar *peer,
                                                         guint flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Complete a certificate chain. Once a certificate chain has been built its status can be examined.

This will lookup missing certificates in PKCS#11 modules and also that each certificate in the chain is the signer of the previous one. If a trust anchor, pinned certificate, or self-signed certificate is found, then the chain is considered built. Any extra certificates are removed from the chain.

It's important to understand that building of a certificate chain does not constitute verifying that chain. This is merely the first step towards trust verification.

The purpose is a string like GCR_PURPOSE_CLIENT_AUTH and is the purpose for which the certificate chain will be used. Trust anchors are looked up for this purpose. This argument is required.

The peer is usually the host name of the peer whith which this certificate chain is being used. It is used to look up pinned certificates that have been stored for this peer. If NULL then no pinned certificates will be considered.

If the GCR_CERTIFICATE_CHAIN_FLAG_NO_LOOKUPS flag is specified then no lookups for anchors or pinned certificates are done, and the resulting chain will be neither anchored or pinned. Additionally no missing certificate authorities are looked up in PKCS#11

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

self :

 the GcrCertificateChain

purpose :

 the purpose the certificate chain will be used for

peer :

 the peer the certificate chain will be used with, or NULL

flags :

 chain completion flags

cancellable :

 a GCancellable or NULL

callback :

 this will be called when the operation completes.

user_data :

 data to pass to the callback

gcr_certificate_chain_build_finish ()

gboolean            gcr_certificate_chain_build_finish  (GcrCertificateChain *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an asynchronous operation started by gcr_certificate_chain_build_async().

self :

 the GcrCertificateChain

result :

 the GAsyncResult passed to the callback

error :

 a GError, or NULL

Returns :

 whether the operation succeeded

GCR_TYPE_CERTIFICATE_CHAIN_FLAGS

#define GCR_TYPE_CERTIFICATE_CHAIN_FLAGS (gcr_certificate_chain_flags_get_type ())

The flags GType for GcrCertificateChainFlags.

GCR_TYPE_CERTIFICATE_CHAIN_STATUS

#define GCR_TYPE_CERTIFICATE_CHAIN_STATUS (gcr_certificate_chain_status_get_type ())

The enum GType for GcrCertificateChainStatus.

Property Details

The "length" property

  "length"                   guint                 : Read

The length of the certificate chain.

Default value: 0

The "status" property

  "status"                   GcrCertificateChainStatus  : Read

The certificate chain status. See GcrCertificateChainStatus

Default value: GCR_CERTIFICATE_CHAIN_UNKNOWN

Generated by GTK-Doc V1.18