InfXmppConnection

InfXmppConnection — Implementation of the XMPP core protocol

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

InfCertificateCredentials * credentials Read / Write / Construct
char * local-hostname Read / Write / Construct Only
char * remote-hostname Read / Write / Construct Only
InfSaslContext * sasl-context Read / Write / Construct
char * sasl-mechanisms Read / Write / Construct
InfXmppConnectionSecurityPolicy security-policy Read / Write / Construct Only
InfXmppConnectionSite site Read / Write / Construct Only
InfTcpConnection * tcp-connection Read / Write / Construct Only
gboolean tls-enabled Read

Types and Values

Object Hierarchy

    GEnum
    ├── InfXmppConnectionSecurityPolicy
    ╰── InfXmppConnectionSite
    GObject
    ╰── InfXmppConnection

Implemented Interfaces

InfXmppConnection implements InfXmlConnection.

Includes

#include <libinfinity/common/inf-xmpp-connection.h>

Description

This class implements the XMPP protocol as defined by RFC 3920. It handles the authentication and authorization. Once the connection is established, XML messages can be sent and received with the API of the InfXmlConnection interface.

Note that any sort of XML messages can be exchanged, and that the XML does not need to adhere to the XMPP standard. It is in the responsibility of the user of this class to send only XML message that the remote counterpart can understand.

Functions

InfXmppConnectionCrtCallback ()

void
(*InfXmppConnectionCrtCallback) (InfXmppConnection *xmpp,
                                 gnutls_session_t session,
                                 InfCertificateChain *chain,
                                 gpointer user_data);

Specifies the callback signature for the certificate callback set with inf_xmpp_connection_set_certificate_callback(). The callback should decide whether to trust the certificate in chain or not.

Parameters

xmpp

The InfXmppConnection validating a certificate.

 

session

The underlying GnuTLS session.

 

chain

The certificate chain presented by the remote host.

 

user_data

Additional data supplied when inf_xmpp_connection_set_certificate_callback() was called.

 

inf_xmpp_connection_error_quark ()

GQuark
inf_xmpp_connection_error_quark (void);

Error domain for generic connection errors. Errors in this domain will be from the InfXmppConnectionError enumeration. See GError for information on error domains.


inf_xmpp_connection_new ()

InfXmppConnection *
inf_xmpp_connection_new (InfTcpConnection *tcp,
                         InfXmppConnectionSite site,
                         const gchar *local_hostname,
                         const gchar *remote_hostname,
                         InfXmppConnectionSecurityPolicy security_policy,
                         InfCertificateCredentials *creds,
                         InfSaslContext *sasl_context,
                         const gchar *sasl_mechanisms);

Creates a new InfXmppConnection with tcp as communication channel. No attempt is being made to open tcp , if it is not already open. However, communication is initiated as soon as tcp gets into INF_TCP_CONNECTION_CONNECTED state, so you might still open it lateron yourself.

local_hostname specifies the hostname of the local host, and remote_hostname specifies the hostname of the remote host, as known to the caller. These can be a string representation of the IP address of tcp , or a DNS name such as "example.com". local_hostname can be NULL in which case the host name as reported by g_get_host_name() is used.

creds may be NULL in which case the connection creates the credentials as soon as they are required. However, this only works if site is INF_XMPP_CONNECTION_CLIENT or security_policy is INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED (or both, of course). For server connections creds must contain a valid server certificate in case security_policy is not INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED. creds can contain a certificate for the client site and, if so, is used for client authentication.

If sasl_context is NULL, InfXmppConnection uses a built-in context that only supports ANONYMOUS authentication. In sasl_context 's callback function, the InfXmppConnection for which the authentication shall be performed can be accessed via the session_data parameter of InfSaslContextCallbackFunc.

If sasl_context is not NULL, then the sasl_mechanisms parameter defines what SASL mechanisms are used. On the server side, these are the mechanisms offered to the client, and on the client side, these are the accepted mechanisms (meaning that if a server does not offer any of these, the connection will be closed). If sasl_context is NULL, then this parameter is ignored. sasl_mechanisms can be NULL in which case all available mechanisms are accepted or offered, respectively.

