InfCertificateVerify: libinfinity-0.7 Reference Manual

## InfCertificateVerify InfCertificateVerify — Server certificate verification. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfCertificateVerify * | inf_certificate_verify_new ()
void | inf_certificate_verify_checked ()

## Properties

gchar * | 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

struct | InfCertificateVerify
struct | InfCertificateVerifyClass
enum | InfCertificateVerifyFlags

## 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”         gchar *

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