QXmppOmemoManager Class Reference

Inheritance diagram for QXmppOmemoManager:

Collaboration diagram for QXmppOmemoManager:

Public Types
using	Result = std::variant< QXmpp::Success, QXmppError >
Public Types inherited from QXmppE2eeExtension
using	MessageEncryptResult = std::variant< std::unique_ptr< QXmppMessage >, QXmppError >
using	MessageDecryptResult = std::variant< QXmppMessage, NotEncrypted, QXmppError >
using	IqEncryptResult = std::variant< std::unique_ptr< QXmppIq >, QXmppError >
using	IqDecryptResult = std::variant< QDomElement, NotEncrypted, QXmppError >

Public Member Functions
	QXmppOmemoManager (QXmppOmemoStorage *omemoStorage)
QXmppTask< bool >	load ()
QXmppTask< bool >	setUp ()
QXmppTask< QByteArray >	ownKey ()
QXmppTask< QHash< QXmpp::TrustLevel, QMultiHash< QString, QByteArray > > >	keys (QXmpp::TrustLevels trustLevels={})
QXmppTask< QHash< QString, QHash< QByteArray, QXmpp::TrustLevel > > >	keys (const QList< QString > &jids, QXmpp::TrustLevels trustLevels={})
QXmppTask< bool >	changeDeviceLabel (const QString &deviceLabel={})
int	maximumDevicesPerJid () const
void	setMaximumDevicesPerJid (int maximum)
int	maximumDevicesPerStanza () const
void	setMaximumDevicesPerStanza (int maximum)
QXmppTask< QVector< DevicesResult > >	requestDeviceLists (const QList< QString > &jids)
QXmppTask< QVector< DevicesResult > >	subscribeToDeviceLists (const QList< QString > &jids)
QXmppTask< QVector< DevicesResult > >	unsubscribeFromDeviceLists ()
QXmppOmemoOwnDevice	ownDevice ()
QXmppTask< QVector< QXmppOmemoDevice > >	devices ()
QXmppTask< QVector< QXmppOmemoDevice > >	devices (const QList< QString > &jids)
QXmppTask< Result >	removeContactDevices (const QString &jid)
void	setAcceptedSessionBuildingTrustLevels (QXmpp::TrustLevels trustLevels)
QXmpp::TrustLevels	acceptedSessionBuildingTrustLevels ()
void	setNewDeviceAutoSessionBuildingEnabled (bool isNewDeviceAutoSessionBuildingEnabled)
bool	isNewDeviceAutoSessionBuildingEnabled ()
QXmppTask< void >	buildMissingSessions (const QList< QString > &jids)
QXmppTask< bool >	resetOwnDevice ()
QXmppTask< void >	resetOwnDeviceLocally ()
QXmppTask< bool >	resetAll ()
QXmppTask< void >	setSecurityPolicy (QXmpp::TrustSecurityPolicy securityPolicy)
QXmppTask< QXmpp::TrustSecurityPolicy >	securityPolicy ()
QXmppTask< void >	setTrustLevel (const QMultiHash< QString, QByteArray > &keyIds, QXmpp::TrustLevel trustLevel)
QXmppTask< QXmpp::TrustLevel >	trustLevel (const QString &keyOwnerJid, const QByteArray &keyId)
Q_SIGNAL void	trustLevelsChanged (const QMultiHash< QString, QByteArray > &modifiedKeys)
Q_SIGNAL void	deviceAdded (const QString &jid, uint32_t deviceId)
Q_SIGNAL void	deviceChanged (const QString &jid, uint32_t deviceId)
Q_SIGNAL void	deviceRemoved (const QString &jid, uint32_t deviceId)
Q_SIGNAL void	devicesRemoved (const QString &jid)
Q_SIGNAL void	allDevicesRemoved ()
Public Member Functions inherited from QXmppClientExtension
	QXmppClientExtension ()
virtual QStringList	discoveryFeatures () const
virtual QList< QXmppDiscoveryIq::Identity >	discoveryIdentities () const
virtual bool	handleStanza (const QDomElement &stanza)
	You need to implement this method to process incoming XMPP stanzas. More...
