Class OlmDevice

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

Index

Constructors

constructor

new OlmDevice(cryptoStore: CryptoStore): OlmDevice
Parameters
- cryptoStore: CryptoStore
Returns OlmDevice
- Defined in src/crypto/OlmDevice.ts:180

Properties

`Private` `Readonly` cryptoStore

cryptoStore: CryptoStore

deviceCurve25519Key

deviceCurve25519Key: null | string = null

deviceEd25519Key

deviceEd25519Key: null | string = null

`Private` inboundGroupSessionMessageIndexes

inboundGroupSessionMessageIndexes: Record<string, {
id: string;
timestamp: number;
}> = {}

`Private` maxOneTimeKeys

maxOneTimeKeys: null | number = null

olmPrekeyPromise

olmPrekeyPromise: Promise<any> = ...

`Private` outboundGroupSessionStore

outboundGroupSessionStore: Record<string, string> = {}

pickleKey

pickleKey: string = "DEFAULT_KEY"

sessionsInProgress

sessionsInProgress: Record<string, Promise<void>> = {}

Methods

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)
- Optional extraSessionData: OlmGroupSessionExtraData = {}
  
  any other data to be include with the session
Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:1106

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>
- Defined in src/crypto/OlmDevice.ts:1222

createInboundSession

createInboundSession(theirDeviceIdentityKey: string, messageType: number, ciphertext: string): Promise<IInboundSession>
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>
- Defined in src/crypto/OlmDevice.ts:625

createOutboundGroupSession

createOutboundGroupSession(): string
Generate a new outbound group session

Returns
sessionId for the outbound session.

Returns string
- Defined in src/crypto/OlmDevice.ts:973

createOutboundSession

createOutboundSession(theirIdentityKey: string, theirOneTimeKey: string): Promise<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>
- Defined in src/crypto/OlmDevice.ts:580

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

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>
- Defined in src/crypto/OlmDevice.ts:1261

decryptMessage

decryptMessage(theirDeviceIdentityKey: string, sessionId: string, messageType: number, ciphertext: string): Promise<string>
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>
- Defined in src/crypto/OlmDevice.ts:857

encryptGroupMessage

encryptGroupMessage(sessionId: string, payloadString: string): 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
- Defined in src/crypto/OlmDevice.ts:992

encryptMessage

encryptMessage(theirDeviceIdentityKey: string, sessionId: string, payloadString: string): Promise<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>
- Defined in src/crypto/OlmDevice.ts:820

export

export(): Promise<IExportedDevice>
Export data for re-creating the Olm device later. TODO export data other than just account and (P2P) sessions.

Returns
The exported data

Returns Promise<IExportedDevice>
- Defined in src/crypto/OlmDevice.ts:340

exportInboundGroupSession

exportInboundGroupSession(senderKey: string, sessionId: string, sessionData: InboundGroupSessionData): IMegolmSessionData
Export an inbound group session

Returns
exported session data
Parameters
- senderKey: string
  
  base64-encoded curve25519 key of the sender
- sessionId: string
  
  session identifier
- sessionData: InboundGroupSessionData
  
  The session object from the store
Returns IMegolmSessionData
- Defined in src/crypto/OlmDevice.ts:1497

filterOutNotifiedErrorDevices

filterOutNotifiedErrorDevices(devices: IOlmDevice<DeviceInfo>[]): Promise<IOlmDevice<DeviceInfo>[]>
Parameters
- devices: IOlmDevice<DeviceInfo>[]
Returns Promise<IOlmDevice<DeviceInfo>[]>
- Defined in src/crypto/OlmDevice.ts:927

forgetOldFallbackKey

forgetOldFallbackKey(): Promise<void>
Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:559

generateFallbackKey

generateFallbackKey(): Promise<void>
Generate a new fallback keys

Returns
Resolved once the account is saved back having generated the key

Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:534

generateOneTimeKeys

generateOneTimeKeys(numKeys: number): 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>
- Defined in src/crypto/OlmDevice.ts:517

`Private` getAccount

getAccount(txn: unknown, func: ((account: Account) => void)): 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
- Defined in src/crypto/OlmDevice.ts:309

getFallbackKey

getFallbackKey(): Promise<Record<string, Record<string, string>>>
Returns Promise<Record<string, Record<string, string>>>
- Defined in src/crypto/OlmDevice.ts:546

`Private` getInboundGroupSession

