org.jivesoftware.smackx.omemo

Class OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>

java.lang.Object

org.jivesoftware.smackx.omemo.OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>

Type Parameters:

T_IdKeyPair - IdentityKeyPair class

T_IdKey - IdentityKey class

T_PreKey - PreKey class

T_SigPreKey - SignedPreKey class

T_Sess - Session class

T_Addr - Address class

T_ECPub - Elliptic Curve PublicKey class

T_Bundle - Bundle class

T_Ciph - Cipher class

Direct Known Subclasses:

FileBasedOmemoStore, SignalOmemoStore

public abstract class OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>
extends Object

Class that presents some methods that are used to load/generate/store keys and session data needed for OMEMO.

Constructor Summary

Constructors

Constructor and Description
OmemoStore() Create a new OmemoStore.

Method Summary

Modifier and Type	Method and Description
abstract boolean	containsRawSession(OmemoManager omemoManager, OmemoDevice device) Return true, if we have a session with the device, otherwise false.
abstract void	distrustOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, OmemoFingerprint fingerprint)
void	distrustOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, T_IdKey identityKey) Distrust an OmemoIdentity.
T_IdKeyPair	generateOmemoIdentityKeyPair() Generate a new IdentityKeyPair.
HashMap<Integer,T_PreKey>	generateOmemoPreKeys(int startId, int count) Generate 'count' new PreKeys beginning with id 'startId'.
T_SigPreKey	generateOmemoSignedPreKey(T_IdKeyPair identityKeyPair, int signedPreKeyId) Generate a new signed preKey.
abstract Date	getDateOfLastReceivedMessage(OmemoManager omemoManager, OmemoDevice from) Return the date in millis of the last message that was received from device 'from'.
abstract Date	getDateOfLastSignedPreKeyRenewal(OmemoManager omemoManager) Get the date in millis of the last time the signed preKey was renewed.
abstract int	getDefaultDeviceId(BareJid user) Return the default deviceId for a user.
OmemoFingerprint	getFingerprint(OmemoManager omemoManager) Return our identityKeys fingerprint.
OmemoFingerprint	getFingerprint(OmemoManager omemoManager, OmemoDevice device) Return the fingerprint of the given devices announced identityKey.
OmemoSession<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>	getOmemoSessionOf(OmemoManager omemoManager, OmemoDevice device) Return the OmemoSession for the OmemoDevice.
abstract boolean	isDecidedOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, OmemoFingerprint fingerprint)
boolean	isDecidedOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, T_IdKey identityKey) Did the user yet made a decision about whether to trust or distrust this device?
abstract boolean	isFreshInstallation(OmemoManager omemoManager) Return true if this is a fresh installation.
abstract boolean	isTrustedOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, OmemoFingerprint fingerprint)
boolean	isTrustedOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, T_IdKey identityKey) Decide, whether a identityKey of a device is trusted or not.
abstract OmemoKeyUtil<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>	keyUtil() Return a concrete KeyUtil object that we can use as a utility to create keys etc.
abstract HashMap<Integer,T_Sess>	loadAllRawSessionsOf(OmemoManager omemoManager, BareJid contact) Load all crypto-lib specific session objects of contact 'contact'.
abstract CachedDeviceList	loadCachedDeviceList(OmemoManager omemoManager, BareJid contact) Load a list of deviceIds from contact 'contact' from the local cache.
abstract int	loadCurrentSignedPreKeyId(OmemoManager omemoManager) Return the id of the currently used signed preKey.
abstract int	loadLastPreKeyId(OmemoManager omemoManager) Return the id of the last generated preKey.
abstract T_IdKey	loadOmemoIdentityKey(OmemoManager omemoManager, OmemoDevice device) Load the public identityKey of the device.
abstract T_IdKeyPair	loadOmemoIdentityKeyPair(OmemoManager omemoManager) Load our identityKeyPair from storage.
abstract T_PreKey	loadOmemoPreKey(OmemoManager omemoManager, int preKeyId) Load the preKey with id 'preKeyId' from storage.
abstract HashMap<Integer,T_PreKey>	loadOmemoPreKeys(OmemoManager omemoManager) Return all our current OmemoPreKeys.
abstract T_SigPreKey	loadOmemoSignedPreKey(OmemoManager omemoManager, int signedPreKeyId) Return the signedPreKey with the id 'singedPreKeyId'.
abstract HashMap<Integer,T_SigPreKey>	loadOmemoSignedPreKeys(OmemoManager omemoManager) Load all our signed PreKeys.
abstract T_Sess	loadRawSession(OmemoManager omemoManager, OmemoDevice device) Load the crypto-lib specific session object of the device from storage.
abstract void	purgeOwnDeviceKeys(OmemoManager omemoManager) Delete this device's IdentityKey, PreKeys, SignedPreKeys and Sessions.
abstract void	removeAllRawSessionsOf(OmemoManager omemoManager, BareJid contact) Remove all crypto-lib specific session of a contact.
abstract void	removeOmemoPreKey(OmemoManager omemoManager, int preKeyId) remove a preKey from storage.
abstract void	removeOmemoSignedPreKey(OmemoManager omemoManager, int signedPreKeyId) Remove a signedPreKey from storage.
abstract void	removeRawSession(OmemoManager omemoManager, OmemoDevice device) Remove a crypto-lib specific session from storage.
void	setDateOfLastReceivedMessage(OmemoManager omemoManager, OmemoDevice from) Set the date in millis of the last message that was received from device 'from' to now.
abstract void	setDateOfLastReceivedMessage(OmemoManager omemoManager, OmemoDevice from, Date date) Set the date in millis of the last message that was received from device 'from' to 'date'.
void	setDateOfLastSignedPreKeyRenewal(OmemoManager omemoManager) Store the date of the last preKey renewal in the omemoStore.
abstract void	setDateOfLastSignedPreKeyRenewal(OmemoManager omemoManager, Date date) Set the date in millis of the last time the signed preKey was renewed.
abstract void	setDefaultDeviceId(BareJid user, int defaultDeviceId) Set the default deviceId of a user.
abstract void	storeCachedDeviceList(OmemoManager omemoManager, BareJid contact, CachedDeviceList deviceList) Store the DeviceList of the contact in local storage.
abstract void	storeCurrentSignedPreKeyId(OmemoManager omemoManager, int currentSignedPreKeyId) Store the id of the currently used signedPreKey.
abstract void	storeLastPreKeyId(OmemoManager omemoManager, int currentPreKeyId) Store the id of the last preKey we generated.
abstract void	storeOmemoIdentityKey(OmemoManager omemoManager, OmemoDevice device, T_IdKey key) Store the public identityKey of the device.
abstract void	storeOmemoIdentityKeyPair(OmemoManager omemoManager, T_IdKeyPair identityKeyPair) Store our identityKeyPair in storage.
abstract void	storeOmemoPreKey(OmemoManager omemoManager, int preKeyId, T_PreKey preKey) Store a PreKey in storage.
void	storeOmemoPreKeys(OmemoManager omemoManager, HashMap<Integer,T_PreKey> preKeyHashMap) Store a whole bunch of preKeys.
abstract void	storeOmemoSignedPreKey(OmemoManager omemoManager, int signedPreKeyId, T_SigPreKey signedPreKey) Store a signedPreKey in storage.
abstract void	storeRawSession(OmemoManager omemoManager, OmemoDevice device, T_Sess session) Store a crypto-lib specific session to storage.
abstract void	trustOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, OmemoFingerprint identityKeyFingerprint)
void	trustOmemoIdentity(OmemoManager omemoManager, OmemoDevice device, T_IdKey identityKey) Trust an OmemoIdentity.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OmemoStore

public OmemoStore()

Create a new OmemoStore.

Method Detail

isFreshInstallation

public abstract boolean isFreshInstallation(OmemoManager omemoManager)

Return true if this is a fresh installation.

Parameters:

omemoManager - omemoManager of our device.

Returns:

true or false.

getOmemoSessionOf

public OmemoSession<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> getOmemoSessionOf(OmemoManager omemoManager,
                                                                                                                      OmemoDevice device)

Return the OmemoSession for the OmemoDevice. If there is no OmemoSession for the device yet, build one from local raw session material.

Parameters:

omemoManager - omemoManager of our device.

device - OmemoDevice

Returns:

OmemoSession

loadLastPreKeyId

public abstract int loadLastPreKeyId(OmemoManager omemoManager)

Return the id of the last generated preKey. This is used to generate new preKeys without preKeyId collisions.

Parameters:

omemoManager - omemoManager of our device.

Returns:

id of the last preKey

storeLastPreKeyId

public abstract void storeLastPreKeyId(OmemoManager omemoManager,
                                       int currentPreKeyId)

Store the id of the last preKey we generated.

Parameters:

omemoManager - omemoManager of our device.

currentPreKeyId - the id of the last generated PreKey

generateOmemoIdentityKeyPair

public T_IdKeyPair generateOmemoIdentityKeyPair()

