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:

CachingOmemoStore, 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	Description
OmemoStore()	Create a new OmemoStore.

Method Summary

Modifier and Type	Method	Description
abstract boolean	containsRawSession(OmemoDevice userDevice, OmemoDevice contactsDevice)	Return true, if we have a session with the device, otherwise false.
T_IdKeyPair	generateOmemoIdentityKeyPair()	Generate a new IdentityKeyPair.
TreeMap<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	getDateOfLastDeviceIdPublication(OmemoDevice userDevice, OmemoDevice contactsDevice)	Return the date of the last time the deviceId was published after previously being not published.
abstract Date	getDateOfLastReceivedMessage(OmemoDevice userDevice, OmemoDevice contactsDevice)	Return the date of the last message that was received from device 'from'.
abstract Date	getDateOfLastSignedPreKeyRenewal(OmemoDevice userDevice)	Get the date of the last time the signed preKey was renewed.
OmemoFingerprint	getFingerprint(OmemoDevice userDevice)	Return our identityKeys fingerprint.
OmemoFingerprint	getFingerprint(OmemoDevice userDevice, OmemoDevice contactsDevice)	Return the fingerprint of the identityKey belonging to contactsDevice.
OmemoFingerprint	getFingerprintAndMaybeBuildSession(OmemoManager.LoggedInOmemoManager managerGuard, OmemoDevice contactsDevice)	Return the fingerprint of the given devices announced identityKey.
abstract OmemoKeyUtil<T_IdKeyPair, T_IdKey, T_PreKey, T_SigPreKey, T_Sess, T_ECPub, T_Bundle>	keyUtil()	Return a concrete KeyUtil object that we can use as a utility to create keys etc.
abstract Map<Integer,T_Sess>	loadAllRawSessionsOf(OmemoDevice userDevice, BareJid contact)	Load all crypto-lib specific session objects of contact 'contact'.
OmemoCachedDeviceList	loadCachedDeviceList(OmemoDevice userDevice)	Load a list of deviceIds from our own devices.
abstract OmemoCachedDeviceList	loadCachedDeviceList(OmemoDevice userDevice, BareJid contact)	Load a list of deviceIds from contact 'contact' from the local cache.
int	loadCurrentOmemoSignedPreKeyId(OmemoDevice userDevice)
abstract T_IdKey	loadOmemoIdentityKey(OmemoDevice userDevice, OmemoDevice contactsDevice)	Load the public identityKey of a device.
abstract T_IdKeyPair	loadOmemoIdentityKeyPair(OmemoDevice userDevice)	Load our identityKeyPair from storage.
abstract int	loadOmemoMessageCounter(OmemoDevice userDevice, OmemoDevice contactsDevice)	Return the current value of the message counter.
abstract T_PreKey	loadOmemoPreKey(OmemoDevice userDevice, int preKeyId)	Load the preKey with id 'preKeyId' from storage.
abstract TreeMap<Integer,T_PreKey>	loadOmemoPreKeys(OmemoDevice userDevice)	Return all our current OmemoPreKeys.
abstract T_SigPreKey	loadOmemoSignedPreKey(OmemoDevice userDevice, int signedPreKeyId)	Return the signedPreKey with the id 'singedPreKeyId'.
abstract TreeMap<Integer, T_SigPreKey>	loadOmemoSignedPreKeys(OmemoDevice userDevice)	Load all our signed PreKeys.
abstract T_Sess	loadRawSession(OmemoDevice userDevice, OmemoDevice contactsDevice)	Load the crypto-lib specific session object of the device from storage.
abstract SortedSet<Integer>	localDeviceIdsOf(BareJid localUser)	Returns a sorted set of all the deviceIds, the localUser has had data stored under in the store.
abstract void	purgeOwnDeviceKeys(OmemoDevice userDevice)	Delete this device's IdentityKey, PreKeys, SignedPreKeys and Sessions.
abstract void	removeAllRawSessionsOf(OmemoDevice userDevice, BareJid contact)	Remove all crypto-lib specific session of a contact.
abstract void	removeOmemoIdentityKey(OmemoDevice userDevice, OmemoDevice contactsDevice)	Removes the identityKey of a device.
abstract void	removeOmemoIdentityKeyPair(OmemoDevice userDevice)	Remove the identityKeyPair of a user.
abstract void	removeOmemoPreKey(OmemoDevice userDevice, int preKeyId)	Remove a preKey from storage.
abstract void	removeOmemoSignedPreKey(OmemoDevice userDevice, int signedPreKeyId)	Remove a signedPreKey from storage.
abstract void	removeRawSession(OmemoDevice userDevice, OmemoDevice contactsDevice)	Remove a crypto-lib specific session from storage.
void	replenishKeys(OmemoDevice userDevice)	Replenish our supply of keys.
abstract void	setDateOfLastDeviceIdPublication(OmemoDevice userDevice, OmemoDevice contactsDevice, Date date)	Set the date of the last time the deviceId was published.
abstract void	setDateOfLastReceivedMessage(OmemoDevice userDevice, OmemoDevice contactsDevice, Date date)	Set the date of the last message that was received from a device.
abstract void	setDateOfLastSignedPreKeyRenewal(OmemoDevice userDevice, Date date)	Set the date of the last time the signed preKey was renewed.
abstract void	storeCachedDeviceList(OmemoDevice userDevice, BareJid contact, OmemoCachedDeviceList contactsDeviceList)	Store the DeviceList of the contact in local storage.
abstract void	storeOmemoIdentityKey(OmemoDevice userDevice, OmemoDevice contactsDevice, T_IdKey contactsKey)	Store the public identityKey of the device.
abstract void	storeOmemoIdentityKeyPair(OmemoDevice userDevice, T_IdKeyPair identityKeyPair)	Store our identityKeyPair in storage.
abstract void	storeOmemoMessageCounter(OmemoDevice userDevice, OmemoDevice contactsDevice, int counter)	Store the number of messages we sent to a device since we last received a message back.
abstract void	storeOmemoPreKey(OmemoDevice userDevice, int preKeyId, T_PreKey preKey)	Store a PreKey in storage.
void	storeOmemoPreKeys(OmemoDevice userDevice, Map<Integer,T_PreKey> preKeyHashMap)	Store a whole bunch of preKeys.
abstract void	storeOmemoSignedPreKey(OmemoDevice userDevice, int signedPreKeyId, T_SigPreKey signedPreKey)	Store a signedPreKey in storage.
abstract void	storeRawSession(OmemoDevice userDevice, OmemoDevice contactsDevice, T_Sess session)	Store a crypto-lib specific session to storage.