getInboundGroupSession(roomId: string, senderKey: string, sessionId: string, txn: unknown, func: ((session: null | InboundGroupSession, data: null | InboundGroupSessionData, withheld: null | IWithheld) => void)): void
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.
  - - (session: null | InboundGroupSession, data: null | InboundGroupSessionData, withheld: null | IWithheld): void
    - Parameters
      
      session: null | InboundGroupSession
      
      data: null | InboundGroupSessionData
      
      withheld: null | IWithheld
      
      Returns void
Returns void
- Defined in src/crypto/OlmDevice.ts:1058

getInboundGroupSessionKey

getInboundGroupSessionKey(roomId: string, senderKey: string, sessionId: string, chainIndex?: number): Promise<null | IInboundGroupSessionKey>
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>
- Defined in src/crypto/OlmDevice.ts:1434

getOneTimeKeys

getOneTimeKeys(): Promise<{
    curve25519: {
        [keyId: string]: string;
    };
}>
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;
    };
}>
- Defined in src/crypto/OlmDevice.ts:473

`Private` getOutboundGroupSession

getOutboundGroupSession<T>(sessionId: string, func: ((session: OutboundGroupSession) => T)): T
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
- Defined in src/crypto/OlmDevice.ts:953

getOutboundGroupSessionKey

getOutboundGroupSessionKey(sessionId: string): IOutboundGroupSessionKey
Get the session keys for an outbound group session

Returns
current chain index, and base64-encoded secret key.
Parameters
- sessionId: string
  
  the id of the outbound group session
Returns IOutboundGroupSessionKey
- Defined in src/crypto/OlmDevice.ts:1012

`Private` getSession

getSession(deviceKey: string, sessionId: string, txn: unknown, func: ((unpickledSessionInfo: IUnpickledSessionInfo) => void)): void
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
- deviceKey: string
- sessionId: string
- txn: unknown
  
  Opaque transaction object from cryptoStore.doTxn()
- func: ((unpickledSessionInfo: IUnpickledSessionInfo) => void)
  - - (unpickledSessionInfo: IUnpickledSessionInfo): void
    - Parameters
      
      unpickledSessionInfo: IUnpickledSessionInfo
      
      Returns void
Returns void
- Defined in src/crypto/OlmDevice.ts:379

getSessionIdForDevice

getSessionIdForDevice(theirDeviceIdentityKey: string, nowait?: boolean, log?: PrefixedLogger): Promise<null | string>
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>
- Defined in src/crypto/OlmDevice.ts:719

getSessionIdsForDevice

getSessionIdsForDevice(theirDeviceIdentityKey: string): Promise<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[]>
- Defined in src/crypto/OlmDevice.ts:680

getSessionInfoForDevice

getSessionInfoForDevice(deviceIdentityKey: string, nowait?: boolean, log??: PrefixedLogger): 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'.
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;
}[]>
- Defined in src/crypto/OlmDevice.ts:766

getSharedHistoryInboundGroupSessions

getSharedHistoryInboundGroupSessions(roomId: string): Promise<[senderKey: string, sessionId: string][]>
Parameters
- roomId: string
Returns Promise<[senderKey: string, sessionId: string][]>
- Defined in src/crypto/OlmDevice.ts:1518

`Private` getUtility

getUtility<T>(func: ((utility: Utility) => T)): T
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
- Defined in src/crypto/OlmDevice.ts:439

hasInboundSessionKeys

hasInboundSessionKeys(roomId: string, senderKey: string, sessionId: string): Promise<boolean>
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>
- Defined in src/crypto/OlmDevice.ts:1381

init