Generate a new IdentityKeyPair. We should always have only one pair and usually keep this for a long time.

Returns:

identityKeyPair

loadOmemoIdentityKeyPair

public abstract T_IdKeyPair loadOmemoIdentityKeyPair(OmemoManager omemoManager)
                                              throws CorruptedOmemoKeyException

Load our identityKeyPair from storage.

Parameters:

omemoManager - omemoManager of our device.

Returns:

identityKeyPair

Throws:

CorruptedOmemoKeyException - Thrown, if the stored key is damaged (*hands up* not my fault!)

storeOmemoIdentityKeyPair

public abstract void storeOmemoIdentityKeyPair(OmemoManager omemoManager,
                                               T_IdKeyPair identityKeyPair)

Store our identityKeyPair in storage. It would be a cool feature, if the key could be stored in a encrypted database or something similar.

Parameters:

omemoManager - omemoManager of our device.

identityKeyPair - identityKeyPair

loadOmemoIdentityKey

public abstract T_IdKey loadOmemoIdentityKey(OmemoManager omemoManager,
                                             OmemoDevice device)
                                      throws CorruptedOmemoKeyException

Load the public identityKey of the device.

Parameters:

omemoManager - omemoManager of our device.

device - device

Returns:

identityKey

Throws:

CorruptedOmemoKeyException - when the key in question is corrupted and cant be deserialized.

storeOmemoIdentityKey

public abstract void storeOmemoIdentityKey(OmemoManager omemoManager,
                                           OmemoDevice device,
                                           T_IdKey key)

Store the public identityKey of the device.

Parameters:

omemoManager - omemoManager of our device.

device - device

key - identityKey

isTrustedOmemoIdentity

public boolean isTrustedOmemoIdentity(OmemoManager omemoManager,
                                      OmemoDevice device,
                                      T_IdKey identityKey)

