InfXmppConnection

InfXmppConnection

Synopsis




void                (*InfXmppConnectionCrtCallback)     (InfXmppConnection *xmpp,
                                                         InfCertificateChain *chain,
                                                         gpointer user_data);
enum                InfXmppConnectionSite;
enum                InfXmppConnectionSecurityPolicy;
enum                InfXmppConnectionError;
enum                InfXmppConnectionStreamError;
enum                InfXmppConnectionAuthError;
                    InfXmppConnection;
                    InfXmppConnectionClass;
InfXmppConnection*  inf_xmpp_connection_new             (InfTcpConnection *tcp,
                                                         InfXmppConnectionSite site,
                                                         const gchar *local_hostname,
                                                         const gchar *remote_hostname,
                                                         InfXmppConnectionSecurityPolicy security_policy,
                                                         gnutls_certificate_credentials_t cred,
                                                         Gsasl *sasl_context,
                                                         const gchar *sasl_mechanisms);
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);

Object Hierarchy


  GObject
   +----InfXmppConnection

Implemented Interfaces

InfXmppConnection implements InfXmlConnection.

Properties


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

Description

Details

InfXmppConnectionCrtCallback ()

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

xmpp :

chain :

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;


InfXmppConnectionClass

typedef struct {
  GObjectClass parent_class;
} InfXmppConnectionClass;


inf_xmpp_connection_new ()

InfXmppConnection*  inf_xmpp_connection_new             (InfTcpConnection *tcp,
                                                         InfXmppConnectionSite site,
                                                         const gchar *local_hostname,
                                                         const gchar *remote_hostname,
                                                         InfXmppConnectionSecurityPolicy security_policy,
                                                         gnutls_certificate_credentials_t cred,
                                                         Gsasl *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.

cred 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 cred 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 the sasl_context's callback function, the InfXmppConnection for which the authentication shall be performed can be retrieved with gsasl_session_hook_get().

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.

cred :

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

Property Details

The "credentials" property

  "credentials"              gpointer              : 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"             gpointer              : Read / Write / Construct Only

The GnuSASL 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.