init(opts?: 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
- opts: IInitOpts = {}
Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:209

`Private` initialiseAccount

initialiseAccount(account: Account): Promise<void>
Parameters
- account: Account
Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:278

`Private` initialiseFromExportedDevice

initialiseFromExportedDevice(exportedData: IExportedDevice, account: Account): 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>
- Defined in src/crypto/OlmDevice.ts:249

markKeysAsPublished

markKeysAsPublished(): Promise<void>
Marks all of the one-time keys as published.

Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:499

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

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>
- Defined in src/crypto/OlmDevice.ts:895

maxNumberOfOneTimeKeys

maxNumberOfOneTimeKeys(): number
Get the maximum number of one-time keys we can store.

Returns
number of keys

Returns number
- Defined in src/crypto/OlmDevice.ts:492

recordSessionProblem

recordSessionProblem(deviceKey: string, type: string, fixed: boolean): Promise<void>
Parameters
- deviceKey: string
- type: string
- fixed: boolean
Returns Promise<void>
- Defined in src/crypto/OlmDevice.ts:918

`Private` saveOutboundGroupSession

saveOutboundGroupSession(session: OutboundGroupSession): void
Private
store an OutboundGroupSession in outboundGroupSessionStore
Parameters
- session: OutboundGroupSession
Returns void
- Defined in src/crypto/OlmDevice.ts:940

`Private` saveSession

saveSession(deviceKey: string, sessionInfo: IUnpickledSessionInfo, txn: unknown): 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
- Defined in src/crypto/OlmDevice.ts:424

sessionMayHaveProblems

sessionMayHaveProblems(deviceKey: string, timestamp: number): Promise<null | IProblem>
Parameters
- deviceKey: string
- timestamp: number
Returns Promise<null | IProblem>
- Defined in src/crypto/OlmDevice.ts:923

sign

sign(message: string): Promise<string>
Signs a message with the ed25519 key for this account.

Returns
base64-encoded signature
Parameters
- message: string
  
  message to be signed
Returns Promise<string>
- Defined in src/crypto/OlmDevice.ts:454

`Private` storeAccount

storeAccount(txn: unknown, account: Account): void
Parameters
- txn: unknown
- account: Account
Returns void
- Defined in src/crypto/OlmDevice.ts:330

`Private` unpickleInboundGroupSession

unpickleInboundGroupSession<T>(sessionData: InboundGroupSessionData, func: ((session: InboundGroupSession) => T)): T
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
- Defined in src/crypto/OlmDevice.ts:1032

`Private` unpickleSession

unpickleSession(sessionInfo: ISessionInfo, func: ((unpickledSessionInfo: IUnpickledSessionInfo) => void)): void
Private
Creates a session object from a session pickle and executes the given function with it. The session object is destroyed once the function returns.
Parameters
- sessionInfo: ISessionInfo
- func: ((unpickledSessionInfo: IUnpickledSessionInfo) => void)
  - - (unpickledSessionInfo: IUnpickledSessionInfo): void
    - Parameters
      
      unpickledSessionInfo: IUnpickledSessionInfo
      
      Returns void
Returns void
- Defined in src/crypto/OlmDevice.ts:401

verifySignature

verifySignature(key: string, message: string, signature: string): void
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
- Defined in src/crypto/OlmDevice.ts:1547

`Static` getOlmVersion

getOlmVersion(): [number, number, number]
Returns
The version of Olm.

Returns [number, number, number]
- Defined in src/crypto/OlmDevice.ts:186

Class OlmDevice

Alias

Param

Property

Property

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

cryptoStore: CryptoStore

Returns OlmDevice

Properties

Private Readonly cryptoStore

deviceCurve25519Key

deviceEd25519Key

Private inboundGroupSessionMessageIndexes

Private maxOneTimeKeys

olmPrekeyPromise

Private outboundGroupSessionStore

pickleKey

sessionsInProgress

Methods

addInboundGroupSession

Parameters

roomId: string

senderKey: string

forwardingCurve25519KeyChain: string[]

sessionId: string

sessionKey: string

keysClaimed: Record<string, string>

exportFormat: boolean

Optional extraSessionData: OlmGroupSessionExtraData = {}

Returns Promise<void>

addInboundGroupSessionWithheld

Parameters

roomId: string

senderKey: string

sessionId: string

code: string

reason: string

Returns Promise<void>

createInboundSession

Returns

Raises

Parameters

theirDeviceIdentityKey: string

messageType: number

ciphertext: string

Returns Promise<IInboundSession>

createOutboundGroupSession

Returns

Returns string

createOutboundSession

Returns

Parameters

theirIdentityKey: string

theirOneTimeKey: string

Returns Promise<string>

decryptGroupMessage

Returns

Returns

Parameters

roomId: string

senderKey: string

sessionId: string

body: string

eventId: string

timestamp: number

Returns Promise<null | IDecryptedGroupMessage>

decryptMessage

Returns

Parameters

theirDeviceIdentityKey: string

sessionId: string

messageType: number

ciphertext: string

`Private` `Readonly` cryptoStore

`Private` inboundGroupSessionMessageIndexes

`Private` maxOneTimeKeys

`Private` outboundGroupSessionStore

`Optional` extraSessionData: OlmGroupSessionExtraData = {}

`Private` getAccount

`Private` getInboundGroupSession

`Optional` chainIndex: number