Methods inherited from class Object

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

Constructor Details

OmemoStore

public OmemoStore()

Create a new OmemoStore.

Method Details

localDeviceIdsOf

public abstract SortedSet<Integer> localDeviceIdsOf(BareJid localUser)

Returns a sorted set of all the deviceIds, the localUser has had data stored under in the store. Basically this returns the deviceIds of all "accounts" of localUser, which are known to the store.

Parameters:

localUser - BareJid of the user.

Returns:

set of deviceIds with available data.

replenishKeys

public void replenishKeys(OmemoDevice userDevice)
                   throws CorruptedOmemoKeyException,
IOException

Replenish our supply of keys. If we are missing any type of keys, generate them fresh.

Parameters:

userDevice - our own OMEMO device

Throws:

CorruptedOmemoKeyException - if the OMEMO key is corrupted.

IOException - if an I/O error occurred.

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:

a fresh identityKeyPair

loadOmemoIdentityKeyPair

public abstract T_IdKeyPair loadOmemoIdentityKeyPair(OmemoDevice userDevice)
                                              throws CorruptedOmemoKeyException,
IOException

Load our identityKeyPair from storage. Return null, if we have no identityKeyPair.

Parameters:

userDevice - our OmemoDevice.

Returns:

loaded identityKeyPair

Throws:

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

IOException - if an I/O error occurred.

storeOmemoIdentityKeyPair

public abstract void storeOmemoIdentityKeyPair(OmemoDevice userDevice,
 T_IdKeyPair identityKeyPair)
                                        throws IOException

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:

userDevice - our OmemoDevice.

identityKeyPair - identityKeyPair

Throws:

IOException - if an I/O error occurred.

removeOmemoIdentityKeyPair

public abstract void removeOmemoIdentityKeyPair(OmemoDevice userDevice)

Remove the identityKeyPair of a user.

Parameters:

userDevice - our device.

loadOmemoIdentityKey

public abstract T_IdKey loadOmemoIdentityKey(OmemoDevice userDevice,
 OmemoDevice contactsDevice)
                                      throws CorruptedOmemoKeyException,
