InfCertificateVerify

InfCertificateVerify — Server certificate verification.

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

char * known-hosts-file Read / Write
InfXmppManager * xmpp-manager Read / Write / Construct Only

Signals

void check-cancelled Run Last
void check-certificate Run Last

Types and Values

Object Hierarchy

    GFlags
    ╰── InfCertificateVerifyFlags
    GObject
    ╰── InfCertificateVerify

Includes

#include <libinfinity/common/inf-certificate-verify.h>

Description

InfCertificateVerify attempts to verify server certificates. It is associated to a InfXmppManager, and all client-side connections managed by that manager will be checked.

The policy enforced by InfCertificateVerify is such that if the certificate is not valid, signed with a weak algorithm, expired, or not yet activated, to reject the certificate. On the other hand, if the certificate itself is valid and the hostname that it is issued to matches the hostname of the connection, and its CA is trusted, then the certificate is accepted.

However, if the certificate as such is valid but either the hostname does not match or the CA is not trusted (for example if a self-signed certificate is used), then certificate pinning takes effect. If the certificate is not pinned, the “check-certificate” is emitted, which should cause the certificate to be checked manually, e.g. by presenting it to the user. Once the check is complete, call inf_certificate_verify_checked(). If the check is positive, the certificate is pinned, so that next time a connection to the same hostname presents the same certificate, it is accepted automatically. If a different certificate than the pinned one is being presented, then the “check-certificate” signal is emitted again.

Functions

inf_certificate_verify_new ()

InfCertificateVerify *
inf_certificate_verify_new (InfXmppManager *xmpp_manager,
                            const gchar *known_hosts_file);

Creates a new InfCertificateVerify. For each new client-side InfXmppConnection in xmpp_manager , the certificate manager will verify the server's certificate.

If the certificate is contained in known_hosts_file , or is issued by a trusted CA, then the certificate is accepted automatically. Otherwise, the “check-certificate” signal is emitted for a manual check of the certificate to be performed.

[constructor]

Parameters

xmpp_manager

The InfXmppManager whose InfXmppConnections to manage the certificates for.

 

known_hosts_file

Path pointing to a file that contains certificates of known hosts, or NULL.

[type filename][allow-none]

Returns

A new InfCertificateVerify.

[transfer full]


inf_certificate_verify_checked ()

void
inf_certificate_verify_checked (InfCertificateVerify *verify,
                                InfXmppConnection *connection,
                                gboolean result);

This function should be called as a response to the “check-certificate” signal being emitted.

Parameters

verify

A InfCertificateVerify.

 

connection

The InfXmppConnection whose certificate has been checked.

 

result

TRUE if the certificate of connection should be accepted, or FALSE if it should be rejected.

 

Types and Values

struct InfCertificateVerify

struct InfCertificateVerify;

InfCertificateVerify is an opaque data type. You should only access it via the public API functions.


struct InfCertificateVerifyClass

struct InfCertificateVerifyClass {
  void (*check_certificate)(InfCertificateVerify* verify,
                            InfXmppConnection* connection,
                            InfCertificateChain* certificate_chain,
                            gnutls_x509_crt_t pinned_certificate,
                            InfCertificateVerifyFlags flags);

  void (*check_cancelled)(InfCertificateVerify* verify,
                          InfXmppConnection* connection);
};

This structure contains default signal handlers for InfCertificateVerify.

Members

check_certificate ()

Default signal handler for the “check-certificate” signal.

 

check_cancelled ()

   

enum InfCertificateVerifyFlags

Various flags for why a certificate is not trusted.

Members

INF_CERTIFICATE_VERIFY_HOSTNAME_MISMATCH

The hostname of the machine connected to does not match the one from the certificate.

 

INF_CERTIFICATE_VERIFY_ISSUER_NOT_KNOWN

The issuer of the certificate is not trusted, i.e. is not in the list of trusted CAs.

 

INF_CERTIFICATE_VERIFY_NOT_PINNED

We have pinned a certificate for this host, but the certificate presented is a different one.

 

Property Details

The “known-hosts-file” property

  “known-hosts-file”         char *

File containing certificates of known hosts.

Owner: InfCertificateVerify

Flags: Read / Write

Default value: NULL


The “xmpp-manager” property

  “xmpp-manager”             InfXmppManager *

The XMPP manager of registered connections.

Owner: InfCertificateVerify

Flags: Read / Write / Construct Only

Signal Details

The “check-cancelled” signal

void
user_function (InfCertificateVerify *verify,
               InfXmppConnection    *connection,
               gpointer              user_data)

This signal is emitted when a manual certificate check as initiated with the “check-certificate” signal should be cancelled. After this signal has been emitted, inf_certificate_verify_checked() should not be called anymore for the specified connection.

This typically happens when the connection to the remote host is lost while the certificate check is in progress.

Parameters

verify

The InfCertificateVerify emitting the signal.

 

connection

The connection to the remote host whose certificate is being verified.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “check-certificate” signal

void
user_function (InfCertificateVerify     *verify,
               InfXmppConnection        *connection,
               InfCertificateChain      *certificate_chain,
               gpointer                  pinned_certificate,
               InfCertificateVerifyFlags flags,
               gpointer                  user_data)

This signal is emitted every time a certificate presented by a remote host needs to be checked manually. This happens when the issuer of the certificate is not in the list of trusted CAs, or the certificate was issued for a different hostname than we expected. In this case, if the certificate is accepted manually, it will be pinned, so that next time a connection is made to the same host under the same hostname, the certificate is accepted automatically.

Consumers of this class should listen to this signal and call inf_certificate_verify_checked() when they finished the manual certificate check.

The pinned_certificate instance is valid until either inf_certificate_verify_checked() is called or the “check-cancelled” signal is emitted.

Parameters

verify

The InfCertificateVerify emitting the signal.

 

connection

The connection to the remote host whose certificate is being verified.

 

certificate_chain

The certificate chain presented by the remote host.

 

pinned_certificate

The certificate that we have pinned for this host, or NULL.

 

flags

Flags explaining why this certificate needs to be checked.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

InfXmppConnection