Class OlmSession

java.lang.Object
io.github.fherbreteau.vodozemac.NativeHandle
io.github.fherbreteau.vodozemac.olm.OlmSession
All Implemented Interfaces:
AutoCloseable
public final class OlmSession extends NativeHandle
An Olm session represents one end of an encrypted communication channel between two participants.

A session enables the session owner to encrypt messages intended for, and decrypt messages sent by, the other participant of the channel.

Olm sessions have two important properties:

  1. They are based on a double ratchet algorithm which continuously introduces new entropy into the channel as messages are sent and received. This imbues the channel with self-healing properties, allowing it to recover from a momentary loss of confidentiality in the event of a key compromise.
  2. They are asynchronous, allowing the participant to start sending messages to the other side even if the other participant is not online at the moment.

An OlmSession is acquired from an Account, by calling Account.createOutboundSession(OlmSessionVersion, io.github.fherbreteau.vodozemac.types.Curve25519PublicKey, io.github.fherbreteau.vodozemac.types.Curve25519PublicKey) if you are the first participant to send a message, or Account.createInboundSession(OlmSessionVersion, io.github.fherbreteau.vodozemac.types.Curve25519PublicKey, OlmMessage) if the other participant initiated the channel by sending you a message.

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

  • Method Details

    • sessionId

      public String sessionId()
      Returns the globally unique session ID, in base64-encoded form.
      Returns:
      the session ID as a base64 string
      Throws:
      IllegalStateException - if this session has been closed

    • sessionKeys

      public SessionKeys sessionKeys()
      Returns the keys associated with this session.

      The session keys contain the identity key, base key and one-time key that were used to establish the session, as well as the derived session ID.

      Returns:
      the SessionKeys for this session
      Throws:
      IllegalStateException - if this session has been closed

    • sessionConfig

      public OlmSessionVersion 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 OlmSessionVersion of this session
      Throws:
      IllegalStateException - if this session has been closed

    • hasReceivedMessage

      public boolean hasReceivedMessage()
      Checks whether a message has ever been received and decrypted from the other side.

      This is used to decide if outgoing messages should be sent as normal or pre-key messages.

      Returns:
      true if at least one message has been received, false otherwise
      Throws:
      IllegalStateException - if this session has been closed

    • encrypt

      public OlmMessage encrypt(byte[] plaintext)
      Encrypts the plaintext and returns an OlmMessage.

      The message will either be a pre-key message or a normal message, depending on whether the session is fully established. A session is fully established once you receive (and decrypt) at least one message from the other side.

      Parameters:
      plaintext - the plaintext to encrypt
      Returns:
      the encrypted OlmMessage
      Throws:
      IllegalStateException - if this session has been closed

    • decrypt

      public byte[] decrypt(OlmMessage message)
      Decrypts an Olm message and returns the plaintext.
      Parameters:
      message - the OlmMessage to decrypt
      Returns:
      the decrypted plaintext bytes
      Throws:
      IllegalStateException - if this session has been closed
      DecryptionException - if decryption fails

    • pickle

      public String pickle()
      Converts the 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 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 OlmSession unpickle(String pickleData)
      Restores an OlmSession from a previously saved JSON string.
      Parameters:
      pickleData - the JSON string from pickle()
      Returns:
      a restored OlmSession
      Throws:
      PickleException - if the data cannot be deserialized

    • unpickle

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

    • unpickleLegacy

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