Infinity.XmppConnection¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37), Infinity.XmlConnection (6)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` (tcp, site, local_hostname, remote_hostname, security_policy, creds, sasl_context, sasl_mechanisms)
	`certificate_verify_cancel` (error)
	`certificate_verify_continue` ()
	`get_dh_prime_bits` ()
	`get_own_certificate` ()
	`get_peer_certificate` ()
	`get_sasl_error` ()
	`get_tls_enabled` ()
	`reset_sasl_authentication` (new_context, new_mechanisms)
	`retry_sasl_authentication` ()
	`set_sasl_error` (error)

Virtual Methods¶

Inherited:: GObject.Object (7), Infinity.XmlConnection (6)

Properties¶

Inherited:: Infinity.XmlConnection (6)

Name	Type	Flags	Short Description
`credentials`	`Infinity.CertificateCredentials`	r/w/c	The certificate credentials for GnuTLS
`local-hostname`	`str`	r/w/co	The hostname of the local host
`remote-hostname`	`str`	r/w/co	The hostname of the remote host
`sasl-context`	`Infinity.SaslContext`	r/w/c	The SASL context used for authentication
`sasl-mechanisms`	`str`	r/w/c	Whitespace separated list of SASL mechanisms to accept/offer
`security-policy`	`Infinity.XmppConnectionSecurityPolicy`	r/w/co	How to choose whether to use (or offer, as a server) TLS
`site`	`Infinity.XmppConnectionSite`	r/w/co	Site of the connection (client or server)
`tcp-connection`	`Infinity.TcpConnection`	r/w/co	Underlaying TCP connection
`tls-enabled`	`bool`	r	Whether TLS is enabled for the connection or not

Signals¶

Inherited:: GObject.Object (1), Infinity.XmlConnection (3)

Fields¶

Inherited:: GObject.Object (1), Infinity.XmlConnection (3)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Infinity.XmppConnection(**kwargs)¶

Bases:: GObject.Object, Infinity.XmlConnection
Abstract:: No
Structure:: Infinity.XmppConnectionClass

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

classmethod error_quark()¶

Return type:: int

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

classmethod new(tcp, site, local_hostname, remote_hostname, security_policy, creds, sasl_context, sasl_mechanisms)¶

Parameters:

tcp (Infinity.TcpConnection) – The underlaying TCP connection to use.
site (Infinity.XmppConnectionSite) – Whether this is a XMPP client or server.
local_hostname (str or None) – The hostname of the local host, or None.
remote_hostname (str) – The hostname of the remote host.
security_policy (Infinity.XmppConnectionSecurityPolicy) – Whether to use (or offer, as a server) TLS. See Infinity.XmppConnectionSecurityPolicy for the meaning of this parameter.
creds (Infinity.CertificateCredentials or None) – Certificate credentials used to secure the communication.
sasl_context (Infinity.SaslContext or None) – A SASL context used for authentication.
sasl_mechanisms (str or None) – A whitespace-separated list of SASL mechanisms to accept/offer, or None.

Returns:

A new Infinity.XmppConnection.

Return type:

Infinity.XmppConnection

Creates a new Infinity.XmppConnection 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 Infinity.TcpConnectionStatus.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 None in which case the host name as reported by GLib.get_host_name() is used.

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

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

If sasl_context is not None, 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 None, then this parameter is ignored. sasl_mechanisms can be None in which case all available mechanisms are accepted or offered, respectively.

certificate_verify_cancel(error)¶

Parameters:: error (GLib.Error) – Reason why the certificate is not trusted, or None.

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-None, 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 Infinity.gnutls_certificate_verification_set_error(). The reason is then shown to the local user.

certificate_verify_continue()¶: 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.

get_dh_prime_bits()¶

Returns:: The number of Diffie-Hellman prime bits.
Return type:: int

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 Infinity.XmppConnection.get_tls_enabled() returns true.

get_own_certificate()¶

Returns:: The certificate of the local host. The returned value should not be freed, it is owned by the Infinity.XmppConnection.
Return type:: InfGnutls.X509Crt

Returns the local host’s certificate that was used to authenticate with the remote host, or None if no certificate was used. This function can only be used after the TLS handshake has completed, see Infinity.XmppConnection.get_tls_enabled().

get_peer_certificate()¶

Returns:: The certificate chain of the remote host. The returned value should not be freed, it is owned by the Infinity.XmppConnection.
Return type:: Infinity.CertificateChain

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

get_sasl_error()¶

Returns:: A pointer to a GLib.Error object owned by self.
Return type:: GLib.Error

Gets the SASL error of self. See Infinity.XmppConnection.set_sasl_error().

get_tls_enabled()¶

Returns:: True if TLS is enabled and False otherwise.
Return type:: bool

Returns whether TLS encryption is enabled for self. 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()).

reset_sasl_authentication(new_context, new_mechanisms)¶

Parameters:

new_context (Infinity.SaslContext or None) – The new sasl context to set, or None.
new_mechanisms (str or None) – Allowed SASL mechanisms to use. Ignored if new_context is None.

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 None, 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 Infinity.XmppConnectionAuthError.TEMPORARY_AUTH_FAILURE error to the client with Infinity.AuthenticationDetailError.TRY_AGAIN detail (see Infinity.XmppConnection.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 Infinity.XmppConnectionAuthError.ABORTED error. In the signal handler of the Infinity.XmlConnection ::error signal you should reinitiate the authentication with Infinity.XmppConnection.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.

retry_sasl_authentication()¶

Raises:: GLib.Error
Returns:: True if auth retry is being performed, False otherwise.
Return type:: bool

When SASL authentication failed then the Infinity.XmlConnection ::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 Infinity.XmppConnection :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 Infinity.XmppConnection :sasl-mechanisms. If so, the function returns False and error is set.

set_sasl_error(error)¶

Parameters:: error (GLib.Error) – The SASL error to set.

Sets the SASL error of self. 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 Infinity.XmlConnection ::error is emitted with an error from the INF_XMPP_CONNECTION_AUTH_ERROR domain then Infinity.XmppConnection.get_sasl_error() can be used to obtain more detailed error information.

Property Details¶

Infinity.XmppConnection.props.credentials¶

Name:: credentials
Type:: Infinity.CertificateCredentials
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT

The certificate credentials for GnuTLS

Infinity.XmppConnection.props.local_hostname¶

Name:: local-hostname
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The hostname of the local host

Infinity.XmppConnection.props.remote_hostname¶

Name:: remote-hostname
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The hostname of the remote host

Infinity.XmppConnection.props.sasl_context¶

Name:: sasl-context
Type:: Infinity.SaslContext
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT

The SASL context used for authentication

Infinity.XmppConnection.props.sasl_mechanisms¶

Name:: sasl-mechanisms
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT

Whitespace separated list of SASL mechanisms to accept/offer

Infinity.XmppConnection.props.security_policy¶

Name:: security-policy
Type:: Infinity.XmppConnectionSecurityPolicy
Default Value:: Infinity.XmppConnectionSecurityPolicy.BOTH_PREFER_TLS
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

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

Infinity.XmppConnection.props.site¶

Name:: site
Type:: Infinity.XmppConnectionSite
Default Value:: Infinity.XmppConnectionSite.CLIENT
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Site of the connection (client or server)

Infinity.XmppConnection.props.tcp_connection¶

Name:: tcp-connection
Type:: Infinity.TcpConnection
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Underlaying TCP connection

Infinity.XmppConnection.props.tls_enabled¶

Name:: tls-enabled
Type:: bool
Default Value:: False
Flags:: READABLE

Whether TLS is enabled for the connection or not