Class OlmDevice

constructor

• new OlmDevice(cryptoStore: CryptoStore): OlmDevice

• Parameters

  • cryptoStore: CryptoStore

  Returns OlmDevice

deviceCurve25519Key

deviceEd25519Key

olmPrekeyPromise

pickleKey

sessionsInProgress

addInboundGroupSession

• addInboundGroupSession(
      roomId: string,
      senderKey: string,
      forwardingCurve25519KeyChain: string[],
      sessionId: string,
      sessionKey: string,
      keysClaimed: Record<string, string>,
      exportFormat: boolean,
      extraSessionData?: OlmGroupSessionExtraData,
  ): Promise<void>

• 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)
  • extraSessionData: OlmGroupSessionExtraData = {}

    any other data to be include with the session

  Returns Promise<void>

addInboundGroupSessionWithheld

• addInboundGroupSessionWithheld(
      roomId: string,
      senderKey: string,
      sessionId: string,
      code: string,
      reason: string,
  ): 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>

createInboundSession

• createInboundSession(
      theirDeviceIdentityKey: string,
      messageType: number,
      ciphertext: string,
  ): Promise<IInboundSession>

• Generate a new inbound session, given an incoming message

  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>

  decrypted payload, and session id of new session

  Throws

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

createOutboundGroupSession

• createOutboundGroupSession(): string

• Generate a new outbound group session

  Returns string

  sessionId for the outbound session.

createOutboundSession

• createOutboundSession(
      theirIdentityKey: string,
      theirOneTimeKey: string,
  ): Promise<string>

• Generate a new outbound session

  The new session will be stored in the cryptoStore.

  Parameters

  • theirIdentityKey: string

    remote user's Curve25519 identity key
  • theirOneTimeKey: string

    remote user's one-time Curve25519 key

  Returns Promise<string>

  sessionId for the outbound session.

decryptGroupMessage

• decryptGroupMessage(
      roomId: string,
      senderKey: string,
      sessionId: string,
      body: string,
      eventId: string,
      timestamp: number,
  ): Promise<null | IDecryptedGroupMessage>

• Decrypt a received message with an inbound group session

  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>

  null if the sessionId is unknown

decryptMessage

• decryptMessage(
      theirDeviceIdentityKey: string,
      sessionId: string,
      messageType: number,
      ciphertext: string,
  ): Promise<string>

• Decrypt an incoming message using an existing 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<string>

  decrypted payload.

encryptGroupMessage

• encryptGroupMessage(sessionId: string, payloadString: string): string

• Encrypt an outgoing message with an outbound group session

  Parameters

  • sessionId: string

    the id of the outboundgroupsession
  • payloadString: string

    payload to be encrypted and sent

  Returns string

  ciphertext

encryptMessage

• encryptMessage(
      theirDeviceIdentityKey: string,
      sessionId: string,
      payloadString: string,
  ): Promise<IMessage>

• Encrypt an outgoing message using an existing session

  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<IMessage>

  ciphertext

export

• export(): Promise<IExportedDevice>

• Export data for re-creating the Olm device later. TODO export data other than just account and (P2P) sessions.

  Returns Promise<IExportedDevice>

  The exported data

exportInboundGroupSession

• exportInboundGroupSession(
      senderKey: string,
      sessionId: string,
      sessionData: InboundGroupSessionData,
  ): IMegolmSessionData

• Export an inbound group session

  Parameters

  • senderKey: string

    base64-encoded curve25519 key of the sender
  • sessionId: string

    session identifier
  • sessionData: InboundGroupSessionData

    The session object from the store

  Returns IMegolmSessionData

  exported session data

filterOutNotifiedErrorDevices

• filterOutNotifiedErrorDevices(
      devices: IOlmDevice<DeviceInfo>[],
  ): Promise<IOlmDevice<DeviceInfo>[]>

• Parameters

  • devices: IOlmDevice<DeviceInfo>[]

  Returns Promise<IOlmDevice<DeviceInfo>[]>

forgetOldFallbackKey

• forgetOldFallbackKey(): Promise<void>

• Returns Promise<void>

generateFallbackKey

• generateFallbackKey(): Promise<void>

• Generate a new fallback keys

  Returns Promise<void>

  Resolved once the account is saved back having generated the key

generateOneTimeKeys

• generateOneTimeKeys(numKeys: number): Promise<void>

