Gcr.CertificateChain¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`add` (certificate)
	`build` (purpose, peer, flags, cancellable)
	`build_async` (purpose, peer, flags, cancellable, callback, *user_data)
	`build_finish` (result)
	`get_anchor` ()
	`get_certificate` (index)
	`get_endpoint` ()
	`get_length` ()
	`get_status` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`length`	`int`	r	Length of certificate chain

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Gcr.CertificateChain(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gcr.CertificateChainClass

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 [ctor`CertificateChain`.new] and then add the certificates with [method`CertificateChain`.add].

You can then use [method`CertificateChain`.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 [method`CertificateChain`.get_status]. The status signifies whether the chain is anchored on a trust root, self-signed, incomplete etc. See [enum`CertificateChainStatus`] 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.

classmethod new()[source]¶

Returns:: a newly allocated certificate chain
Return type:: Gcr.CertificateChain

Create a new Gcr.CertificateChain.

add(certificate)[source]¶

Parameters:: certificate (Gcr.Certificate) – a Gcr.Certificate to add to the chain

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.CertificateChain.build()) resets the type of the certificate chain to Gcr.CertificateChainStatus.UNKNOWN

build(purpose, peer, flags, cancellable)[source]¶

Parameters:

purpose (str) – the purpose the certificate chain will be used for
peer (str or None) – the peer the certificate chain will be used with, or None
flags (Gcr.CertificateChainFlags) – chain completion flags
cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None

Raises:

GLib.Error

Returns:

whether the operation completed successfully

Return type:

bool

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 None then no pinned certificates will be considered.

If the Gcr.CertificateChainFlags.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.CertificateChain.build_async() for the asynchronous version.

build_async(purpose, peer, flags, cancellable, callback, *user_data)[source]¶

Parameters:

purpose (str) – the purpose the certificate chain will be used for
peer (str or None) – the peer the certificate chain will be used with, or None
flags (Gcr.CertificateChainFlags) – chain completion flags
cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None
callback (Gio.AsyncReadyCallback or None) – this will be called when the operation completes.
user_data (object or None) – data to pass to the callback

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 None then no pinned certificates will be considered.

If the Gcr.CertificateChainFlags.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.CertificateChain.build_finish() to get the result of the operation.

build_finish(result)[source]¶

Parameters:: result (Gio.AsyncResult) – the Gio.AsyncResult passed to the callback
Raises:: GLib.Error
Returns:: whether the operation succeeded
Return type:: bool

Finishes an asynchronous operation started by Gcr.CertificateChain.build_async().

get_anchor()[source]¶

Returns:: the anchor certificate, or None if not anchored.
Return type:: Gcr.Certificate

If the certificate chain has been built and is of status Gcr.CertificateChainStatus.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.

get_certificate(index)[source]¶

Parameters:: index (int) – index of the certificate to get
Returns:: the certificate
Return type:: Gcr.Certificate

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

get_endpoint()[source]¶

Returns:: the endpoint certificate, or None if the chain is empty
Return type:: Gcr.Certificate

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

get_length()[source]¶

Returns:: the length of the certificate chain
Return type:: int

Get the length of the certificate chain.

get_status()[source]¶

Returns:: the status of the certificate chain.
Return type:: Gcr.CertificateChainStatus

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

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

Property Details¶

Gcr.CertificateChain.props.length¶

Name:: length
Type:: int
Default Value:: 0
Flags:: READABLE

The length of the certificate chain.