QXmpp Version: 1.5.6
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Friends | List of all members
QXmppOmemoManager Class Reference
Inheritance diagram for QXmppOmemoManager:
Inheritance graph
[legend]
Collaboration diagram for QXmppOmemoManager:
Collaboration graph
[legend]

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< ResultremoveContactDevices (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< bool > resetAll ()
 
QXmppTask< void > setSecurityPolicy (QXmpp::TrustSecurityPolicy securityPolicy)
 
QXmppTask< QXmpp::TrustSecurityPolicysecurityPolicy ()
 
QXmppTask< void > setTrustLevel (const QMultiHash< QString, QByteArray > &keyIds, QXmpp::TrustLevel trustLevel)
 
QXmppTask< QXmpp::TrustLeveltrustLevel (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::IdentitydiscoveryIdentities () const
 
virtual bool handleStanza (const QDomElement &stanza)
 You need to implement this method to process incoming XMPP stanzas.
 
virtual bool handleStanza (const QDomElement &stanza, const std::optional< QXmppE2eeMetadata > &e2eeMetadata)
 You need to implement this method to process incoming XMPP stanzas.
 
- Public Member Functions inherited from QXmppLoggable
 QXmppLoggable (QObject *parent=nullptr)
 
- Public Member Functions inherited from QXmppE2eeExtension
virtual QXmppTask< MessageEncryptResultencryptMessage (QXmppMessage &&, const std::optional< QXmppSendStanzaParams > &)=0
 
virtual QXmppTask< MessageDecryptResultdecryptMessage (QXmppMessage &&)=0
 
virtual QXmppTask< IqEncryptResultencryptIq (QXmppIq &&, const std::optional< QXmppSendStanzaParams > &)=0
 
virtual QXmppTask< IqDecryptResultdecryptIq (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
QXmppClientclient ()
 
virtual void setClient (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:

client->addExtension(pubSubManager);
QXmppClient * client()
Definition QXmppClientExtension.cpp:78
bool addExtension(QXmppClientExtension *extension)
Definition QXmppClient.cpp:263
The QXmppPubSubManager aims to provide publish-subscribe functionality as specified in XEP-0060: Publ...
Definition QXmppPubSubManager.h:21

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:

The QXmppOmemoMemoryStorage class stores data used by XEP-0384: OMEMO Encryption in the memory.
Definition QXmppOmemoMemoryStorage.h:17
The QXmppOmemoStorage class stores data used by XEP-0384: OMEMO Encryption.
Definition QXmppOmemoStorage.h:17
The QXmppTrustMemoryStorage class stores trust data for end-to-end encryption in the memory.
Definition QXmppTrustMemoryStorage.h:15
The QXmppTrustStorage class stores end-to-end encryption trust data.
Definition QXmppTrustStorage.h:16

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

The QXmppAtmManager class represents a manager for XEP-0450: Automatic Trust Management (ATM).
Definition QXmppAtmManager.h:18
T * addNewExtension(Args... args)
Definition QXmppClient.h:129

Afterwards, the OMEMO manager using its storage must be added to the client:

auto *manager = client->addNewExtension<QXmppOmemoManager>(omemoStorage);
Definition QXmppOmemoManager.h:69

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);
@ Toakafa
Definition QXmppTrustSecurityPolicy.h:23

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

The QXmppCarbonManagerV2 class handles message carbons as described in XEP-0280: Message Carbons.
Definition QXmppCarbonManagerV2.h:11

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();
});
void connected()

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:

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

client->send(stanza, params);
QXmppTask< QXmpp::SendResult > send(QXmppStanza &&, const std::optional< QXmppSendStanzaParams > &={})
Definition QXmppClient.cpp:468
Definition QXmppSendStanzaParams.h:18
void setAcceptedTrustLevels(std::optional< QXmpp::TrustLevels > trustLevels)
Definition QXmppSendStanzaParams.cpp:85

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

params.setEncryptionJids({ "alice@example.org", "bob@example.com" })
client->send(stanza, params);
void setEncryptionJids(QVector< QString >)
Definition QXmppSendStanzaParams.cpp:58
Warning
THIS API IS NOT FINALIZED YET!
Since
QXmpp 1.5

Member Typedef Documentation

◆ 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
omemoStoragestorage 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
jidsJIDs 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
deviceLabelown 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
jiddevice owner's bare JID
deviceIdID of the device

◆ deviceChanged()

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

Emitted when a device changed.

Parameters
jiddevice owner's bare JID
deviceIdID of the device

◆ deviceRemoved()

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

Emitted when a device is removed.

Parameters
jiddevice owner's bare JID
deviceIdID 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
jidsJIDs 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
jiddevice 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.

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
jidskey owners' bare JIDs
trustLevelstrust levels of the keys
Returns
the key IDs mapped to their trust levels for specific key owners

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

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
trustLevelstrust levels of the keys
Returns
the key owner JIDs mapped to their keys with specific trust levels

◆ 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
jidJID 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
jidsJIDs 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.

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

◆ 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
trustLevelstrust 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
maximummaximum 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
maximummaximum 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
isNewDeviceAutoSessionBuildingEnabledwhether sessions are built for incoming devices

◆ setSecurityPolicy()

QXmppTask< void > Manager::setSecurityPolicy ( QXmpp::TrustSecurityPolicy  securityPolicy)

Sets the security policy used by this E2EE extension.

Parameters
securityPolicysecurity 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
keyIdskey owners' bare JIDs mapped to the IDs of their keys
trustLeveltrust 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
jidsJIDs 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
keyOwnerJidkey owner's bare JID
keyIdID 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
modifiedKeyskey 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: