libinfinity-0.6 Reference Manual: InfXmppConnection

## InfXmppConnection InfXmppConnection — Implementation of the XMPP core protocol |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfXmppConnectionCrtCallback) ()
InfXmppConnection * | inf_xmpp_connection_new ()
gboolean | inf_xmpp_connection_get_tls_enabled ()
gnutls_x509_crt_t | inf_xmpp_connection_get_own_certificate ()
InfCertificateChain * | inf_xmpp_connection_get_peer_certificate ()
void | inf_xmpp_connection_set_certificate_callback ()
void | inf_xmpp_connection_certificate_verify_continue ()
void | inf_xmpp_connection_certificate_verify_cancel ()
void | inf_xmpp_connection_reset_sasl_authentication ()
gboolean | inf_xmpp_connection_retry_sasl_authentication ()
void | inf_xmpp_connection_set_sasl_error ()
const GError * | inf_xmpp_connection_get_sasl_error ()

## Properties

InfCertificateCredentials * | credentials | Read / Write / Construct
gchar * | local-hostname | Read / Write / Construct Only
gchar * | remote-hostname | Read / Write / Construct Only
InfSaslContext * | sasl-context | Read / Write / Construct
gchar * | 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

enum | InfXmppConnectionSite
enum | InfXmppConnectionSecurityPolicy
enum | InfXmppConnectionError
enum | InfXmppConnectionStreamError
enum | InfXmppConnectionAuthError
struct | InfXmppConnection
struct | InfXmppConnectionClass

## 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_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.

#### 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`. |
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. |
sasl_context | A SASL context used for authentication. |
sasl_mechanisms | A whitespace-separated list of SASL mechanisms to accept/offer, or `NULL`. |

#### Returns

A new InfXmppConnection.

### 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.

### 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.

### 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);

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. |
cb | Function to be called to verify the peer's certificate, or `NULL`. |
user_data | Additional data to pass to the callback function. |

### 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`. |
new_mechanisms | Allowed SASL mechanisms to use. Ignored if `new_context` is `NULL`. |

### 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 requsted 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.

Flags: Read / Write / Construct

### The `“local-hostname”` property

      “local-hostname”           gchar *

The hostname of the local host.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“remote-hostname”` property

      “remote-hostname”          gchar *

The hostname of the remote host.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“sasl-context”` property

      “sasl-context”             InfSaslContext *

The SASL context used for authentication.

Flags: Read / Write / Construct

### The `“sasl-mechanisms”` property

      “sasl-mechanisms”          gchar *

Whitespace separated list of SASL mechanisms to accept/offer.

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.

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).

Flags: Read / Write / Construct Only

Default value: INF_XMPP_CONNECTION_CLIENT

### The `“tcp-connection”` property

      “tcp-connection”           InfTcpConnection *

Underlaying TCP connection.

Flags: Read / Write / Construct Only

### The `“tls-enabled”` property

      “tls-enabled”              gboolean

Whether TLS is enabled for the connection or not.

Flags: Read

Default value: FALSE