virtual bool	handleStanza (const QDomElement &stanza, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
	You need to implement this method to process incoming XMPP stanzas. More...
Public Member Functions inherited from QXmppLoggable
	QXmppLoggable (QObject *parent=nullptr)
Public Member Functions inherited from QXmppE2eeExtension
virtual QXmppTask< MessageEncryptResult >	encryptMessage (QXmppMessage &&, const std::optional< QXmppSendStanzaParams > &)=0
virtual QXmppTask< MessageDecryptResult >	decryptMessage (QXmppMessage &&)=0
virtual QXmppTask< IqEncryptResult >	encryptIq (QXmppIq &&, const std::optional< QXmppSendStanzaParams > &)=0
virtual QXmppTask< IqDecryptResult >	decryptIq (const QDomElement &)=0
virtual bool	isEncrypted (const QDomElement &)=0
virtual bool	isEncrypted (const QXmppMessage &)=0
Public Member Functions inherited from QXmppPubSubEventHandler
virtual bool	handlePubSubEvent (const QDomElement &element, const QString &pubSubService, const QString &nodeName)=0
Public Member Functions inherited from QXmppMessageHandler
virtual bool	handleMessage (const QXmppMessage &)=0

Friends
class	QXmppOmemoManagerPrivate
class	tst_QXmppOmemoManager

Additional Inherited Members
Signals inherited from QXmppLoggable
void	setGauge (const QString &gauge, double value)
	Sets the given gauge to value.
void	logMessage (QXmppLogger::MessageType type, const QString &msg)
	This signal is emitted to send logging messages.
void	updateCounter (const QString &counter, qint64 amount=1)
	Updates the given counter by amount.
Protected Member Functions inherited from QXmppClientExtension
QXmppClient *	client () const
virtual void	setClient (QXmppClient *client)
virtual void	onRegistered (QXmppClient *client)
virtual void	onUnregistered (QXmppClient *client)
void	injectIq (const QDomElement &element, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
bool	injectMessage (QXmppMessage &&message)
Protected Member Functions inherited from QXmppLoggable
void	debug (const QString &message)
void	info (const QString &message)
void	warning (const QString &message)
void	logReceived (const QString &message)
void	logSent (const QString &message)

Detailed Description

The QXmppOmemoManager class manages OMEMO encryption as defined in XEP-0384: OMEMO Encryption.

OMEMO uses XEP-0060: Publish-Subscribe (PubSub) and XEP-0163: Personal Eventing Protocol (PEP). Thus, they must be supported by the server and the corresponding PubSub manager must be added to the client:

QXmppPubSubManager *pubSubManager = new QXmppPubSubManager;
client->addExtension(pubSubManager);

For interacting with the storage, corresponding implementations of the storage interfaces must be instantiated. Those implementations have to be adapted to your storage such as a database. In case you only need memory and no persistent storage, you can use the existing implementations:

QXmppOmemoStorage *omemoStorage = new QXmppOmemoMemoryStorage;
QXmppTrustStorage *trustStorage = new QXmppTrustMemoryStorage;

A trust manager using its storage must be added to the client:

client->addNewExtension<QXmppAtmManager>(trustStorage);

Afterwards, the OMEMO manager using its storage must be added to the client and activated to be used for encryption:

auto *manager = client->addNewExtension<QXmppOmemoManager>(omemoStorage);
client->setEncryptionExtension(manager);

You can set a security policy used by OMEMO. Is is recommended to apply TOAKAFA for good security and usability when using XEP-0450: Automatic Trust Management (ATM):

manager->setSecurityPolicy(QXmpp::Toakafa);

XEP-0280: Message Carbons should be used for delivering messages to all endpoints of a user:

client->addNewExtension<QXmppCarbonManagerV2>();

The old QXmppCarbonManager cannot be used with OMEMO.

The OMEMO data must be loaded before connecting to the server:

    manager->load();
});

If no OMEMO data could be loaded (i.e., the result of load() is "false"), it must be set up first. That can be done as soon as the user is logged in to the server:

connect(client, &QXmppClient::connected, this, [=]() {
    auto future = manager->start();
});

Once the future is finished and the result is "true", the manager is ready for use. Otherwise, check the logging output for details.

By default, stanzas are only sent to devices having keys with the following trust levels:

QXmpp::TrustLevel::AutomaticallyTrusted | QXmpp::TrustLevel::ManuallyTrusted
| QXmpp::TrustLevel::Authenticated

That behavior can be changed for each message being sent by specifying the accepted trust levels:

QXmppSendStanzaParams params;
params.setAcceptedTrustLevels(QXmpp::TrustLevel::Authenticated)
client->send(stanza, params);

Stanzas can be encrypted for multiple JIDs which is needed in group chats:

QXmppSendStanzaParams params;
params.setEncryptionJids({ "alice@example.org", "bob@example.com" })
client->send(stanza, params);

Warning

THIS API IS NOT FINALIZED YET!

Since

QXmpp 1.5

Member Typedef Documentation

Result

QXmppOmemoManager::Result

Contains QXmpp::Success for success or an QXmppStanza::Error for an error.

Constructor & Destructor Documentation

QXmppOmemoManager()

QXmppOmemoManager::QXmppOmemoManager ( QXmppOmemoStorage *  omemoStorage )

explicit

Constructs an OMEMO manager.

Parameters

omemoStorage

storage used to store all OMEMO data

Member Function Documentation

acceptedSessionBuildingTrustLevels()

TrustLevels Manager::acceptedSessionBuildingTrustLevels

(

)

Returns the trust levels keys must have in order to build sessions for their devices.

Returns

the trust levels of the keys used for building sessions

allDevicesRemoved()

QXmppOmemoManager::allDevicesRemoved

(

)

Emitted when all devices are removed.

buildMissingSessions()

QXmppTask< void > Manager::buildMissingSessions

(

const QList< QString > &

jids

)

Builds sessions manually with devices for whom no sessions are available.

Usually, sessions are built during sending a first message to a device or after a first message is received from a device. This can be called in order to speed up the sending of a message. If this method is called before sending the first message, all sessions can be built and when the first message is being sent, the message only needs to be encrypted. Especially for chats with multiple devices, that can decrease the noticeable time a user has to wait for sending a message. Additionally, the keys are automatically retrieved from the server which is helpful in order to get them when calling QXmppOmemoManager::devices().

The user must be logged in while calling this.

Parameters

jids	JIDs of the device owners for whom the sessions are built

changeDeviceLabel()

QXmppTask< bool > Manager::changeDeviceLabel

(

const QString &

deviceLabel = {}

)

Changes the label of the own (this client instance's current user's) device.

The label is a human-readable string used to identify the device by users.

If the OMEMO manager is not started yet, the device label is only changed locally in memory. It is stored persistently in the OMEMO storage and updated on the server if the OMEMO manager is already started or once it is.

Parameters

deviceLabel

own device's label

Returns

whether the action was successful

deviceAdded()

QXmppOmemoManager::deviceAdded	(	const QString &	jid,
		uint32_t	deviceId
	)

Emitted when a device is added.

Parameters

jid	device owner's bare JID
deviceId	ID of the device

deviceChanged()

QXmppOmemoManager::deviceChanged	(	const QString &	jid,
		uint32_t	deviceId
	)

Emitted when a device changed.

Parameters

jid	device owner's bare JID
deviceId	ID of the device

deviceRemoved()

QXmppOmemoManager::deviceRemoved	(	const QString &	jid,
		uint32_t	deviceId
	)

Emitted when a device is removed.

Parameters

jid	device owner's bare JID
deviceId	ID of the device

devices() [1/2]

QXmppTask< QVector< QXmppOmemoDevice > > Manager::devices

(

)

Returns all locally stored devices except the own device.

Only devices that have been received after subscribing the corresponding device lists on the server are stored locally. Thus, only those are returned. Call QXmppOmemoManager::subscribeToDeviceLists() for contacts without presence subscription before.

You must build sessions before you can get devices with corresponding keys.

Returns

all devices except the own device

devices() [2/2]

QXmppTask< QVector< QXmppOmemoDevice > > Manager::devices

(

const QList< QString > &

jids

)

Returns locally stored devices except the own device.

Only devices that have been received after subscribing the corresponding device lists on the server are stored locally. Thus, only those are returned. Call QXmppOmemoManager::subscribeToDeviceLists() for contacts without presence subscription before.

You must build sessions before you can get devices with corresponding keys.

Parameters

jids	JIDs whose devices are being retrieved

Returns

all devices of the passed JIDs

devicesRemoved()

QXmppOmemoManager::devicesRemoved

(

const QString &

jid

)

Emitted when all devices of an owner are removed.

Parameters

jid	device owner's bare JID

isNewDeviceAutoSessionBuildingEnabled()

bool Manager::isNewDeviceAutoSessionBuildingEnabled

(

)

Returns whether sessions are built when new devices are received from the server.

See also

QXmppOmemoManager::setNewDeviceAutoSessionBuildingEnabled

Returns

whether sessions are built for incoming devices

keys() [1/2]

QXmppTask< QHash< QString, QHash< QByteArray, QXmpp::TrustLevel > > > Manager::keys	(	const QList< QString > &	jids,
		QXmpp::TrustLevels	trustLevels = {}
	)

