Smack/documentation/extensions/omemo_migration_4.2.0_head.md

Migrating smack-omemo from 4.2.1 to 4.x.x
=========================================

The implementation of smack-omemo and smack-omemo-signal was originally started as an
academic project under pressure of time.
For that reason, the API was not perfect when OMEMO support was first introduced in
Smack in version 4.2.1.
Many issues of smack-omemo have been resolved over the course of the last year in
a major effort, which is why smack-omemo and smack-omemo-signalwere excluded from
the 4.2.2 release.

During this time major parts of the implementation were redone and the API changed
as a consequence of that. This guide will go through all notable changes in order
to make the process of upgrading as easy and straight forward as possible.

## Trust
One major change is, that the OmemoStore implementations no longer store trust decisions.
Methods related to trust have been removed from OmemoStore implementations.
Instead the client is now responsible to store those.
Upon startup, the client now must pass an `OmemoTrustCallback` to the `OmemoManager`
which is used to access and change trust decisions.

It is recommended for the client to store trust decisions as tuples of (omemo device,
fingerprint of identityKey, trust state).
When querying a trust decision (aka. "Is this fingerprint trusted for that device?),
the local fingerprint should be compared to the provided fingerprint.

The method signatures for setting and querying trust from inside the OmemoManager are
still the same. Internally they access the `OmemoTrustCallback` set by the client.

## Encryption
Message encryption in smack-omemo 4.2.1 was ugly. Encryption for multiple devices
could fail because session negotiation could go wrong, which resulted in an
exception, which contained all devices with working sessions.
That exception could then be used in 
`OmemoManager.encryptForExistingSessions(CannotEstablishOmemoSessionException exception, String message)`,
to encrypt the message for all devices with a session.

The new API is
Rework support for XEP-0384: OMEMO Encryption Changes: Rework integration tests New structure of base integration test classes bump dependency on signal-protocol-java from 2.4.0 to 2.6.2 Introduced CachingOmemoStore implementations Use CachingOmemoStore classes in integration tests Removed OmemoSession classes (replaced with more logical OmemoRatchet classes) Consequently also removed load/storeOmemoSession methods from OmemoStore Removed some clutter from KeyUtil classes Moved trust decision related code from OmemoStore to TrustCallback Require authenticated connection for many functions Add async initialization function in OmemoStore Refactor omemo test package (/java/org/jivesoftware/smack/omemo -> /java/org/jivesoftware/smackx) Remove OmemoStore method isFreshInstallation() as well as defaultDeviceId related stuff FileBasedOmemoStore: Add cleaner methods to store/load base data types (Using tryWithResource, only for future releases, once Android API gets bumped) Attempt to make OmemoManager thread safe new logic for getInstanceFor() deviceId determination OmemoManagers encrypt methods now don't throw exceptions when encryption for some devices fails. Instead message gets encrypted when possible and more information about failures gets returned alongside the message itself Added OmemoMessage class for that purpose Reworked entire OmemoService class Use safer logic for creating trust-ignoring messages (like ratchet-update messages) Restructure elements/provider in order to prepare for OMEMO namespace bumps Remove OmemoManager.regenerate() methods in favor of getInstanceFor(connection, randomDeviceId) Removed some unnecessary configuration options Prepare for support of more AES message key types Simplify session creation Where possible, avoid side effects in methods Add UntrustedOmemoIdentityException Add TrustState enum More improved tests 2018-06-13 12:29:16 +02:00			`Migrating smack-omemo from 4.2.1 to 4.x.x`
			`=========================================`

			`The implementation of smack-omemo and smack-omemo-signal was originally started as an`
			`academic project under pressure of time.`
			`For that reason, the API was not perfect when OMEMO support was first introduced in`
			`Smack in version 4.2.1.`
			`Many issues of smack-omemo have been resolved over the course of the last year in`
			`a major effort, which is why smack-omemo and smack-omemo-signalwere excluded from`
			`the 4.2.2 release.`

			`During this time major parts of the implementation were redone and the API changed`
			`as a consequence of that. This guide will go through all notable changes in order`
			`to make the process of upgrading as easy and straight forward as possible.`

			`## Trust`
			`One major change is, that the OmemoStore implementations no longer store trust decisions.`
			`Methods related to trust have been removed from OmemoStore implementations.`
			`Instead the client is now responsible to store those.`
			Upon startup, the client now must pass an `OmemoTrustCallback` to the `OmemoManager`
			`which is used to access and change trust decisions.`

			`It is recommended for the client to store trust decisions as tuples of (omemo device,`
			`fingerprint of identityKey, trust state).`
			`When querying a trust decision (aka. "Is this fingerprint trusted for that device?),`
			`the local fingerprint should be compared to the provided fingerprint.`

			`The method signatures for setting and querying trust from inside the OmemoManager are`
			still the same. Internally they access the `OmemoTrustCallback` set by the client.

			`## Encryption`
			`Message encryption in smack-omemo 4.2.1 was ugly. Encryption for multiple devices`
			`could fail because session negotiation could go wrong, which resulted in an`
			`exception, which contained all devices with working sessions.`
			`That exception could then be used in`
			`OmemoManager.encryptForExistingSessions(CannotEstablishOmemoSessionException exception, String message)`,
			`to encrypt the message for all devices with a session.`

			`The new API is`