InfXmppConnection

InfXmppConnection

Synopsis

void                (*InfXmppConnectionCrtCallback)     (InfXmppConnection *xmpp,
                                                         InfCertificateChain *chain,
                                                         gpointer user_data);
enum                InfXmppConnectionSite;
enum                InfXmppConnectionSecurityPolicy;
enum                InfXmppConnectionError;
enum                InfXmppConnectionStreamError;
enum                InfXmppConnectionAuthError;
                    InfXmppConnection;
struct              InfXmppConnectionClass;
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);
gboolean            inf_xmpp_connection_get_tls_enabled (InfXmppConnection *xmpp);
void                inf_xmpp_connection_set_certificate_callback
                                                        (InfXmppConnection *xmpp,
                                                         InfXmppConnectionCrtCallback cb,
                                                         gpointer user_data);
void                inf_xmpp_connection_certificate_verify_continue
                                                        (InfXmppConnection *xmpp);
void                inf_xmpp_connection_certificate_verify_cancel
                                                        (InfXmppConnection *xmpp);
void                inf_xmpp_connection_reset_sasl_authentication
                                                        (InfXmppConnection *xmpp,
                                                         InfSaslContext *new_context,
                                                         const gchar *new_mechanisms);
gboolean            inf_xmpp_connection_retry_sasl_authentication
                                                        (InfXmppConnection *xmpp,
                                                         GError **error);
void                inf_xmpp_connection_set_sasl_error  (InfXmppConnection *xmpp,
                                                         const GError *error);
const GError *      inf_xmpp_connection_get_sasl_error  (InfXmppConnection *xmpp);

Object Hierarchy

  GEnum
   +----InfXmppConnectionSite
  GEnum
   +----InfXmppConnectionSecurityPolicy
  GObject
   +----InfXmppConnection

Implemented Interfaces

InfXmppConnection implements InfXmlConnection.

Properties

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

Description

Details

InfXmppConnectionCrtCallback ()

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


enum InfXmppConnectionSite

typedef enum _InfXmppConnectionSite {
  INF_XMPP_CONNECTION_SERVER,
  INF_XMPP_CONNECTION_CLIENT
} InfXmppConnectionSite;


enum InfXmppConnectionSecurityPolicy

typedef enum _InfXmppConnectionSecurityPolicy {
  /* Server: Do not offer TLS.
   * Client: Only connect if TLS is not required. */
  INF_XMPP_CONNECTION_SECURITY_ONLY_UNSECURED,
  /* Server: Require TLS.
   * Client: Only connect if TLS is available. */
  INF_XMPP_CONNECTION_SECURITY_ONLY_TLS,
  /* Server: Offer both.
   * Client: Use unsecured communication unless TLS is required */
  INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_UNSECURED,
  /* Server: Offer both.
   * Client: Use TLS-secured communication unless TLS is not available. */
  INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS
} InfXmppConnectionSecurityPolicy;


enum InfXmppConnectionError

typedef enum _InfXmppConnectionError {
  /* Server does not support TLS */
  INF_XMPP_CONNECTION_ERROR_TLS_UNSUPPORTED,
  /* The server requires TLS, but we don't want TLS */
  INF_XMPP_CONNECTION_ERROR_TLS_REQUIRED,
  /* Got <failure> as response to <starttls> */
  INF_XMPP_CONNECTION_ERROR_TLS_FAILURE,
  /* The server did not provide a certificate */
  INF_XMPP_CONNECTION_ERROR_NO_CERTIFICATE_PROVIDED,
  /* The server certificate is not trusted */
  INF_XMPP_CONNECTION_ERROR_CERTIFICATE_NOT_TRUSTED,
  /* Server does not provide authentication mechanisms */
  INF_XMPP_CONNECTION_ERROR_AUTHENTICATION_UNSUPPORTED,
  /* Server does not offer a suitable machnism */
  INF_XMPP_CONNECTION_ERROR_NO_SUITABLE_MECHANISM,

  INF_XMPP_CONNECTION_ERROR_FAILED
} InfXmppConnectionError;


enum InfXmppConnectionStreamError

typedef enum _InfXmppConnectionStreamError {
  INF_XMPP_CONNECTION_STREAM_ERROR_BAD_FORMAT,
  INF_XMPP_CONNECTION_STREAM_ERROR_BAD_NAMESPACE_PREFIX,
  INF_XMPP_CONNECTION_STREAM_ERROR_CONFLICT,
  INF_XMPP_CONNECTION_STREAM_ERROR_CONNECTION_TIMEOUT,
  INF_XMPP_CONNECTION_STREAM_ERROR_HOST_GONE,
  INF_XMPP_CONNECTION_STREAM_ERROR_HOST_UNKNOWN,
  INF_XMPP_CONNECTION_STREAM_ERROR_IMPROPER_ADDRESSING,
  INF_XMPP_CONNECTION_STREAM_ERROR_INTERNAL_SERVER_ERROR,
  INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_FROM,
  INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_ID,
  INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_NAMESPACE,
  INF_XMPP_CONNECTION_STREAM_ERROR_INVALID_XML,
  INF_XMPP_CONNECTION_STREAM_ERROR_NOT_AUTHORIZED,
  INF_XMPP_CONNECTION_STREAM_ERROR_POLICY_VIOLATION,
  INF_XMPP_CONNECTION_STREAM_ERROR_REMOTE_CONNECTION_FAILED,
  INF_XMPP_CONNECTION_STREAM_ERROR_RESOURCE_CONSTRAINT,
  INF_XMPP_CONNECTION_STREAM_ERROR_RESTRICTED_XML,
  INF_XMPP_CONNECTION_STREAM_ERROR_SEE_OTHER_HOST,
  INF_XMPP_CONNECTION_STREAM_ERROR_SYSTEM_SHUTDOWN,
  INF_XMPP_CONNECTION_STREAM_ERROR_UNDEFINED_CONDITION,
  INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_ENCODING,
  INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_STANZA_TYPE,
  INF_XMPP_CONNECTION_STREAM_ERROR_UNSUPPORTED_VERSION,
  INF_XMPP_CONNECTION_STREAM_ERROR_XML_NOT_WELL_FORMED,

  INF_XMPP_CONNECTION_STREAM_ERROR_FAILED
} InfXmppConnectionStreamError;


enum InfXmppConnectionAuthError

typedef enum _InfXmppConnectionAuthError {
  INF_XMPP_CONNECTION_AUTH_ERROR_ABORTED,
  INF_XMPP_CONNECTION_AUTH_ERROR_INCORRECT_ENCODING,
  INF_XMPP_CONNECTION_AUTH_ERROR_INVALID_AUTHZID,
  INF_XMPP_CONNECTION_AUTH_ERROR_INVALID_MECHANISM,
  INF_XMPP_CONNECTION_AUTH_ERROR_MECHANISM_TOO_WEAK,
  INF_XMPP_CONNECTION_AUTH_ERROR_NOT_AUTHORIZED,
  INF_XMPP_CONNECTION_AUTH_ERROR_TEMPORARY_AUTH_FAILURE,

  INF_XMPP_CONNECTION_AUTH_ERROR_FAILED
} InfXmppConnectionAuthError;


InfXmppConnection

typedef struct _InfXmppConnection InfXmppConnection;


struct InfXmppConnectionClass

struct InfXmppConnectionClass {
  GObjectClass parent_class;
};


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.

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.

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

xmpp :

A InfXmppConnection.

Returns :

TRUE if TLS is enabled and FALSE otherwise.

inf_xmpp_connection_set_certificate_callback ()

void                inf_xmpp_connection_set_certificate_callback
                                                        (InfXmppConnection *xmpp,
                                                         InfXmppConnectionCrtCallback cb,
                                                         gpointer user_data);

This function sets a callback that is called when the connection needs to verify the server'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.

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

xmpp :

A InfXmppConnection.

cb :

Function to be called to verify the server 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 server's certificate. The connection process will then continue.

xmpp :

A InfXmppConnection.

inf_xmpp_connection_certificate_verify_cancel ()

void                inf_xmpp_connection_certificate_verify_cancel
                                                        (InfXmppConnection *xmpp);

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

xmpp :

A InfXmppConnection.

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.

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.

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.

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

xmpp :

A InfXmppConnection.

Returns :

A pointer to a GError object owned by xmpp.

Property Details

The "credentials" property

  "credentials"              InfCertificateCredentials*  : Read / Write / Construct Only

The certificate credentials for GnuTLS.


The "local-hostname" property

  "local-hostname"           gchar*                : Read / Write / Construct Only

The hostname of the local host.

Default value: NULL


The "remote-hostname" property

  "remote-hostname"          gchar*                : Read / Write / Construct Only

The hostname of the remote host.

Default value: NULL


The "sasl-context" property

  "sasl-context"             InfSaslContext*       : Read / Write / Construct Only

The SASL context used for authentication.


The "sasl-mechanisms" property

  "sasl-mechanisms"          gchar*                : Read / Write / Construct Only

Whitespace separated list of SASL mechanisms to accept/offer.

Default value: NULL


The "security-policy" property

  "security-policy"          InfXmppConnectionSecurityPolicy  : Read / Write / Construct Only

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

Default value: INF_XMPP_CONNECTION_SECURITY_BOTH_PREFER_TLS


The "site" property

  "site"                     InfXmppConnectionSite  : Read / Write / Construct Only

Site of the connection (client or server).

Default value: INF_XMPP_CONNECTION_CLIENT


The "tcp-connection" property

  "tcp-connection"           InfTcpConnection*     : Read / Write / Construct Only

Underlaying TCP connection.


The "tls-enabled" property

  "tls-enabled"              gboolean              : Read

Whether TLS is enabled for the connection or not.

Default value: FALSE