Returns the IDs of keys mapped to their trust levels for specific key owners except for the own key.

If no trust levels are passed, all keys for jids are returned.

This should be called in order to get the stored keys which can be more than the stored devices because of trust decisions made without a published or received device.

Parameters

jids	key owners' bare JIDs
trustLevels	trust levels of the keys

Returns

the key IDs mapped to their trust levels for specific key owners except for the own key

keys() [2/2]

QXmppTask< QHash< QXmpp::TrustLevel, QMultiHash< QString, QByteArray > > > Manager::keys

(

QXmpp::TrustLevels

trustLevels = {}

)

Returns the JIDs of all key owners mapped to the IDs of their keys with specific trust levels except for the own key.

If no trust levels are passed, all keys are returned.

This should be called in order to get all stored keys which can be more than the stored devices because of trust decisions made without a published or received device.

Parameters

trustLevels

trust levels of the keys

Returns

the key owner JIDs mapped to their keys with specific trust levels except for the own key

load()

QXmppTask< bool > Manager::load

(

)

Loads all locally stored OMEMO data.

This should be called after starting the client and before the login. It must only be called after setUp() has been called once for the user during one of the past login sessions. It does not need to be called if setUp() has been called during the current login session.

See also

QXmppOmemoManager::setUp()

Returns

whether everything is loaded successfully

maximumDevicesPerJid()

int Manager::maximumDevicesPerJid

(

)

const

Returns the maximum count of devices stored per JID.

If more devices than that maximum are received for one JID from a server, they will not be stored locally and thus not used for encryption.

Returns

the maximum count of devices stored per JID

maximumDevicesPerStanza()

int Manager::maximumDevicesPerStanza

(

)

const

Returns the maximum count of devices for whom a stanza is encrypted.

If more devices than that maximum are stored for all addressed recipients of a stanza, the stanza will only be encrypted for first devices until the maximum is reached.

Returns

the maximum count of devices for whom a stanza is encrypted

ownDevice()

QXmppOmemoOwnDevice Manager::ownDevice

(

)

Returns the device of this client instance's current user.

Returns

the own device

ownKey()

QXmppTask< QByteArray > Manager::ownKey

(

)

Returns the key of this client instance.

Returns

the own key

removeContactDevices()

QXmppTask< QXmppPubSubManager::Result > Manager::removeContactDevices

(

const QString &

jid

)

Removes all devices of a contact and the subscription to the contact's device list.

This should be called after removing a contact. The JID of the current user must not be passed. Use QXmppOmemoManager::resetAll() in order to remove all devices of the user.

Parameters

jid	JID of the contact whose devices are being removed

Returns

the result of the contact device removals

requestDeviceLists()

QXmppTask< QVector< Manager::DevicesResult > > Manager::requestDeviceLists

(

const QList< QString > &

jids

)

Requests device lists from contacts and stores them locally.

The user must be logged in while calling this. The JID of the current user must not be passed.

Parameters

jids	JIDs of the contacts whose device lists are being requested

Returns

the results of the requests for each JID

resetAll()

QXmppTask< bool > Manager::resetAll

(

)

Resets all OMEMO data for all own devices and the trust data used by OMEMO.

ATTENTION: This should only be called if there is a certain reason for it since it deletes the data for this device and for other own devices from the server.

Call resetOwnDevice() if you only want to delete the OMEMO data for this device.

The user must be logged in while calling this.

Call setUp() once this method is finished if you want to set up everything again. Existing sessions are reset, which might lead to undecryptable incoming stanzas until everything is set up again.

Returns

whether the action was successful

resetOwnDevice()

QXmppTask< bool > Manager::resetOwnDevice

(

)

Resets all OMEMO data for this device and the trust data used by OMEMO.

ATTENTION: This should only be called when an account is removed locally or if there are unrecoverable problems with the OMEMO setup of this device.

The data on the server for other own devices is not removed. Call resetAll() for that purpose.

The user must be logged in while calling this.

Call setUp() once this method is finished if you want to set up everything again for this device. Existing sessions are reset, which might lead to undecryptable incoming stanzas until everything is set up again.

Returns

whether the action was successful

resetOwnDeviceLocally()

QXmppTask< void > QXmppOmemoManager::resetOwnDeviceLocally

(

)

Resets all local OMEMO data for this device and the trust data used by OMEMO.

ATTENTION: This should only be called after an account is removed from the server since the data on the server is not reset.