IOException

Load the public identityKey of a device.

Parameters:

userDevice - our OmemoDevice.

contactsDevice - the device of which we want to load the identityKey.

Returns:

loaded identityKey

Throws:

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

IOException - if an I/O error occurred.

storeOmemoIdentityKey

public abstract void storeOmemoIdentityKey(OmemoDevice userDevice,
 OmemoDevice contactsDevice,
 T_IdKey contactsKey)
                                    throws IOException

Store the public identityKey of the device.

Parameters:

userDevice - our OmemoDevice.

contactsDevice - device.

contactsKey - identityKey belonging to the contactsDevice.

Throws:

IOException - if an I/O error occurred.

removeOmemoIdentityKey

public abstract void removeOmemoIdentityKey(OmemoDevice userDevice,
 OmemoDevice contactsDevice)

Removes the identityKey of a device.

Parameters:

userDevice - our omemoDevice.

contactsDevice - device of which we want to delete the identityKey.

storeOmemoMessageCounter

public abstract void storeOmemoMessageCounter(OmemoDevice userDevice,
 OmemoDevice contactsDevice,
 int counter)
                                       throws IOException

Store the number of messages we sent to a device since we last received a message back. This counter gets reset to 0 whenever we receive a message from the contacts device.

Parameters:

userDevice - our omemoDevice.

contactsDevice - device of which we want to set the message counter.

counter - counter value.

Throws:

IOException - if an I/O error occurred.

loadOmemoMessageCounter

public abstract int loadOmemoMessageCounter(OmemoDevice userDevice,
 OmemoDevice contactsDevice)
                                     throws IOException

Return the current value of the message counter. This counter represents the number of message we sent to the contactsDevice without getting a reply back. The default value for this counter is 0.

Parameters:

userDevice - our omemoDevice

contactsDevice - device of which we want to get the message counter.

Returns:

counter value.

Throws:

IOException - if an I/O error occurred.

setDateOfLastReceivedMessage

public abstract void setDateOfLastReceivedMessage(OmemoDevice userDevice,
 OmemoDevice contactsDevice,
 Date date)
                                           throws IOException

Set the date of the last message that was received from a device.

Parameters:

userDevice - omemoManager of our device.

contactsDevice - device in question

date - date of the last received message

Throws:

IOException - if an I/O error occurred.

getDateOfLastReceivedMessage

public abstract Date getDateOfLastReceivedMessage(OmemoDevice userDevice,
 OmemoDevice contactsDevice)
                                           throws IOException

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

Parameters:

userDevice - our OmemoDevice.

contactsDevice - device in question

Returns:

date if existent, null

Throws:

IOException - if an I/O error occurred.

setDateOfLastDeviceIdPublication

public abstract void setDateOfLastDeviceIdPublication(OmemoDevice userDevice,
 OmemoDevice contactsDevice,
 Date date)
                                               throws IOException

Set the date of the last time the deviceId was published. This method only gets called, when the deviceId was inactive/non-existent before it was published.

Parameters:

userDevice - our OmemoDevice

contactsDevice - OmemoDevice in question

date - date of the last publication after not being published

Throws:

IOException - if an I/O error occurred.

getDateOfLastDeviceIdPublication

public abstract Date getDateOfLastDeviceIdPublication(OmemoDevice userDevice,
 OmemoDevice contactsDevice)
                                               throws IOException

Return the date of the last time the deviceId was published after previously being not published. (Point in time, where the status of the deviceId changed from inactive/non-existent to active).

Parameters:

userDevice - our OmemoDevice

contactsDevice - OmemoDevice in question

Returns:

date of the last publication after not being published

Throws:

IOException - if an I/O error occurred.

setDateOfLastSignedPreKeyRenewal

public abstract void setDateOfLastSignedPreKeyRenewal(OmemoDevice userDevice,
 Date date)
                                               throws IOException

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

Parameters:

userDevice - our OmemoDevice.

date - date

Throws:

IOException - if an I/O error occurred.

getDateOfLastSignedPreKeyRenewal

public abstract Date getDateOfLastSignedPreKeyRenewal(OmemoDevice userDevice)
                                               throws IOException

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

Parameters:

userDevice - our OmemoDevice.

Returns:

date if existent, otherwise null

Throws:

IOException - if an I/O error occurred.

generateOmemoPreKeys