[constructor]

Parameters

tcp

The underlaying TCP connection to use.

 

site

Whether this is a XMPP client or server.

 

local_hostname

The hostname of the local host, or NULL.

[allow-none]

remote_hostname

The hostname of the remote host.

 

security_policy

Whether to use (or offer, as a server) TLS. See InfXmppConnectionSecurityPolicy for the meaning of this parameter.

 

creds

Certificate credentials used to secure the communication.

[allow-none]

sasl_context

A SASL context used for authentication.

[allow-none]

sasl_mechanisms

A whitespace-separated list of SASL mechanisms to accept/offer, or NULL.

[allow-none]

Returns

A new InfXmppConnection.

[transfer full]


inf_xmpp_connection_get_tls_enabled ()

gboolean
inf_xmpp_connection_get_tls_enabled (InfXmppConnection *xmpp);

Returns whether TLS encryption is enabled for xmpp . This returns TRUE as soon as the TLS handshake is completed but before the server certificate was verified (see inf_xmpp_connection_set_certificate_callback()).

Parameters

xmpp

A InfXmppConnection.

 

Returns

TRUE if TLS is enabled and FALSE otherwise.


inf_xmpp_connection_get_own_certificate ()

gnutls_x509_crt_t
inf_xmpp_connection_get_own_certificate
                               (InfXmppConnection *xmpp);

Returns the local host's certificate that was used to authenticate with the remote host, or NULL if no certificate was used. This function can only be used after the TLS handshake has completed, see inf_xmpp_connection_get_tls_enabled().

Parameters

xmpp

A InfXmppConnection.

 

Returns

The certificate of the local host. The returned value should not be freed, it is owned by the InfXmppConnection.

[transfer none]


inf_xmpp_connection_get_peer_certificate ()

InfCertificateChain *
inf_xmpp_connection_get_peer_certificate
                               (InfXmppConnection *xmpp);

Returns the certificate chain that the remote host authenticated itself with. This function can only be used after the TLS handshake has completed, see inf_xmpp_connection_get_tls_enabled().

Parameters

xmpp

A InfXmppConnection.

 

Returns

The certificate chain of the remote host. The returned value should not be freed, it is owned by the InfXmppConnection.

[transfer none]


inf_xmpp_connection_get_kx_algorithm ()

gnutls_kx_algorithm_t
inf_xmpp_connection_get_kx_algorithm (InfXmppConnection *xmpp);

Returns the key exchange algorithm used for this connection. This function can only be used if inf_xmpp_connection_get_tls_enabled() returns true.

Parameters

xmpp

A InfXmppConnection.

 

Returns

The key exchange algorithm used.


inf_xmpp_connection_get_cipher_algorithm ()

gnutls_cipher_algorithm_t
inf_xmpp_connection_get_cipher_algorithm
                               (InfXmppConnection *xmpp);

Returns the cipher algorithm used for this connection. This function can only be used if inf_xmpp_connection_get_tls_enabled() returns true.

Parameters

xmpp

A InfXmppConnection.

 

Returns

The cipher algorithm used.


inf_xmpp_connection_get_mac_algorithm ()

gnutls_mac_algorithm_t
inf_xmpp_connection_get_mac_algorithm (InfXmppConnection *xmpp);

Returns the MAC algorithm used for this connection. This function can only be used if inf_xmpp_connection_get_tls_enabled() returns true.

Parameters

xmpp

A InfXmppConnection.

 

Returns

The MAC algorithm used.


inf_xmpp_connection_get_tls_protocol ()

gnutls_protocol_t
inf_xmpp_connection_get_tls_protocol (InfXmppConnection *xmpp);

Returns the TLS protocol version used for this connection. This function can only be used if inf_xmpp_connection_get_tls_enabled() returns true.

Parameters

xmpp

A InfXmppConnection.

 

Returns

The TLS protocol version used.


inf_xmpp_connection_get_dh_prime_bits ()

guint
inf_xmpp_connection_get_dh_prime_bits (InfXmppConnection *xmpp);

