Class InboundGroupSession

java.lang.Object
io.github.fherbreteau.vodozemac.NativeHandle
io.github.fherbreteau.vodozemac.megolm.InboundGroupSession
All Implemented Interfaces:
AutoCloseable
public final class InboundGroupSession extends NativeHandle
A Megolm inbound group session represents a single receiving participant in an encrypted group communication involving multiple recipients.

The session includes a ratchet for decryption and an Ed25519 public key for ensuring authenticity. An inbound group session is typically created from a session key obtained from the sender's OutboundGroupSession via OutboundGroupSession.sessionKey().

This class implements AutoCloseable and should be used in a try-with-resources block to ensure native resources are properly released.

Author:
François HERBRETEAU

  • Constructor Details

    • InboundGroupSession

      public InboundGroupSession(String sessionKey)
      Creates a new inbound group session from a session key received over an authenticated channel using the default megolm version.
      Parameters:
      sessionKey - the base64-encoded session key from OutboundGroupSession.sessionKey()
      Throws:
      VodozemacException - if the session key is invalid

    • InboundGroupSession

      public InboundGroupSession(String sessionKey, MegolmSessionVersion version)
      Creates a new inbound group session from a session key received over an authenticated channel.
      Parameters:
      sessionKey - the base64-encoded session key from OutboundGroupSession.sessionKey()
      version - the Megolm session protocol version to use
      Throws:
      VodozemacException - if the session key is invalid

  • Method Details

    • sessionId

      public String sessionId()
      Returns the unique ID of this session.

      The session ID is the Ed25519 public key of the outbound group session that created this session, encoded in base64.

      Returns:
      the session ID as a base64 string
      Throws:
      IllegalStateException - if this session has been closed

    • firstKnownIndex

      public int firstKnownIndex()
      Returns the first known message index for this session.

      The message index reflects how many times the ratchet has advanced, determining which messages the session can decrypt. For example, if the first known index is zero, the session can decrypt all messages encrypted by the outbound group session. If the index is one, it can decrypt all messages except the first (zeroth) one.

      Returns:
      the first known message index
      Throws:
      IllegalStateException - if this session has been closed

    • decrypt

      public DecryptedMessage decrypt(MegolmMessage message)
      Decrypts the provided Megolm message.
      Parameters:
      message - the MegolmMessage to decrypt
      Returns:
      a DecryptedMessage containing the plaintext and message index
      Throws:
      IllegalStateException - if this session has been closed
      DecryptionException - if decryption fails (invalid MAC, padding, or unknown message index)
      SignatureException - if the message signature is invalid

    • pickle

      public String pickle()
      Converts the inbound group session into a JSON string representation.
      Returns:
      a JSON string representing the session
      Throws:
      IllegalStateException - if this session has been closed

    • pickle

      public String pickle(byte[] key)
      Encrypts the inbound group session using the given 32-byte key and returns the encrypted representation.
      Parameters:
      key - a 256-bit (32-byte) key for encrypting the session
      Returns:
      an encrypted string representation of the session
      Throws:
      IllegalStateException - if this session has been closed
      KeyException - if the key is not 32 bytes

    • exportAt

      public Optional<String> exportAt(int index)
      Exports the session at the specified message index.

      The exported session key can be used to create a new InboundGroupSession via importSession(String, MegolmSessionVersion) that can decrypt messages from the given index onwards.

      Parameters:
      index - the message index to export at
      Returns:
      the exported session key as a base64 string, or null if the session has been ratcheted beyond the given index
      Throws:
      IllegalStateException - if this session has been closed

    • exportAtFirstKnownIndex

      public Optional<String> exportAtFirstKnownIndex()
      Exports the session at its first known message index.

      This is equivalent to calling exportAt(int) with firstKnownIndex().

      Returns:
      the exported session key as a base64 string
      Throws:
      IllegalStateException - if this session has been closed

    • advanceTo

      public boolean advanceTo(int index)
      Permanently advances the session to the specified message index.

      Advancing the session will remove the ability to decrypt messages encrypted with a lower index than the provided one.

      Parameters:
      index - the message index to advance to
      Returns:
      true if the ratchet was successfully advanced, false if the ratchet was already advanced beyond the given index
      Throws:
      IllegalStateException - if this session has been closed

    • connected

      public boolean connected(InboundGroupSession other)
      Checks if two sessions are connected, i.e. created from the same outbound group session.

      If the sessions are connected, the session with the lower message index can safely replace the one with the higher message index.

      Parameters:
      other - the other session to compare with
      Returns:
      true if the sessions are connected, false otherwise
      Throws:
      IllegalStateException - if either session has been closed

    • compare

      public SessionOrdering compare(InboundGroupSession other)
      Compares this session with another session.

      Returns a SessionOrdering describing how the two sessions relate to each other. Only connected sessions can be compared meaningfully.

      Parameters:
      other - the other session to compare with
      Returns:
      the ordering relationship between the two sessions
      Throws:
      IllegalStateException - if either session has been closed

    • merge

      public Optional<InboundGroupSession> merge(InboundGroupSession other)
      Merges this session with the given other session, picking the best parts from each.

      This is useful when multiple sessions with the same session ID are received with different ratchet indices and trust properties. The merged session will have the lower (better) initial ratchet index and the combined trust of both sessions.

      Parameters:
      other - the other session to merge with
      Returns:
      an Optional containing the merged session if the sessions are connected, or an empty Optional if they are not connected
      Throws:
      IllegalStateException - if either session has been closed

    • unpickle

      public static InboundGroupSession unpickle(String pickleData)
      Restores an InboundGroupSession from a previously saved JSON string.
      Parameters:
      pickleData - the JSON string from pickle()
      Returns:
      a restored InboundGroupSession
      Throws:
      PickleException - if the data cannot be deserialized

    • unpickle

      public static InboundGroupSession unpickle(String pickleData, byte[] key)
      Restores an InboundGroupSession from an encrypted string using a 32-byte key.
      Parameters:
      pickleData - the encrypted pickle data from pickle(byte[])
      key - a 256-bit (32-byte) key for decrypting the session
      Returns:
      a restored InboundGroupSession
      Throws:
      KeyException - if the key is not 32 bytes
      PickleException - if the data cannot be decrypted or deserialized

    • unpickleLegacy

      public static InboundGroupSession unpickleLegacy(String pickleData, byte[] pickleKey)
      Restores an InboundGroupSession from a legacy libolm pickle format. The pickle must be encrypted with the provided key.
      Parameters:
      pickleData - the libolm pickle data
      pickleKey - the key used to encrypt the pickle data
      Returns:
      a restored InboundGroupSession
      Throws:
      PickleException - if the data cannot be decrypted or deserialized

    • importSession

      public static InboundGroupSession importSession(String sessionKey)
      Creates a new InboundGroupSession from an exported session key with the default version.

      An exported session key can be obtained from another recipient's InboundGroupSession using exportAt(int) or exportAtFirstKnownIndex().

      Warning: Extra care is required to ensure the authenticity of the session, because an exported session key does not include the signature of the original outbound group session creator.

      Parameters:
      sessionKey - the base64-encoded exported session key
      Returns:
      a new InboundGroupSession
      Throws:
      KeyException - if the session key is invalid

    • importSession

      public static InboundGroupSession importSession(String sessionKey, MegolmSessionVersion version)
      Creates a new InboundGroupSession from an exported session key.

      An exported session key can be obtained from another recipient's InboundGroupSession using exportAt(int) or exportAtFirstKnownIndex().

      Warning: Extra care is required to ensure the authenticity of the session, because an exported session key does not include the signature of the original outbound group session creator.

      Parameters:
      sessionKey - the base64-encoded exported session key
      version - the Megolm session protocol version to use
      Returns:
      a new InboundGroupSession
      Throws:
      KeyException - if the session key is invalid