Decide, whether a identityKey of a device is trusted or not. If you want to use this module, you should memorize, whether the user has trusted this key or not, since the owner of the identityKey will be able to read sent messages when this method returned 'true' for their identityKey. Either you let the user decide whether you trust a key every time you see a new key, or you implement something like 'blind trust' (see https://gultsch.de/trust.html).

Parameters:

omemoManager - omemoManager of our device.

device - Owner of the key

identityKey - identityKey

Returns:

true, if the user trusts the key and wants to send messages to it, otherwise false

isTrustedOmemoIdentity

public abstract boolean isTrustedOmemoIdentity(OmemoManager omemoManager,
                                               OmemoDevice device,
                                               OmemoFingerprint fingerprint)

isDecidedOmemoIdentity

public boolean isDecidedOmemoIdentity(OmemoManager omemoManager,
                                      OmemoDevice device,
                                      T_IdKey identityKey)

Did the user yet made a decision about whether to trust or distrust this device?

Parameters:

omemoManager - omemoManager of our device.

device - device

identityKey - IdentityKey

Returns:

true, if the user either trusted or distrusted the device. Return false, if the user did not yet decide.

isDecidedOmemoIdentity

public abstract boolean isDecidedOmemoIdentity(OmemoManager omemoManager,
                                               OmemoDevice device,
                                               OmemoFingerprint fingerprint)

trustOmemoIdentity

public void trustOmemoIdentity(OmemoManager omemoManager,
                               OmemoDevice device,
                               T_IdKey identityKey)

Trust an OmemoIdentity. This involves marking the key as trusted.

Parameters:

omemoManager - omemoManager of our device.

device - device

identityKey - identityKey

trustOmemoIdentity

public abstract void trustOmemoIdentity(OmemoManager omemoManager,
                                        OmemoDevice device,
                                        OmemoFingerprint identityKeyFingerprint)

distrustOmemoIdentity

public void distrustOmemoIdentity(OmemoManager omemoManager,
                                  OmemoDevice device,
                                  T_IdKey identityKey)

Distrust an OmemoIdentity. This involved marking the key as distrusted.

Parameters:

omemoManager - omemoManager of our device.

device - device

identityKey - identityKey

distrustOmemoIdentity

public abstract void distrustOmemoIdentity(OmemoManager omemoManager,
                                           OmemoDevice device,
                                           OmemoFingerprint fingerprint)

setDateOfLastReceivedMessage

public abstract void setDateOfLastReceivedMessage(OmemoManager omemoManager,
                                                  OmemoDevice from,
                                                  Date date)

Set the date in millis of the last message that was received from device 'from' to 'date'.

Parameters:

omemoManager - omemoManager of our device.

from - device in question

date - date of the last received message

setDateOfLastReceivedMessage

public void setDateOfLastReceivedMessage(OmemoManager omemoManager,
                                         OmemoDevice from)

Set the date in millis of the last message that was received from device 'from' to now.

Parameters:

omemoManager - omemoManager of our device.

from - device in question

getDateOfLastReceivedMessage

public abstract Date getDateOfLastReceivedMessage(OmemoManager omemoManager,
                                                  OmemoDevice from)

Return the date in millis of the last message that was received from device 'from'.

Parameters:

omemoManager - omemoManager of our device.

from - device in question

Returns:

date if existent as long, otherwise -1

setDateOfLastSignedPreKeyRenewal

public abstract void setDateOfLastSignedPreKeyRenewal(OmemoManager omemoManager,
                                                      Date date)

Set the date in millis of the last time the signed preKey was renewed.

Parameters:

omemoManager - omemoManager of our device.

date - date

setDateOfLastSignedPreKeyRenewal

public void setDateOfLastSignedPreKeyRenewal(OmemoManager omemoManager)

Store the date of the last preKey renewal in the omemoStore.

Parameters:

omemoManager - omemoManager of our device.

getDateOfLastSignedPreKeyRenewal

public abstract Date getDateOfLastSignedPreKeyRenewal(OmemoManager omemoManager)

Get the date in millis of the last time the signed preKey was renewed.

Parameters:

omemoManager - omemoManager of our device.

Returns:

date if existent, otherwise null

generateOmemoPreKeys

public HashMap<Integer,T_PreKey> generateOmemoPreKeys(int startId,
                                                      int count)

Generate 'count' new PreKeys beginning with id 'startId'. These preKeys are published and can be used by contacts to establish sessions with us.

Parameters:

startId - start id

count - how many keys do we want to generate

Returns:

Map of new preKeys

loadOmemoPreKey

public abstract T_PreKey loadOmemoPreKey(OmemoManager omemoManager,
                                         int preKeyId)

Load the preKey with id 'preKeyId' from storage.

Parameters:

omemoManager - omemoManager of our device.

preKeyId - id of the key to be loaded

Returns:

loaded preKey

storeOmemoPreKey

public abstract void storeOmemoPreKey(OmemoManager omemoManager,
                                      int preKeyId,
                                      T_PreKey preKey)

Store a PreKey in storage.

Parameters:

omemoManager - omemoManager of our device.

preKeyId - id of the key

preKey - key

storeOmemoPreKeys

public void storeOmemoPreKeys(OmemoManager omemoManager,
                              HashMap<Integer,T_PreKey> preKeyHashMap)

Store a whole bunch of preKeys.

Parameters:

omemoManager - omemoManager of our device.

preKeyHashMap - HashMap of preKeys

removeOmemoPreKey

public abstract void removeOmemoPreKey(OmemoManager omemoManager,
                                       int preKeyId)

remove a preKey from storage. This is called, when a contact used one of our preKeys to establish a session with us.

Parameters:

omemoManager - omemoManager of our device.

preKeyId - id of the used key that will be deleted

loadCurrentSignedPreKeyId

public abstract int loadCurrentSignedPreKeyId(OmemoManager omemoManager)

Return the id of the currently used signed preKey. This is used to avoid collisions when generating a new signedPreKey.

Parameters:

omemoManager - omemoManager of our device.

Returns:

id

storeCurrentSignedPreKeyId

public abstract void storeCurrentSignedPreKeyId(OmemoManager omemoManager,
                                                int currentSignedPreKeyId)

Store the id of the currently used signedPreKey.

Parameters:

omemoManager - omemoManager of our device.

currentSignedPreKeyId - if of the signedPreKey that is currently in use

loadOmemoPreKeys

public abstract HashMap<Integer,T_PreKey> loadOmemoPreKeys(OmemoManager omemoManager)

Return all our current OmemoPreKeys.

Parameters:

omemoManager - omemoManager of our device.

Returns:

Map containing our preKeys

loadOmemoSignedPreKey

public abstract T_SigPreKey loadOmemoSignedPreKey(OmemoManager omemoManager,
                                                  int signedPreKeyId)

Return the signedPreKey with the id 'singedPreKeyId'.

Parameters:

omemoManager - omemoManager of our device.

signedPreKeyId - id of the key

Returns:

key

loadOmemoSignedPreKeys

public abstract HashMap<Integer,T_SigPreKey> loadOmemoSignedPreKeys(OmemoManager omemoManager)

Load all our signed PreKeys.

Parameters:

omemoManager - omemoManager of our device.

Returns:

HashMap of our singedPreKeys

generateOmemoSignedPreKey

public T_SigPreKey generateOmemoSignedPreKey(T_IdKeyPair identityKeyPair,
                                             int signedPreKeyId)
                                      throws CorruptedOmemoKeyException

Generate a new signed preKey.

Parameters:

identityKeyPair - identityKeyPair used to sign the preKey

signedPreKeyId - id that the preKey will have

Returns:

signedPreKey

Throws:

CorruptedOmemoKeyException - when something goes wrong

storeOmemoSignedPreKey

public abstract void storeOmemoSignedPreKey(OmemoManager omemoManager,
                                            int signedPreKeyId,
                                            T_SigPreKey signedPreKey)

Store a signedPreKey in storage.

Parameters:

omemoManager - omemoManager of our device.

signedPreKeyId - id of the signedPreKey

signedPreKey - the key itself

removeOmemoSignedPreKey

public abstract void removeOmemoSignedPreKey(OmemoManager omemoManager,
                                             int signedPreKeyId)

Remove a signedPreKey from storage.

Parameters:

omemoManager - omemoManager of our device.

signedPreKeyId - id of the key that will be removed

loadRawSession

public abstract T_Sess loadRawSession(OmemoManager omemoManager,
                                      OmemoDevice device)

Load the crypto-lib specific session object of the device from storage.

Parameters:

omemoManager - omemoManager of our device.

device - device whose session we want to load

Returns:

crypto related session

loadAllRawSessionsOf

public abstract HashMap<Integer,T_Sess> loadAllRawSessionsOf(OmemoManager omemoManager,
                                                             BareJid contact)

Load all crypto-lib specific session objects of contact 'contact'.

Parameters:

omemoManager - omemoManager of our device.

contact - BareJid of the contact we want to get all sessions from

Returns:

HashMap of deviceId and sessions of the contact

storeRawSession

public abstract void storeRawSession(OmemoManager omemoManager,
                                     OmemoDevice device,
                                     T_Sess session)

Store a crypto-lib specific session to storage.

Parameters:

omemoManager - omemoManager of our device.

device - OmemoDevice whose session we want to store

session - session

removeRawSession

public abstract void removeRawSession(OmemoManager omemoManager,
                                      OmemoDevice device)

Remove a crypto-lib specific session from storage.

Parameters:

omemoManager - omemoManager of our device.

device - device whose session we want to delete

removeAllRawSessionsOf

public abstract void removeAllRawSessionsOf(OmemoManager omemoManager,
                                            BareJid contact)

Remove all crypto-lib specific session of a contact.

Parameters:

omemoManager - omemoManager of our device.

contact - BareJid of the contact

containsRawSession

public abstract boolean containsRawSession(OmemoManager omemoManager,
                                           OmemoDevice device)

Return true, if we have a session with the device, otherwise false. Hint for Signal: Do not try 'return getSession() != null' since this will create a new session.

Parameters:

omemoManager - omemoManager of our device.

device - device

Returns:

true if we have session, otherwise false

loadCachedDeviceList

public abstract CachedDeviceList loadCachedDeviceList(OmemoManager omemoManager,
                                                      BareJid contact)

Load a list of deviceIds from contact 'contact' from the local cache.

Parameters:

omemoManager - omemoManager of our device.

contact - contact we want to get the deviceList of

Returns:

CachedDeviceList of the contact

storeCachedDeviceList

public abstract void storeCachedDeviceList(OmemoManager omemoManager,
                                           BareJid contact,
                                           CachedDeviceList deviceList)

Store the DeviceList of the contact in local storage. See this as a cache.

Parameters:

omemoManager - omemoManager of our device.

contact - Contact

deviceList - list of the contacts devices' ids.

purgeOwnDeviceKeys

public abstract void purgeOwnDeviceKeys(OmemoManager omemoManager)

Delete this device's IdentityKey, PreKeys, SignedPreKeys and Sessions.

Parameters:

omemoManager - omemoManager of our device.

keyUtil

public abstract OmemoKeyUtil<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> keyUtil()

Return a concrete KeyUtil object that we can use as a utility to create keys etc.

Returns:

KeyUtil object

getFingerprint

public OmemoFingerprint getFingerprint(OmemoManager omemoManager)

Return our identityKeys fingerprint.

Parameters:

omemoManager - omemoManager of our device.

Returns:

fingerprint of our identityKeyPair

getDefaultDeviceId

public abstract int getDefaultDeviceId(BareJid user)

Return the default deviceId for a user. The defaultDeviceId will be used when the OmemoManager gets instantiated without passing a specific deviceId. If no default id is set, return -1;

Parameters:

user - user

Returns:

defaultDeviceId or -1

setDefaultDeviceId

public abstract void setDefaultDeviceId(BareJid user,
                                        int defaultDeviceId)

Set the default deviceId of a user.

Parameters:

user - user

defaultDeviceId - defaultDeviceId

getFingerprint

public OmemoFingerprint getFingerprint(OmemoManager omemoManager,
                                       OmemoDevice device)
                                throws CannotEstablishOmemoSessionException

Return the fingerprint of the given devices announced identityKey.

Parameters:

omemoManager - omemoManager of our device.

device - device

Returns:

fingerprint of the identityKey

Throws:

CannotEstablishOmemoSessionException - if we cannot establish a session