Returns the number of prime bits used for the Diffie-Hellman group if a key exchange algorithm based on Diffie-Hellman is used. Otherwise, 0 is returned. This function can only be used if inf_xmpp_connection_get_tls_enabled() returns true.

Parameters

xmpp

A InfXmppConnection.

 

Returns

The number of Diffie-Hellman prime bits.


inf_xmpp_connection_set_certificate_callback ()

void
inf_xmpp_connection_set_certificate_callback
                               (InfXmppConnection *xmpp,
                                gnutls_certificate_request_t req,
                                InfXmppConnectionCrtCallback cb,
                                gpointer user_data,
                                GDestroyNotify notify);

This function sets a callback that is called when the connection needs to verify the peer's certificate. It does not need to respond immediately, but can, for example, show a dialog to a user and continue when the user finished with it.

When the certificate is trusted, then call inf_xmpp_connection_certificate_verify_continue(), otherwise inf_xmpp_connection_certificate_verify_cancel(). This can happen in the callback or some time later. The connection process is stopped until either of these functions is called.

Note that the function is also called if the peer did not send a certificate, in which case the certificate chain parameter in the callback will be NULL.

If cb is NULL, or this function has not been called before a certificate needs to be verified, then the certificate is always trusted.

Parameters

xmpp

A InfXmppConnection.

 

req

Whether to request a client certificate from the peer.

[type int]

cb

Function to be called to verify the peer's certificate, or NULL.

[allow-none]

user_data

Additional data to pass to the callback function.

 

notify

Function to call to free the user data, or NULL.

[allow-none]

inf_xmpp_connection_certificate_verify_continue ()

void
inf_xmpp_connection_certificate_verify_continue
                               (InfXmppConnection *xmpp);

Call this function when your callback set in inf_xmpp_connection_set_certificate_callback() was called and you do trust the peer's certificate. The connection process will then continue.

Parameters

xmpp

A InfXmppConnection.

 

inf_xmpp_connection_certificate_verify_cancel ()

void
inf_xmpp_connection_certificate_verify_cancel
                               (InfXmppConnection *xmpp,
                                const GError *error);

Call this function when your callback set in inf_xmpp_connection_set_certificate_callback() was called and you do not trust the peer's certificate. The connection will then be closed with a corresponding error.

If error is non-NULL, then it should contain a reason why the certificate was not trusted. If you verified the peer's certificate with gnutls_certificate_verify_peers2(), or gnutls_x509_crt_list_verify(), then a corresponding error can be generated with the verification result with inf_gnutls_certificate_verification_set_error(). The reason is then shown to the local user.

Parameters

xmpp

A InfXmppConnection.

 

error

Reason why the certificate is not trusted, or NULL.

 

inf_xmpp_connection_reset_sasl_authentication ()

void
inf_xmpp_connection_reset_sasl_authentication
                               (InfXmppConnection *xmpp,
                                InfSaslContext *new_context,
                                const gchar *new_mechanisms);

Sets a new SASL context and mechanisms to use for authentication. This does not have any effect if authentication has already been performed. This can be useful if a server decides to use a stricter authentication policy and gets away with its previous SASL context. If new_context is NULL, then a built-in SASL context is used which only accepts anonymous authentication.

If the authentication is currently in progress then it is aborted. The server sends an INF_XMPP_CONNECTION_AUTH_ERROR_TEMPORARY_AUTH_FAILURE error to the client with INF_AUTHENTICATION_DETAIL_ERROR_TRY_AGAIN detail (see inf_xmpp_connection_get_sasl_error()).

On the client side, if authentication is in progress, a request to abort the authentication is sent to the server. The server will then reply with an INF_XMPP_CONNECTION_AUTH_ERROR_ABORTED error. In the signal handler of the “error” signal you should reinitiate the authentication with inf_xmpp_connection_retry_sasl_authentication() or the connection will be closed. It is also possible that the final authentication request has already been sent, and the server replies with successful authentication instead. In that case calling this function will have no effect apart from closing and reopening the connection will use the new context and mechanisms.

Parameters

xmpp

A InfXmppConnection.

 