public TreeMap<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(OmemoDevice userDevice,
 int preKeyId)
                                  throws IOException

Load the preKey with id 'preKeyId' from storage.

Parameters:

userDevice - our OmemoDevice.

preKeyId - id of the key to be loaded

Returns:

loaded preKey

Throws:

IOException - if an I/O error occurred.

storeOmemoPreKey

public abstract void storeOmemoPreKey(OmemoDevice userDevice,
 int preKeyId,
 T_PreKey preKey)
                               throws IOException

Store a PreKey in storage.

Parameters:

userDevice - our OmemoDevice.

preKeyId - id of the key

preKey - key

Throws:

IOException - if an I/O error occurred.

storeOmemoPreKeys

public void storeOmemoPreKeys(OmemoDevice userDevice,
 Map<Integer,T_PreKey> preKeyHashMap)
                       throws IOException

Store a whole bunch of preKeys.

Parameters:

userDevice - our OmemoDevice.

preKeyHashMap - HashMap of preKeys

Throws:

IOException - if an I/O error occurred.

removeOmemoPreKey

public abstract void removeOmemoPreKey(OmemoDevice userDevice,
 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:

userDevice - our OmemoDevice.

preKeyId - id of the used key that will be deleted

loadOmemoPreKeys

public abstract TreeMap<Integer,T_PreKey> loadOmemoPreKeys(OmemoDevice userDevice)
                                                    throws IOException

Return all our current OmemoPreKeys.

Parameters:

userDevice - our OmemoDevice.

Returns:

Map containing our preKeys

Throws:

IOException - if an I/O error occurred.

loadOmemoSignedPreKey

public abstract T_SigPreKey loadOmemoSignedPreKey(OmemoDevice userDevice,
 int signedPreKeyId)
                                           throws IOException

Return the signedPreKey with the id 'singedPreKeyId'.

Parameters:

userDevice - our OmemoDevice.

signedPreKeyId - id of the key

Returns:

loaded signed preKey

Throws:

IOException - if an I/O error occurred.

loadCurrentOmemoSignedPreKeyId

public int loadCurrentOmemoSignedPreKeyId(OmemoDevice userDevice)
                                   throws IOException

Throws:

IOException

loadOmemoSignedPreKeys

public abstract TreeMap<Integer, T_SigPreKey> loadOmemoSignedPreKeys(OmemoDevice userDevice)
                                                              throws IOException

Load all our signed PreKeys.

Parameters:

userDevice - our OmemoDevice.

Returns:

HashMap of our singedPreKeys

Throws:

IOException - if an I/O error occurred.

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:

a fresh signedPreKey

Throws:

CorruptedOmemoKeyException - when something goes wrong

storeOmemoSignedPreKey

public abstract void storeOmemoSignedPreKey(OmemoDevice userDevice,
 int signedPreKeyId,
 T_SigPreKey signedPreKey)
                                     throws IOException

Store a signedPreKey in storage.

Parameters:

userDevice - our OmemoDevice.

signedPreKeyId - id of the signedPreKey

signedPreKey - the key itself

Throws:

IOException - if an I/O error occurred.

removeOmemoSignedPreKey

public abstract void removeOmemoSignedPreKey(OmemoDevice userDevice,
 int signedPreKeyId)

Remove a signedPreKey from storage.

Parameters:

userDevice - our OmemoDevice.

signedPreKeyId - id of the key that will be removed

loadRawSession

public abstract T_Sess loadRawSession(OmemoDevice userDevice,
 OmemoDevice contactsDevice)
                               throws IOException

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

Parameters:

userDevice - our OmemoDevice.

contactsDevice - device whose session we want to load

Returns:

crypto related session

Throws:

IOException - if an I/O error occurred.

loadAllRawSessionsOf

public abstract Map<Integer,T_Sess> loadAllRawSessionsOf(OmemoDevice userDevice,
 BareJid contact)
                                                  throws IOException

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

Parameters:

userDevice - our OmemoDevice.

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

Returns:

TreeMap of deviceId and sessions of the contact

Throws:

IOException - if an I/O error occurred.

storeRawSession

public abstract void storeRawSession(OmemoDevice userDevice,
 OmemoDevice contactsDevice,
 T_Sess session)
                              throws IOException

Store a crypto-lib specific session to storage.

Parameters:

userDevice - our OmemoDevice.

contactsDevice - OmemoDevice whose session we want to store

session - session

Throws:

IOException - if an I/O error occurred.

removeRawSession

public abstract void removeRawSession(OmemoDevice userDevice,
 OmemoDevice contactsDevice)

Remove a crypto-lib specific session from storage.

Parameters:

userDevice - our OmemoDevice.

contactsDevice - device whose session we want to delete

removeAllRawSessionsOf

public abstract void removeAllRawSessionsOf(OmemoDevice userDevice,
 BareJid contact)

Remove all crypto-lib specific session of a contact.

Parameters:

userDevice - our OmemoDevice.

contact - BareJid of the contact

containsRawSession

public abstract boolean containsRawSession(OmemoDevice userDevice,
 OmemoDevice contactsDevice)

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:

userDevice - our OmemoDevice.

contactsDevice - device

Returns:

true if we have session, otherwise false

loadCachedDeviceList

public abstract OmemoCachedDeviceList loadCachedDeviceList(OmemoDevice userDevice,
 BareJid contact)
                                                    throws IOException

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

Parameters:

userDevice - our OmemoDevice.

contact - contact we want to get the deviceList of

Returns:

CachedDeviceList of the contact

Throws:

IOException - if an I/O error occurred.

loadCachedDeviceList

public OmemoCachedDeviceList loadCachedDeviceList(OmemoDevice userDevice)
                                           throws IOException

Load a list of deviceIds from our own devices.

Parameters:

userDevice - our own OMEMO device

Returns:

the cached OMEMO device list.

Throws:

IOException - if an I/O error occurred.

storeCachedDeviceList

public abstract void storeCachedDeviceList(OmemoDevice userDevice,
 BareJid contact,
 OmemoCachedDeviceList contactsDeviceList)
                                    throws IOException

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

Parameters:

userDevice - our OmemoDevice.

contact - Contact

contactsDeviceList - list of the contacts devices' ids.

Throws:

IOException - if an I/O error occurred.

purgeOwnDeviceKeys

public abstract void purgeOwnDeviceKeys(OmemoDevice userDevice)

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

Parameters:

userDevice - our OmemoDevice.

keyUtil

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

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

Returns:

KeyUtil object

getFingerprint

public OmemoFingerprint getFingerprint(OmemoDevice userDevice)
                                throws CorruptedOmemoKeyException,
IOException

Return our identityKeys fingerprint.

Parameters:

userDevice - our OmemoDevice.

Returns:

fingerprint of our identityKeyPair

Throws:

CorruptedOmemoKeyException - if the identityKey of userDevice is corrupted.

IOException - if an I/O error occurred.

getFingerprint

public OmemoFingerprint getFingerprint(OmemoDevice userDevice,
 OmemoDevice contactsDevice)
                                throws CorruptedOmemoKeyException,
NoIdentityKeyException,
IOException

Return the fingerprint of the identityKey belonging to contactsDevice.

Parameters:

userDevice - our OmemoDevice.

contactsDevice - OmemoDevice we want to have the fingerprint for.

Returns:

fingerprint of the userDevices IdentityKey.

Throws:

CorruptedOmemoKeyException - if the IdentityKey is corrupted.

NoIdentityKeyException - if no IdentityKey for contactsDevice has been found locally.

IOException - if an I/O error occurred.

getFingerprintAndMaybeBuildSession

public OmemoFingerprint getFingerprintAndMaybeBuildSession(OmemoManager.LoggedInOmemoManager managerGuard,
 OmemoDevice contactsDevice)
                                                    throws CannotEstablishOmemoSessionException,
CorruptedOmemoKeyException,
SmackException.NotConnectedException,
InterruptedException,
SmackException.NoResponseException,
IOException

Return the fingerprint of the given devices announced identityKey. If we have no local copy of the identityKey of the contact, build a fresh session in order to get the key.

Parameters:

managerGuard - authenticated OmemoManager

contactsDevice - OmemoDevice we want to get the fingerprint from

Returns:

fingerprint of the contacts OMEMO device

Throws:

CannotEstablishOmemoSessionException - If we have no local copy of the identityKey of the contact and are unable to build a fresh session

CorruptedOmemoKeyException - If the identityKey we have of the contact is corrupted

SmackException.NotConnectedException - if the XMPP connection is not connected.

InterruptedException - if the calling thread was interrupted.

SmackException.NoResponseException - if there was no response from the remote entity.

IOException - if an I/O error occurred.