Top | ![]() |
![]() |
![]() |
![]() |
void | (*InfXmppConnectionCrtCallback) () |
GQuark | inf_xmpp_connection_error_quark () |
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 () |
gnutls_kx_algorithm_t | inf_xmpp_connection_get_kx_algorithm () |
gnutls_cipher_algorithm_t | inf_xmpp_connection_get_cipher_algorithm () |
gnutls_mac_algorithm_t | inf_xmpp_connection_get_mac_algorithm () |
gnutls_protocol_t | inf_xmpp_connection_get_tls_protocol () |
guint | inf_xmpp_connection_get_dh_prime_bits () |
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 () |
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 |
enum | InfXmppConnectionSite |
enum | InfXmppConnectionSecurityPolicy |
enum | InfXmppConnectionError |
enum | InfXmppConnectionStreamError |
enum | InfXmppConnectionAuthError |
struct | InfXmppConnection |
struct | InfXmppConnectionClass |
GEnum ├── InfXmppConnectionSecurityPolicy ╰── InfXmppConnectionSite GObject ╰── InfXmppConnection
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.
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.
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
|
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.
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]
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 |
[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 |
[allow-none] |
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()
).
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()
.
The certificate of the local host. The returned value should not be freed, it is owned by the InfXmppConnection.
[transfer none]
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()
.
The certificate chain of the remote host. The returned value should not be freed, it is owned by the InfXmppConnection.
[transfer none]
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
const GError *
inf_xmpp_connection_get_sasl_error (InfXmppConnection *xmpp
);
Gets the SASL error of xmpp
. See inf_xmpp_connection_set_sasl_error()
.
Specifies whether the local site of the connection is a client or a server.
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.
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. |
||
In the case of a server, require all connections to be TLS-secured. As a client, only connect if the server supports TLS. |
||
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. |
||
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. |
Specifies the error codes in the
INF_XMPP_CONNECTION_ERROR
error domain.
Server does not support TLS,
but the security policy is set to |
||
The server requires TLS, but the
security policy is set to |
||
Server cannot proceed with the TLS handshake. |
||
The server did not provide a certificate. |
||
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
|
||
The server does not provide any authentication mechanisms. |
||
The server does not offer a suitable authentication mechanism that is accepted by the client. |
||
General error code for otherwise unknown errors. |
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.
The entity has sent XML that cannot be processed. |
||
The entity has sent a namespace prefix that is unsupported, or has sent no namespace prefix on an element that requires such a prefix. |
||
The server is closing the active stream for this entity because a new stream has been initiated that conflicts with the existing stream. |
||
The entity has not generated any traffic over the stream for some period of time. |
||
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. |
||
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. |
||
A stanza sent between two servers lacks a 'to' or 'from' attribute. |
||
The server has experienced a misconfiguration or an otherwise-undefined internal error that prevents it from servicing the stream. |
||
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. |
||
The stream ID or dialback ID is invalid or does not match an ID previously provided. |
||
The streams namespace
is something other than |
||
The entity has sent invalid XML over the stream to a server that performs validation. |
||
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. |
||
The entity has violated some local service policy. |
||
The server is unable to properly connect to a remote entity that is required for authentication or authorization. |
||
The server lacks the system resources necessary to service the stream. |
||
The entity has attempted to send restricted XML features. |
||
The server will not provide service to the initiating entity but is redirecting traffic to another host. |
||
The server is being shut down and all active streams are being closed. |
||
The error condition is not one of those defined by the other conditions. |
||
The initiating entity has encoded the stream in an encoding that is not supported by the server. |
||
The initiating entity has sent a first-level child of the stream that is not supported by the server. |
||
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. |
||
The initiating entity has sent XML that is not well-formed. |
||
General error code for otherwise unknown errors. |
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.
The receiving entity acknowledged
an |
||
The data provided by the initiating entity could not be processed because the Base64 encoding is incorrect. |
||
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. |
||
The initiating entity did not provide a mechanism or requested a mechanism that is not supported by the receiving entity. |
||
The mechanism requested by the initiating entity is weaker than server policy permits for that initiating entity. |
||
The authentication failed because the initiating entity did not provide valid credentials. |
||
The authentication failed because of a temporary error condition within the receiving entity. |
||
General error code for otherwise unknown errors. |
struct InfXmppConnection;
InfXmppConnection is an opaque data type. You should only access it via the public API functions.
“credentials”
property“credentials” InfCertificateCredentials *
The certificate credentials for GnuTLS.
Owner: InfXmppConnection
Flags: Read / Write / Construct
“local-hostname”
property “local-hostname” gchar *
The hostname of the local host.
Owner: InfXmppConnection
Flags: Read / Write / Construct Only
Default value: NULL
“remote-hostname”
property “remote-hostname” gchar *
The hostname of the remote host.
Owner: InfXmppConnection
Flags: Read / Write / Construct Only
Default value: NULL
“sasl-context”
property“sasl-context” InfSaslContext *
The SASL context used for authentication.
Owner: InfXmppConnection
Flags: Read / Write / Construct
“sasl-mechanisms”
property “sasl-mechanisms” gchar *
Whitespace separated list of SASL mechanisms to accept/offer.
Owner: InfXmppConnection
Flags: Read / Write / Construct
Default value: NULL
“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
“site”
property“site” InfXmppConnectionSite
Site of the connection (client or server).
Owner: InfXmppConnection
Flags: Read / Write / Construct Only
Default value: INF_XMPP_CONNECTION_CLIENT
“tcp-connection”
property“tcp-connection” InfTcpConnection *
Underlaying TCP connection.
Owner: InfXmppConnection
Flags: Read / Write / Construct Only