new_context

The new sasl context to set, or NULL.

[allow-none]

new_mechanisms

Allowed SASL mechanisms to use. Ignored if new_context is NULL.

[allow-none]

inf_xmpp_connection_retry_sasl_authentication ()

gboolean
inf_xmpp_connection_retry_sasl_authentication
                               (InfXmppConnection *xmpp,
                                GError **error);

When SASL authentication failed then the “error” signal is emitted with an error from the INF_XMPP_CONNECTION_AUTH_ERROR domain. If the signal handler wants to retry authentication then it should call this function, possibly modifying the “sasl-mechanisms” property before. If this function is not called then the connection will terminate.

The function can fail if the server does not support any of the available mechanisms given in “sasl-mechanisms”. If so, the function returns FALSE and error is set.

Parameters

xmpp

A InfXmppConnection.

 

error

Location to store error information, if any.

 

Returns

TRUE if auth retry is being performed, FALSE otherwise.


inf_xmpp_connection_set_sasl_error ()

void
inf_xmpp_connection_set_sasl_error (InfXmppConnection *xmpp,
                                    const GError *error);

Sets the SASL error of xmpp . The SASL error is an additional hint of what went wrong during authentication. It should be set on the server side in the gsasl callback checking the user authentication. If on the client side “error” is emitted with an error from the INF_XMPP_CONNECTION_AUTH_ERROR domain then inf_xmpp_connection_get_sasl_error() can be used to obtain more detailed error information.

Parameters

xmpp

A InfXmppConnection.

 

error

The SASL error to set.

 

inf_xmpp_connection_get_sasl_error ()

const GError *
inf_xmpp_connection_get_sasl_error (InfXmppConnection *xmpp);

Gets the SASL error of xmpp . See inf_xmpp_connection_set_sasl_error().

Parameters

xmpp

A InfXmppConnection.

 

Returns

A pointer to a GError object owned by xmpp .

Types and Values

enum InfXmppConnectionSite

Specifies whether the local site of the connection is a client or a server.

Members

INF_XMPP_CONNECTION_SERVER

The local site of this connection is an XMPP server and the remote counterpart is a client.

 

INF_XMPP_CONNECTION_CLIENT

The local site of this connection is a XMPP client and the remote counterpart is a server.

 

enum InfXmppConnectionSecurityPolicy

The InfXmppConnectionSecurityPolicy enumeration specifies various options of how to deal with the other site allowing or requiring TLS-secured connections. Note that if the local site is a server, then INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_UNSECURED and INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS are equivalent.

Members

INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED

In the case of a server, do not offer TLS to the client. As a client, only connect if the server does not require TLS.

 

INF_XMPP_CONNECTION_SECURITY_ONLY_TLS

In the case of a server, require all connections to be TLS-secured. As a client, only connect if the server supports TLS.

 

INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_UNSECURED

In the case of a server, offer both unsecured and secured messaging to the client. As a client, use unsecured communication unless TLS is required by the server.

 

INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS

In the case of a server, offer both unsecured and secured messaging to the client. As a client, use TLS unless not supported by the server.

 

enum InfXmppConnectionError

Specifies the error codes in the INF_XMPP_CONNECTION_ERROR error domain.

Members

INF_XMPP_CONNECTION_ERROR_TLS_UNSUPPORTED

Server does not support TLS, but the security policy is set to INF_XMPP_CONNECTION_SECURITY_ONLY_TLS.

 

INF_XMPP_CONNECTION_ERROR_TLS_REQUIRED

The server requires TLS, but the security policy is set to INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED.

 

INF_XMPP_CONNECTION_ERROR_TLS_FAILURE

Server cannot proceed with the TLS handshake.

 

INF_XMPP_CONNECTION_ERROR_NO_CERTIFICATE_PROVIDED

The server did not provide a certificate.

 

INF_XMPP_CONNECTION_ERROR_CERTIFICATE_NOT_TRUSTED

The server certificate is not trusted. Whether the server certificate is trusted or not is defined by the API user, by providing a certificate callback with inf_xmpp_connection_set_certificate_callback().

 

