Class OutboundGroupSession

java.lang.Object
io.github.fherbreteau.vodozemac.NativeHandle
io.github.fherbreteau.vodozemac.megolm.OutboundGroupSession
All Implemented Interfaces:
AutoCloseable
public final class OutboundGroupSession extends NativeHandle
A Megolm outbound group session represents a single sending participant in an encrypted group communication context containing multiple receiving parties.

A group session consists of a ratchet, used for encryption, and an Ed25519 signing key pair, used for authenticity. The session key (obtained via sessionKey()) can be shared with other participants so that they can create InboundGroupSession objects to decrypt messages sent by this session.

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

    • OutboundGroupSession

      public OutboundGroupSession()
      Constructs a new outbound group session with a random ratchet state and signing key pair.

    • OutboundGroupSession

      public OutboundGroupSession(MegolmSessionVersion version)
      Constructs a new outbound group session with a random ratchet state and signing key pair.
      Parameters:
      version - the Megolm session protocol version to use

  • Method Details

    • sessionId

      public String sessionId()
      Returns the globally unique session ID, in base64-encoded form.

      The session ID is the public part of the Ed25519 key pair associated with the group session. Due to the construction, every session ID is probabilistically globally unique.

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

    • messageIndex

      public int messageIndex()
      Returns the current message index.

      The message index is incremented each time a message is encrypted with the group session.

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

    • sessionKey

      public String sessionKey()
      Exports the group session into a session key.

      The session key contains the key version constant, the current message index, the ratchet state, and the public part of the signing key pair. It is signed by the signing key pair for authenticity. The session key is typically sent to other group participants via a secure peer-to-peer channel (e.g. an Olm channel) so that they can reconstruct an InboundGroupSession to decrypt messages.

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

    • sessionConfig

      public MegolmSessionVersion sessionConfig()
      Returns the session configuration (protocol version) used by this session.

      The version determines the MAC truncation behaviour used for encryption and authentication.

      Returns:
      the MegolmSessionVersion of this session
      Throws:
      IllegalStateException - if this session has been closed

    • encrypt

      public MegolmMessage encrypt(byte[] plaintext)
      Encrypts the given plaintext with the group session.

      The resulting ciphertext is MAC-ed, signed with the group session's Ed25519 key pair, and returned as a structured MegolmMessage.

      Parameters:
      plaintext - the plaintext to encrypt
      Returns:
      the encrypted message as a MegolmMessage
      Throws:
      IllegalStateException - if this session has been closed

    • pickle

      public String pickle()
      Converts the 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 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

    • unpickle

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

    • unpickle

      public static OutboundGroupSession unpickle(String pickleData, byte[] key)
      Restores an OutboundGroupSession 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 OutboundGroupSession
      Throws:
      KeyException - if the key is not 32 bytes
      PickleException - if the data cannot be decrypted or deserialized

    • unpickleLegacy

      public static OutboundGroupSession unpickleLegacy(String pickleData, byte[] pickleKey)
      Restores an OutboundGroupSession 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 OutboundGroupSession
      Throws:
      PickleException - if the data cannot be decrypted or deserialized