Package 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:
CachingOmemoStore, FileBasedOmemoStore
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 Details

    • OmemoStore

      public OmemoStore()
      Create a new OmemoStore.

  • Method Details

    • localDeviceIdsOf

      public abstract SortedSet<Integer> localDeviceIdsOf(org.jxmpp.jid.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, org.jxmpp.jid.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, org.jxmpp.jid.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, org.jxmpp.jid.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, org.jxmpp.jid.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, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException, org.jivesoftware.smack.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
      org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
      IOException - if an I/O error occurred.