INF_XMPP_CONNECTION_ERROR_AUTHENTICATION_UNSUPPORTED

The server does not provide any authentication mechanisms.

 

INF_XMPP_CONNECTION_ERROR_NO_SUITABLE_MECHANISM

The server does not offer a suitable authentication mechanism that is accepted by the client.

 

INF_XMPP_CONNECTION_ERROR_FAILED

General error code for otherwise unknown errors.

 

enum InfXmppConnectionStreamError

Specifies the error codes in the INF_XMPP_CONNECTION_STREAM_ERROR error domain. These errors correspond to the ones defined in RFC 3920, section 4.7.3.

Members

INF_XMPP_CONNECTION_STREAM_ERROR_BAD_FORMAT

The entity has sent XML that cannot be processed.

 

INF_XMPP_CONNECTION_STREAM_ERROR_BAD_NAMESPACE_PREFIX

The entity has sent a namespace prefix that is unsupported, or has sent no namespace prefix on an element that requires such a prefix.

 

INF_XMPP_CONNECTION_STREAM_ERROR_CONFLICT

The server is closing the active stream for this entity because a new stream has been initiated that conflicts with the existing stream.

 

INF_XMPP_CONNECTION_STREAM_ERROR_CONNECTION_TIMEOUT

The entity has not generated any traffic over the stream for some period of time.

 

INF_XMPP_CONNECTION_STREAM_ERROR_HOST_GONE

The value of the 'to' attribute provided by the initiating entity in the stream header corresponds to a hostname that is no longer hosted by the server.

 

INF_XMPP_CONNECTION_STREAM_ERROR_HOST_UNKNOWN

The value of the 'to' attribute provided by the initiating entity in the stream header does not correspond to a hostname that is hosted by the server.

 

INF_XMPP_CONNECTION_STREAM_ERROR_IMPROPER_ADDRESSING

A stanza sent between two servers lacks a 'to' or 'from' attribute.

 

INF_XMPP_CONNECTION_STREAM_ERROR_INTERNAL_SERVER_ERROR

The server has experienced a misconfiguration or an otherwise-undefined internal error that prevents it from servicing the stream.

 

INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_FROM

The JID or hostname provided in a 'from' address does not match an authorized JID or validated domain negotiated between servers via SASL or dialback, or between a client and a server via authentication and resource binding.

 

INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_ID

The stream ID or dialback ID is invalid or does not match an ID previously provided.

 

INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_NAMESPACE

The streams namespace is something other than http://etherx.jabber.org/streams or the dialback namespace name is something other than jabber:server:dialback.

 

INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_XML

The entity has sent invalid XML over the stream to a server that performs validation.

 

INF_XMPP_CONNECTION_STREAM_ERROR_NOT_AUTHORIZED

The entity has attempted to send data before the stream has been authenticated, or otherwise is not authorized to perform an action related to stream negotiation.

 

INF_XMPP_CONNECTION_STREAM_ERROR_POLICY_VIOLATION

The entity has violated some local service policy.

 

INF_XMPP_CONNECTION_STREAM_ERROR_REMOTE_CONNECTION_FAILED

The server is unable to properly connect to a remote entity that is required for authentication or authorization.

 

INF_XMPP_CONNECTION_STREAM_ERROR_RESOURCE_CONSTRAINT

The server lacks the system resources necessary to service the stream.

 

INF_XMPP_CONNECTION_STREAM_ERROR_RESTRICTED_XML

The entity has attempted to send restricted XML features.

 

INF_XMPP_CONNECTION_STREAM_ERROR_SEE_OTHER_HOST

The server will not provide service to the initiating entity but is redirecting traffic to another host.

 

INF_XMPP_CONNECTION_STREAM_ERROR_SYSTEM_SHUTDOWN

The server is being shut down and all active streams are being closed.

 

INF_XMPP_CONNECTION_STREAM_ERROR_UNDEFINED_CONDITION

The error condition is not one of those defined by the other conditions.

 

INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_ENCODING

The initiating entity has encoded the stream in an encoding that is not supported by the server.

 

INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_STANZA_TYPE

The initiating entity has sent a first-level child of the stream that is not supported by the server.

 

INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_VERSION

The value of the 'version' attribute provided by the initiating entity in the stream header specifies a version of XMPP that is not supported by the server.

 

INF_XMPP_CONNECTION_STREAM_ERROR_XML_NOT_WELL_FORMED

The initiating entity has sent XML that is not well-formed.

 

INF_XMPP_CONNECTION_STREAM_ERROR_FAILED

General error code for otherwise unknown errors.

 

enum InfXmppConnectionAuthError

Specifies the error codes in the INF_XMPP_CONNECTION_AUTH_ERROR error domain. These errors correspond to the ones defined in RFC 3920, section 6.4.

Members

INF_XMPP_CONNECTION_AUTH_ERROR_ABORTED

The receiving entity acknowledged an <abort/> element sent by the initiating entity.

 

INF_XMPP_CONNECTION_AUTH_ERROR_INCORRECT_ENCODING

The data provided by the initiating entity could not be processed because the Base64 encoding is incorrect.

 

INF_XMPP_CONNECTION_AUTH_ERROR_INVALID_AUTHZID

The authzid provided by the initiating entity is invalid, either because it is incorrectly formatted or because the initiating entity does not have permissions to authorize that ID.

 

INF_XMPP_CONNECTION_AUTH_ERROR_INVALID_MECHANISM

The initiating entity did not provide a mechanism or requested a mechanism that is not supported by the receiving entity.

 

INF_XMPP_CONNECTION_AUTH_ERROR_MECHANISM_TOO_WEAK

The mechanism requested by the initiating entity is weaker than server policy permits for that initiating entity.

 

INF_XMPP_CONNECTION_AUTH_ERROR_NOT_AUTHORIZED

The authentication failed because the initiating entity did not provide valid credentials.

 

INF_XMPP_CONNECTION_AUTH_ERROR_TEMPORARY_AUTH_FAILURE

The authentication failed because of a temporary error condition within the receiving entity.

 

INF_XMPP_CONNECTION_AUTH_ERROR_FAILED

General error code for otherwise unknown errors.

 

struct InfXmppConnection

struct InfXmppConnection;

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


struct InfXmppConnectionClass

struct InfXmppConnectionClass {
};

This structure does not contain any public fields.

Property Details

The “credentials” property

  “credentials”              InfCertificateCredentials *

The certificate credentials for GnuTLS.

Owner: InfXmppConnection

Flags: Read / Write / Construct


The “local-hostname” property

  “local-hostname”           char *

The hostname of the local host.

Owner: InfXmppConnection

Flags: Read / Write / Construct Only

Default value: NULL


The “remote-hostname” property

  “remote-hostname”          char *

The hostname of the remote host.

Owner: InfXmppConnection

Flags: Read / Write / Construct Only

Default value: NULL


The “sasl-context” property

  “sasl-context”             InfSaslContext *

The SASL context used for authentication.

Owner: InfXmppConnection

Flags: Read / Write / Construct


The “sasl-mechanisms” property

  “sasl-mechanisms”          char *

Whitespace separated list of SASL mechanisms to accept/offer.

Owner: InfXmppConnection

Flags: Read / Write / Construct

Default value: NULL


The “security-policy” property

  “security-policy”          InfXmppConnectionSecurityPolicy

How to choose whether to use (or offer, as a server) TLS.

Owner: InfXmppConnection

Flags: Read / Write / Construct Only

Default value: INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS


The “site” property

  “site”                     InfXmppConnectionSite

Site of the connection (client or server).

Owner: InfXmppConnection

Flags: Read / Write / Construct Only

Default value: INF_XMPP_CONNECTION_CLIENT


The “tcp-connection” property

  “tcp-connection”           InfTcpConnection *

Underlaying TCP connection.

Owner: InfXmppConnection

Flags: Read / Write / Construct Only


The “tls-enabled” property

  “tls-enabled”              gboolean

Whether TLS is enabled for the connection or not.

Owner: InfXmppConnection

Flags: Read

Default value: FALSE