Skip to content

Latest commit

 

History

History
161 lines (134 loc) · 11.1 KB

functionality.md

File metadata and controls

161 lines (134 loc) · 11.1 KB

Functionality/Use Cases

  • the maximum number of skipped message keys to keep around per session is configurable

    • the default is set to 1000
    • the value is limited neither upwards nor downwards
    • skipped message keys are deleted following LRU once the limit is reached

  • the maximum number of skipped message keys in a single message is configurable

    • the default is set to the maximum number of skipped message keys per session
    • the value is not limited downwards, altough a value of 0 is forbidden if the maximum number of skipped message keys per session is non-zero
    • the value is limited upwards to be lower than or equal to the maximum number of skipped message keys per session

  • device lists are managed

    • PEP updates to device lists are handled
      • a function is provided to feed PEP updates to device lists into the library
      • a PEP downloading mechanism must be provided by the application to download device lists from PEP
    • the own device list is managed
      • the own device is added to the list if it isn't included
      • a label for the own device can optionally be provided
      • a PEP publishing mechanism must be provided by the application to update the device list in PEP
    • the most recent version of all device lists is cached
    • a convenience method is provided to manually trigger the refresh of a device list
    • devices that are removed from the device list are marked as "inactive", while devices on the list are marked as "active"
    • only active devices are considered during encryption
    • a device becoming inactive has no other effect than it being omitted during encryption, i.e. the data corrsponding to the device is never (automatically) deleted
    • device lists of different backends are merged. it is assumed that device ids are unique even across backends. the same device id in multiple lists is assumed to represent the same device.
    • the backends supported by each device are indicated together with the device id

  • the own bundle is managed

    • the identity key is managed
    • the signed pre key is managed
      • the signed pre key is rotated periodically
      • the rotation period is configurable
      • a default rotation period of between one week and one month is provided
      • the signed pre key of the previous rotation is kept around for the next full period to account for delayed messages
    • the pre keys are managed
      • the number of pre keys is capped to 100
      • the threshold for when to generate new pre keys is configurable
      • the threshold can not be configured lower than 25
      • the default threshold is 99, which means that every used pre key is replaced right away
    • a PEP publishing mechanism must be provided by the application to update the bundle in PEP
    • a PEP downloading mechanism must be provided by the application to download a bundle from PEP
    • one bundle is managed per backend, only the identity key is shared between all backends/bundles
      • care is taken to provide the identity key to each backend in the format required by the backend (i.e. Ed25519 or Curve25519)

  • the own device id is generated

    • the device id is shared across all backends
    • the current device lists are consulted prior to device id generation to avoid the very unlikely case of a collision
      • no efforts are made to detect clashes or avoid races (even on protocol level), due to the very low likeliness of a collision
      • this mechanism can not prevent collisions with new backends if backends are added after the device id has been generated
    • it is assumed that other clients also share device ids and identity keys across backends

  • trust is managed

    • custom trust levels are supported, allowing for different trust systems like BTBV
    • a callback must be implemented to translate custom trust levels into core trust levels understood by the library
    • the default trust level to assign to new devices must be specified
    • trust decisions are always requested in bulk, such that applications can e.g. show one decision dialog for all outstanding trust decisions
    • trust is shared across backends
    • trust is applied to pairs of identity key and bare JID, device ids are not part of trust

  • sessions can be built

    • transparently when sending or receiving encrypted messages
    • explicit session building APIs are not provided
    • requires own bundle management
    • sessions are per-backend
    • a PEP downloading mechanism must be provided by the application to download public bundles from PEP

  • messages can be encrypted

    • requires session building, device list management and trust management
    • multiple recipients are supported
    • own devices are automatically added to the list of recipients, the sending device is removed from the list
    • messages are only encrypted for devices whose trust level evaluates to "trusted"
    • the message is not automatically sent, but a structure containing the encrypted payload and the headers is returned
    • the backend(s) to encrypt the message with can be selected explicitly or implicitly
      • in the explicit selection, a list of namespaces is given of which the order decides priority
      • the type of the message parameter to the encryption methods is generic, and each backend provides a method to serialize the type into a byte string
        • this is necessary because different backends require different inputs to message encryption. For example, omemo:1 requires stanzas for SCE and legacy OMEMO requires just text
        • when multiple backends are used together, the generic type can be chosen as the lowest common denominator between all backend input types, and implement the serialization methods accordingly
      • implicit selection is the default, with the priority order taken from the order of the backends as passed to the constructor

  • empty OMEMO messages can be sent

    • transparently when required by the protocol
    • explicit API for empty OMEMO messages is not provided
    • a mechanism must be provided by the application to send empty OMEMO messages
    • trust is not applied for empty OMEMO messages

  • messages can be decrypted

    • requires session building and trust management
    • the whole OMEMO-encrypted message can be passed to the library, it will select the correct header corresponding the the device
    • the type of the decrypted message is generic, each backend provides a method to deserialize the decrypted message body from a byte string into its respective type
      • this is necessary because different backends produce different outputs from message decryption. For example, omemo:1 produces stanzas from SCE and legacy OMEMO produces just text
      • when multiple backends are used together, the generic type can be chosen as the lowest common denominator between all backend output types, and implement the deserialization methods accordingly
    • device lists are automatically refreshed when encountering a message by a device that is not cached
    • the backend to decrypt the message with is implicitly selected by looking at the type of the message structure
    • messages sent by devices with undecided trust are decrytped
      • it is detectable in case the message of an undecided device was decrypted
    • duplicate messages are not detected, that task is up to the application

  • opt-out is not handled

  • MUC participant list management is not provided

    • message encryption to multiple recipients is supported though

  • passive session initiations are automatically completed

    • requires empty OMEMO messages

  • message catch-up is handled

    • methods are provided to notify the library about start and end of message catch-up
    • the library automatically enters catch-up mode when loaded
    • pre keys are retained during catch-up and deleted when the catch-up is done
    • delays automated staleness prevention responses
    • requires automatic completion of passive session initiations

  • manual per-device session replacement is provided

    • requires empty OMEMO messages

  • global or per-JID session replacement is not provided

  • own staleness is prevented

    • received messages with a ratchet counter of 53 or higher trigger an automated response
    • automated responses are delayed until after catch-up is done and only one message is sent per stale session afterwards
    • requires empty OMEMO messages

  • stale devices are not detected

    • however, API is offered to query the sending chain length of a session, which is one important piece of information that clients might use for staleness detection

  • account purging is supported

    • removes all data related to a bare JID across all backends
    • useful e.g. to remove all OMEMO-related data corresponding to an XMPP account that was blocked by the user

  • a convenience method to get the identity key fingerprint is provided

    • independent of the backend

  • methods are provided to retrieve information about devices

    • information for all devices of a bare JID can be retrieved in bulk
    • includes device id, label, identity key, trust information, supported backends, active status
    • independent of the backend

  • backends can be provided for different versions of the OMEMO protocol

    • the protocol version a backend implements is identified by its namespace

  • data storage has to be provided by the application

    • an asyncio-based storage interface has to be implemented
      • this interface transparently handles caching
      • the interface represents generic key-value storage with opaque keys and values
    • automatic migrations between storage format versions are provided
    • storage consistency is guaranteed
      • write operations MUST NOT cache or defer but perform the writing operation right away
      • when encrypting or decrypting, changes to the state are only persisted when success is guaranteed

  • a convenience method to verify consistency (and fix) of the server-side data with the local data is provided

    • these checks are not ran automatically, but the documentation includes a hint and examples run the checks after startup

Part of the respective backends

  • a state migration tool/function is provided for migration from legacy python-omemo to the new storage format

  • a state migration tool/function is provided for migration from libsignal to python-omemo

  • convenience functions for XML (de)serialization is provided using the ElementTree API

    • this part is fully optional, the application may take care of (de)serialization itself
    • installed only when doing pip install *backend*[xml]