Top | ![]() |
![]() |
![]() |
![]() |
gchar * | known-hosts-file | Read / Write |
InfXmppManager * | xmpp-manager | Read / Write / Construct Only |
struct | InfCertificateVerify |
struct | InfCertificateVerifyClass |
enum | InfCertificateVerifyFlags |
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.
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]
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 |
[type filename][allow-none] |
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.
verify |
||
connection |
The InfXmppConnection whose certificate has been checked. |
|
result |
|
struct InfCertificateVerify;
InfCertificateVerify is an opaque data type. You should only access it via the public API functions.
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.
Various flags for why a certificate is not trusted.
“known-hosts-file”
property “known-hosts-file” gchar *
File containing certificates of known hosts.
Owner: InfCertificateVerify
Flags: Read / Write
Default value: NULL
“xmpp-manager”
property“xmpp-manager” InfXmppManager *
The XMPP manager of registered connections.
Owner: InfCertificateVerify
Flags: Read / Write / Construct Only
“check-cancelled”
signalvoid 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.
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
“check-certificate”
signalvoid 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.
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 |
|
flags |
Flags explaining why this certificate needs to be checked. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last