Manages the olm cryptography functions. Each OlmDevice has a single OlmAccount and a number of OlmSessions.

Accounts and sessions are kept pickled in the cryptoStore.

Alias

module:crypto/OlmDevice

Param

A store for crypto data

Property

Curve25519 key for the account

Property

Ed25519 key for the account

Hierarchy

  • OlmDevice

Constructors

Properties

cryptoStore: CryptoStore
deviceCurve25519Key: null | string = null
deviceEd25519Key: null | string = null
inboundGroupSessionMessageIndexes: Record<string, {
    id: string;
    timestamp: number;
}> = {}
maxOneTimeKeys: null | number = null
olmPrekeyPromise: Promise<any> = ...
outboundGroupSessionStore: Record<string, string> = {}
pickleKey: string = "DEFAULT_KEY"
sessionsInProgress: Record<string, Promise<void>> = {}

Methods

  • Add an inbound group session to the session store

    Parameters

    • roomId: string

      room in which this session will be used

    • senderKey: string

      base64-encoded curve25519 key of the sender

    • forwardingCurve25519KeyChain: string[]

      Devices involved in forwarding this session to us.

    • sessionId: string

      session identifier

    • sessionKey: string

      base64-encoded secret key

    • keysClaimed: Record<string, string>

      Other keys the sender claims.

    • exportFormat: boolean

      true if the megolm keys are in export format (ie, they lack an ed25519 signature)

    • Optional extraSessionData: OlmGroupSessionExtraData = {}

      any other data to be include with the session

    Returns Promise<void>

  • Record in the data store why an inbound group session was withheld.

    Parameters

    • roomId: string

      room that the session belongs to

    • senderKey: string

      base64-encoded curve25519 key of the sender

    • sessionId: string

      session identifier

    • code: string

      reason code

    • reason: string

      human-readable version of code

    Returns Promise<void>

  • Generate a new inbound session, given an incoming message

    Returns

    decrypted payload, and session id of new session

    Raises

    if the received message was not valid (for instance, it didn't use a valid one-time key).

    Parameters

    • theirDeviceIdentityKey: string

      remote user's Curve25519 identity key

    • messageType: number

      messageType field from the received message (must be 0)

    • ciphertext: string

      base64-encoded body from the received message

    Returns Promise<IInboundSession>

  • Generate a new outbound group session

    Returns

    sessionId for the outbound session.

    Returns string

  • Generate a new outbound session

    The new session will be stored in the cryptoStore.

    Returns

    sessionId for the outbound session.

    Parameters

    • theirIdentityKey: string

      remote user's Curve25519 identity key

    • theirOneTimeKey: string

      remote user's one-time Curve25519 key

    Returns Promise<string>

  • Decrypt a received message with an inbound group session

    Returns

    the sessionId is unknown

    Returns

    Parameters

    • roomId: string

      room in which the message was received

    • senderKey: string

      base64-encoded curve25519 key of the sender

    • sessionId: string

      session identifier

    • body: string

      base64-encoded body of the encrypted message

    • eventId: string

      ID of the event being decrypted

    • timestamp: number

      timestamp of the event being decrypted

    Returns Promise<null | IDecryptedGroupMessage>

  • Decrypt an incoming message using an existing session

    Returns

    decrypted payload.

    Parameters

    • theirDeviceIdentityKey: string

      Curve25519 identity key for the remote device

    • sessionId: string

      the id of the active session

    • messageType: number

      messageType field from the received message

    • ciphertext: string

      base64-encoded body from the received message

    Returns Promise<string>

  • Encrypt an outgoing message with an outbound group session

    Returns

    ciphertext

    Parameters

    • sessionId: string

      the id of the outboundgroupsession

    • payloadString: string

      payload to be encrypted and sent

    Returns string

  • Encrypt an outgoing message using an existing session

    Returns

    ciphertext

    Parameters

    • theirDeviceIdentityKey: string

      Curve25519 identity key for the remote device

    • sessionId: string

      the id of the active session

    • payloadString: string

      payload to be encrypted and sent

    Returns Promise<string>

  • Generate a new fallback keys

    Returns

    Resolved once the account is saved back having generated the key

    Returns Promise<void>

  • Generate some new one-time keys

    Returns

    Resolved once the account is saved back having generated the keys

    Parameters

    • numKeys: number

      number of keys to generate

    Returns Promise<void>

  • Private

    extract our OlmAccount from the crypto store and call the given function with the account object The account object is usable only within the callback passed to this function and will be freed as soon the callback returns. It is not usable for the rest of the lifetime of the transaction. This function requires a live transaction object from cryptoStore.doTxn() and therefore may only be called in a doTxn() callback.

    Parameters

    • txn: unknown

      Opaque transaction object from cryptoStore.doTxn()

    • func: ((account: Account) => void)
        • (account: Account): void
        • Parameters

          • account: Account

          Returns void

    Returns void

  • Returns Promise<Record<string, Record<string, string>>>

  • Private

    extract an InboundGroupSession from the crypto store and call the given function

    Parameters

    • roomId: string

      The room ID to extract the session for, or null to fetch sessions for any room.

    • senderKey: string
    • sessionId: string
    • txn: unknown

      Opaque transaction object from cryptoStore.doTxn()

    • func: ((session: null | InboundGroupSession, data: null | InboundGroupSessionData, withheld: null | IWithheld) => void)

      function to call.

    Returns void

  • Extract the keys to a given megolm session, for sharing

    Returns

    details of the session key. The key is a base64-encoded megolm key in export format.

    Throws

    Error If the given chain index could not be obtained from the known index (ie. the given chain index is before the first we have).

    Parameters

    • roomId: string

      room in which the message was received

    • senderKey: string

      base64-encoded curve25519 key of the sender

    • sessionId: string

      session identifier

    • Optional chainIndex: number

      The chain index at which to export the session. If omitted, export at the first index we know about.

    Returns Promise<null | IInboundGroupSessionKey>

  • Get the current (unused, unpublished) one-time keys for this account.

    Returns

    one time keys; an object with the single property curve25519, which is itself an object mapping key id to Curve25519 key.

    Returns Promise<{
        curve25519: {
            [keyId: string]: string;
        };
    }>

  • Private

    extract an OutboundGroupSession from outboundGroupSessionStore and call the given function

    Returns

    result of func

    Type Parameters

    • T

    Parameters

    • sessionId: string
    • func: ((session: OutboundGroupSession) => T)
        • (session: OutboundGroupSession): T
        • Parameters

          • session: OutboundGroupSession

          Returns T

    Returns T

  • Private

    extract an OlmSession from the session store and call the given function The session is usable only within the callback passed to this function and will be freed as soon the callback returns. It is not usable for the rest of the lifetime of the transaction.

    Parameters

    Returns void

  • Get the right olm session id for encrypting messages to the given identity key

    Returns

    session id, or null if no established session

    Parameters

    • theirDeviceIdentityKey: string

      Curve25519 identity key for the remote device

    • nowait: boolean = false

      Don't wait for an in-progress session to complete. This should only be set to true of the calling function is the function that marked the session as being in-progress.

    • Optional log: PrefixedLogger

      A possibly customised log

    Returns Promise<null | string>

  • Get a list of known session IDs for the given device

    Returns

    a list of known session ids for the device

    Parameters

    • theirDeviceIdentityKey: string

      Curve25519 identity key for the remote device

    Returns Promise<string[]>

  • Get information on the active Olm sessions for a device.

    Returns an array, with an entry for each active session. The first entry in the result will be the one used for outgoing messages. Each entry contains the keys 'hasReceivedMessage' (true if the session has received an incoming message and is therefore past the pre-key stage), and 'sessionId'.

    Returns

    Parameters

    • deviceIdentityKey: string

      Curve25519 identity key for the device

    • nowait: boolean = false

      Don't wait for an in-progress session to complete. This should only be set to true of the calling function is the function that marked the session as being in-progress.

    • Optional log: PrefixedLogger = logger

      A possibly customised log

    Returns Promise<{
        hasReceivedMessage: boolean;
        lastReceivedMessageTs: number;
        sessionId: string;
    }[]>

  • Parameters

    • roomId: string

    Returns Promise<[senderKey: string, sessionId: string][]>

  • Private

    get an OlmUtility and call the given function

    Returns

    result of func

    Type Parameters

    • T

    Parameters

    • func: ((utility: Utility) => T)
        • (utility: Utility): T
        • Parameters

          • utility: Utility

          Returns T

    Returns T

  • Determine if we have the keys for a given megolm session

    Returns

    true if we have the keys to this session

    Parameters

    • roomId: string

      room in which the message was received

    • senderKey: string

      base64-encoded curve25519 key of the sender

    • sessionId: string

      session identifier

    Returns Promise<boolean>

  • Initialise the OlmAccount. This must be called before any other operations on the OlmDevice.

    Data from an exported Olm device can be provided in order to re-create this device.

    Attempts to load the OlmAccount from the crypto store, or creates one if none is found.

    Reads the device keys from the OlmAccount object.

    Parameters

    Returns Promise<void>

  • Parameters

    • account: Account

    Returns Promise<void>

  • Populates the crypto store using data that was exported from an existing device. Note that for now only the “account” and “sessions” stores are populated; Other stores will be as with a new device.

    Parameters

    • exportedData: IExportedDevice

      Data exported from another device through the “export” method.

    • account: Account

      an olm account to initialize

    Returns Promise<void>

  • Marks all of the one-time keys as published.

    Returns Promise<void>

  • Determine if an incoming messages is a prekey message matching an existing session

    Returns

    true if the received message is a prekey message which matches the given session.

    Parameters

    • theirDeviceIdentityKey: string

      Curve25519 identity key for the remote device

    • sessionId: string

      the id of the active session

    • messageType: number

      messageType field from the received message

    • ciphertext: string

      base64-encoded body from the received message

    Returns Promise<boolean>

  • Get the maximum number of one-time keys we can store.

    Returns

    number of keys

    Returns number

  • Parameters

    • deviceKey: string
    • type: string
    • fixed: boolean

    Returns Promise<void>

  • Private

    store an OutboundGroupSession in outboundGroupSessionStore

    Parameters

    • session: OutboundGroupSession

    Returns void

  • Private

    store our OlmSession in the session store

    Parameters

    • deviceKey: string
    • sessionInfo: IUnpickledSessionInfo

      {session: OlmSession, lastReceivedMessageTs: int}

    • txn: unknown

      Opaque transaction object from cryptoStore.doTxn()

    Returns void

  • Signs a message with the ed25519 key for this account.

    Returns

    base64-encoded signature

    Parameters

    • message: string

      message to be signed

    Returns Promise<string>

  • Parameters

    • txn: unknown
    • account: Account

    Returns void

  • Unpickle a session from a sessionData object and invoke the given function. The session is valid only until func returns.

    Returns

    result of func

    Type Parameters

    • T

    Parameters

    • sessionData: InboundGroupSessionData

      Object describing the session.

    • func: ((session: InboundGroupSession) => T)

      Invoked with the unpickled session

        • (session: InboundGroupSession): T
        • Parameters

          • session: InboundGroupSession

          Returns T

    Returns T

  • Verify an ed25519 signature.

    Raises

    if there is a problem with the verification. If the key was too small then the message will be "OLM.INVALID_BASE64". If the signature was invalid then the message will be "OLM.BAD_MESSAGE_MAC".

    Parameters

    • key: string

      ed25519 key

    • message: string

      message which was signed

    • signature: string

      base64-encoded signature to be checked

    Returns void

  • Returns

    The version of Olm.

    Returns [number, number, number]

Generated using TypeDoc