Top |
Functions
Types and Values
struct | GcrCertificateChain |
struct | GcrCertificateChainClass |
enum | GcrCertificateChainStatus |
enum | GcrCertificateChainFlags |
#define | GCR_TYPE_CERTIFICATE_CHAIN_FLAGS |
#define | GCR_TYPE_CERTIFICATE_CHAIN_STATUS |
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.
Functions
gcr_certificate_chain_new ()
GcrCertificateChain *
gcr_certificate_chain_new (void
);
Create a new 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
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.
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.
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.
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.
gcr_certificate_chain_get_length ()
guint
gcr_certificate_chain_get_length (GcrCertificateChain *self
);
Get the length of the certificate chain.
gcr_certificate_chain_build ()
gboolean gcr_certificate_chain_build (GcrCertificateChain *self
,const gchar *purpose
,const gchar *peer
,GcrCertificateChainFlags 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_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.
gcr_certificate_chain_build_async ()
void gcr_certificate_chain_build_async (GcrCertificateChain *self
,const gchar *purpose
,const gchar *peer
,GcrCertificateChainFlags 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_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.
Parameters
self |
||
purpose |
the purpose the certificate chain will be used for |
|
peer |
the peer the certificate chain will be used with, or |
[allow-none] |
flags |
chain completion flags |
|
cancellable |
a GCancellable or |
|
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()
.
Types and Values
struct GcrCertificateChainClass
struct GcrCertificateChainClass { GObjectClass parent_class; };
The class for GcrCertificateChain.
enum GcrCertificateChainStatus
The status of a built certificate chain. Will be set to
GCR_CERTIFICATE_CHAIN_UNKNOWN
for certificate chains that have not been
built.
Members
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. |
||
A full chain could not be loaded. The chain does not end with a self-signed certificate, a trusted anchor, or a pinned certificate. |
||
The certificate chain contains a revoked or otherwise explicitly distrusted certificate. The entire chain should be distrusted. |
||
The chain ends with a self-signed certificate. No trust anchor was found. |
||
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. |
||
The chain ends with an anchored certificate. The anchored certificate is not necessarily self-signed. |
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
The length of the certificate chain.
Flags: Read
Default value: 0
The “status”
property
“status” GcrCertificateChainStatus
The certificate chain status. See GcrCertificateChainStatus
Flags: Read
Default value: GCR_CERTIFICATE_CHAIN_UNKNOWN