• Generate some new one-time keys

  Parameters

  • numKeys: number

    number of keys to generate

  Returns Promise<void>

  Resolved once the account is saved back having generated the keys

getFallbackKey

• getFallbackKey(): Promise<Record<string, Record<string, string>>>

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

getInboundGroupSessionKey

• getInboundGroupSessionKey(
      roomId: string,
      senderKey: string,
      sessionId: string,
      chainIndex?: number,
  ): Promise<null | IInboundGroupSessionKey>

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

  Parameters

  • roomId: string

    room in which the message was received
  • senderKey: string

    base64-encoded curve25519 key of the sender
  • sessionId: string

    session identifier
  • OptionalchainIndex: number

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

  Returns Promise<null | IInboundGroupSessionKey>

  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).

getOneTimeKeys

• getOneTimeKeys(): Promise<OneTimeKeys>

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

  Returns Promise<OneTimeKeys>

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

getOutboundGroupSessionKey

• getOutboundGroupSessionKey(sessionId: string): IOutboundGroupSessionKey

• Get the session keys for an outbound group session

  Parameters

  • sessionId: string

    the id of the outbound group session

  Returns IOutboundGroupSessionKey

  current chain index, and base64-encoded secret key.

getSessionIdForDevice

• getSessionIdForDevice(
      theirDeviceIdentityKey: string,
      nowait?: boolean,
      log?: Logger,
  ): Promise<null | string>

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

  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.
  • Optionallog: Logger

    A possibly customised log

  Returns Promise<null | string>

  session id, or null if no established session

getSessionIdsForDevice

• getSessionIdsForDevice(theirDeviceIdentityKey: string): Promise<string[]>

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

  Parameters

  • theirDeviceIdentityKey: string

    Curve25519 identity key for the remote device

  Returns Promise<string[]>

  a list of known session ids for the device

getSessionInfoForDevice

• getSessionInfoForDevice(
      deviceIdentityKey: string,
      nowait?: boolean,
      log?: Logger,
  ): Promise<
      {
          hasReceivedMessage: boolean;
          lastReceivedMessageTs: number;
          sessionId: 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'.

  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.
  • log: Logger = logger

    A possibly customised log

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

getSharedHistoryInboundGroupSessions

• getSharedHistoryInboundGroupSessions(
      roomId: string,
  ): Promise<[senderKey: string, sessionId: string][]>

• Parameters

  • roomId: string

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

hasInboundSessionKeys

• hasInboundSessionKeys(
      roomId: string,
      senderKey: string,
      sessionId: string,
  ): Promise<boolean>

• Determine if we have the keys for a given megolm 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>

  true if we have the keys to this session

init

• init(IInitOpts?: IInitOpts): Promise<void>

• 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

  • IInitOpts: IInitOpts = {}

    opts to initialise the OlmAccount with

  Returns Promise<void>

markKeysAsPublished

• markKeysAsPublished(): Promise<void>

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

  Returns Promise<void>

matchesSession

• matchesSession(
      theirDeviceIdentityKey: string,
      sessionId: string,
      messageType: number,
      ciphertext: string,
  ): Promise<boolean>

• Determine if an incoming messages is a prekey message matching an existing 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>

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

maxNumberOfOneTimeKeys

• maxNumberOfOneTimeKeys(): number

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

  Returns number

  number of keys

recordSessionProblem

• recordSessionProblem(
      deviceKey: string,
      type: string,
      fixed: boolean,
  ): Promise<void>

• Parameters

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

  Returns Promise<void>

sessionMayHaveProblems

• sessionMayHaveProblems(
      deviceKey: string,
      timestamp: number,
  ): Promise<null | IProblem>

• Parameters

  • deviceKey: string
  • timestamp: number

  Returns Promise<null | IProblem>

sign

• sign(message: string): Promise<string>

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

  Parameters

  • message: string

    message to be signed

  Returns Promise<string>

  base64-encoded signature

verifySignature

• verifySignature(key: string, message: string, signature: string): void

• Verify an ed25519 signature.

  Parameters

  • key: string

    ed25519 key
  • message: string

    message which was signed
  • signature: string

    base64-encoded signature to be checked

  Returns void

  Throws

  Error 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".

StaticgetOlmVersion

• getOlmVersion(): [number, number, number]

• Returns [number, number, number]

  The version of Olm.