Call setUp() once this method is finished and you are logged in to a new account if you want to set up everything for it.

Since

QXmpp 1.9

securityPolicy()

QXmppTask< QXmpp::TrustSecurityPolicy > Manager::securityPolicy

(

)

Returns the security policy used by this E2EE extension.

Returns

the used security policy

setAcceptedSessionBuildingTrustLevels()

void Manager::setAcceptedSessionBuildingTrustLevels

(

QXmpp::TrustLevels

trustLevels

)

Sets the trust levels keys must have in order to build sessions for their devices.

Parameters

trustLevels

trust levels of the keys used for building sessions

setMaximumDevicesPerJid()

void Manager::setMaximumDevicesPerJid

(

int

maximum

)

Sets the maximum count of devices stored per JID.

If more devices than that maximum are received for one JID from a server, they will not be stored locally and thus not used for encryption.

Parameters

maximum

maximum count of devices stored per JID

setMaximumDevicesPerStanza()

void Manager::setMaximumDevicesPerStanza

(

int

maximum

)

Sets the maximum count of devices for whom a stanza is encrypted.

If more devices than that maximum are stored for all addressed recipients of a stanza, the stanza will only be encrypted for first devices until the maximum is reached.

Parameters

maximum

maximum count of devices for whom a stanza is encrypted

setNewDeviceAutoSessionBuildingEnabled()

void Manager::setNewDeviceAutoSessionBuildingEnabled

(

bool

isNewDeviceAutoSessionBuildingEnabled

)

Sets whether sessions are built when new devices are received from the server.

This can be used to not call QXmppOmemoManager::buildMissingSessions manually. But it should not be used before the initial setup and storing lots of devices locally. Otherwise, it could lead to a massive computation and network load when there are many devices for whom sessions are built.

See also

QXmppOmemoManager::buildMissingSessions

Parameters

isNewDeviceAutoSessionBuildingEnabled

whether sessions are built for incoming devices

setSecurityPolicy()

QXmppTask< void > Manager::setSecurityPolicy

(

QXmpp::TrustSecurityPolicy

securityPolicy

)

Sets the security policy used by this E2EE extension.

Parameters

securityPolicy

security policy being set

setTrustLevel()

QXmppTask< void > Manager::setTrustLevel	(	const QMultiHash< QString, QByteArray > &	keyIds,
		QXmpp::TrustLevel	trustLevel
	)

Sets the trust level of keys.

If a key is not stored, it is added to the storage.

Parameters

keyIds	key owners' bare JIDs mapped to the IDs of their keys
trustLevel	trust level being set

setUp()

QXmppTask< bool > Manager::setUp

(

)

Sets up all OMEMO data locally and on the server.

The user must be logged in while calling this.

Returns

whether everything is set up successfully

subscribeToDeviceLists()

QXmppTask< QVector< Manager::DevicesResult > > Manager::subscribeToDeviceLists

(

const QList< QString > &

jids

)

Subscribes the current user's resource to device lists manually.

This should be called after each login and only for contacts without presence subscription because their device lists are not automatically subscribed. The user must be logged in while calling this.

Call QXmppOmemoManager::unsubscribeFromDeviceLists() before logout.

Parameters

jids	JIDs of the contacts whose device lists are being subscribed

Returns

the results of the subscription for each JID

trustLevel()

QXmppTask< QXmpp::TrustLevel > Manager::trustLevel	(	const QString &	keyOwnerJid,
		const QByteArray &	keyId
	)

Returns the trust level of a key.

If the key is not stored, the trust in that key is undecided.

Parameters

keyOwnerJid	key owner's bare JID
keyId	ID of the key

Returns

the key's trust level

trustLevelsChanged()

QXmppOmemoManager::trustLevelsChanged

(

const QMultiHash< QString, QByteArray > &

modifiedKeys

)

Emitted when the trust levels of keys changed.

Parameters

modifiedKeys

key owners' bare JIDs mapped to their modified keys

unsubscribeFromDeviceLists()

QXmppTask< QVector< Manager::DevicesResult > > Manager::unsubscribeFromDeviceLists

(

)

Unsubscribes the current user's resource from all device lists that were manually subscribed by QXmppOmemoManager::subscribeToDeviceList().

This should be called before each logout. The user must be logged in while calling this.

Returns

the results of the unsubscription for each JID

---

The documentation for this class was generated from the following files:

• QXmppOmemoManager.h
• QXmppOmemoManager.cpp