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.

Index

Constructors

Properties

cryptoStore deviceCurve25519Key deviceEd25519Key inboundGroupSessionMessageIndexes maxOneTimeKeys olmPrekeyPromise outboundGroupSessionStore pickleKey sessionsInProgress

Methods

addInboundGroupSession addInboundGroupSessionWithheld createInboundSession createOutboundGroupSession createOutboundSession decryptGroupMessage decryptMessage encryptGroupMessage encryptMessage export exportInboundGroupSession filterOutNotifiedErrorDevices forgetOldFallbackKey generateFallbackKey generateOneTimeKeys getAccount getFallbackKey getInboundGroupSession getInboundGroupSessionKey getOneTimeKeys getOutboundGroupSession getOutboundGroupSessionKey getSession getSessionIdForDevice getSessionIdsForDevice getSessionInfoForDevice getSharedHistoryInboundGroupSessions getUtility hasInboundSessionKeys init initialiseAccount initialiseFromExportedDevice markKeysAsPublished matchesSession maxNumberOfOneTimeKeys recordSessionProblem saveOutboundGroupSession saveSession sessionMayHaveProblems sign storeAccount unpickleInboundGroupSession unpickleSession verifySignature getOlmVersion

Constructors

constructor

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

Properties

`Private` `Readonly` cryptoStore

cryptoStore: CryptoStore

deviceCurve25519Key

deviceCurve25519Key: null | string = null

Curve25519 key for the account, unknown until we load the account from storage in init()

deviceEd25519Key

deviceEd25519Key: null | string = null

Ed25519 key for the account, unknown until we load the account from storage in init()

`Private` inboundGroupSessionMessageIndexes

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

Type declaration

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, senderKey, forwardingCurve25519KeyChain, sessionId, sessionKey, keysClaimed, exportFormat, extraSessionData?): 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>
- Defined in src/crypto/OlmDevice.ts:1041

addInboundGroupSessionWithheld

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

createInboundSession

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

createOutboundGroupSession

createOutboundGroupSession(): string
Generate a new outbound group session

Returns string
sessionId for the outbound session.
- Defined in src/crypto/OlmDevice.ts:905

createOutboundSession

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

decryptGroupMessage

decryptGroupMessage(roomId, senderKey, sessionId, body, eventId, timestamp): 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
- Defined in src/crypto/OlmDevice.ts:1198

decryptMessage

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

encryptGroupMessage

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

encryptMessage

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

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

exportInboundGroupSession

exportInboundGroupSession(senderKey, sessionId, sessionData): 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
- Defined in src/crypto/OlmDevice.ts:1418

filterOutNotifiedErrorDevices

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

forgetOldFallbackKey

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

generateFallbackKey

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

Returns Promise<void>
Resolved once the account is saved back having generated the key
- Defined in src/crypto/OlmDevice.ts:475

generateOneTimeKeys

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

`Private` getAccount

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

getFallbackKey

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

`Private` getInboundGroupSession

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

getInboundGroupSessionKey

getInboundGroupSessionKey(roomId, senderKey, sessionId, chainIndex?): 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
- 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>
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).
- Defined in src/crypto/OlmDevice.ts:1356

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

`Private` getOutboundGroupSession

getOutboundGroupSession<T>(sessionId, func): T
Internal
extract an OutboundGroupSession from outboundGroupSessionStore and call the given function
Type Parameters
- T
Parameters
- sessionId: string
- func: ((session) => T)
  - - (session): T
    - Parameters
      session: OutboundGroupSession
      Returns T
Returns T
result of func
- Defined in src/crypto/OlmDevice.ts:885

getOutboundGroupSessionKey

getOutboundGroupSessionKey(sessionId): 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.
- Defined in src/crypto/OlmDevice.ts:944

`Private` getSession

getSession(deviceKey, sessionId, txn, func): void
Internal
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) => void)
  - - (unpickledSessionInfo): void
    - Parameters
      unpickledSessionInfo: IUnpickledSessionInfo
      Returns void
Returns void
- Defined in src/crypto/OlmDevice.ts:332

getSessionIdForDevice

getSessionIdForDevice(theirDeviceIdentityKey, nowait?, log?): 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.
- Optional log: Logger
  A possibly customised log
Returns Promise<null | string>
session id, or null if no established session
- Defined in src/crypto/OlmDevice.ts:645

getSessionIdsForDevice

getSessionIdsForDevice(theirDeviceIdentityKey): 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
- Defined in src/crypto/OlmDevice.ts:607

getSessionInfoForDevice

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

getSharedHistoryInboundGroupSessions

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

`Private` getUtility

getUtility<T>(func): T
Internal
get an OlmUtility and call the given function
Type Parameters
- T
Parameters
- func: ((utility) => T)
  - - (utility): T
    - Parameters
      utility: Utility
      Returns T
Returns T
result of func
- Defined in src/crypto/OlmDevice.ts:391

hasInboundSessionKeys

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

init

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

`Private` initialiseAccount

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

`Private` initialiseFromExportedDevice

initialiseFromExportedDevice(exportedData, 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:223

markKeysAsPublished

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

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

matchesSession

matchesSession(theirDeviceIdentityKey, sessionId, messageType, ciphertext): 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.
- Defined in src/crypto/OlmDevice.ts:829

maxNumberOfOneTimeKeys

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

Returns number
number of keys
- Defined in src/crypto/OlmDevice.ts:439

recordSessionProblem

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

`Private` saveOutboundGroupSession

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

`Private` saveSession

saveSession(deviceKey, sessionInfo, txn): void
Internal
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:372

sessionMayHaveProblems

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

sign

sign(message): 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
- Defined in src/crypto/OlmDevice.ts:406

`Private` storeAccount

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

`Private` unpickleInboundGroupSession

unpickleInboundGroupSession<T>(sessionData, func): T
Unpickle a session from a sessionData object and invoke the given function. The session is valid only until func returns.
Type Parameters
- T
Parameters
- sessionData: InboundGroupSessionData
  Object describing the session.
- func: ((session) => T)
  Invoked with the unpickled session
  - - (session): T
    - Parameters
      session: InboundGroupSession
      Returns T
Returns T
result of func
- Defined in src/crypto/OlmDevice.ts:964

`Private` unpickleSession

unpickleSession(sessionInfo, func): void
Internal
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) => void)
  - - (unpickledSessionInfo): void
    - Parameters
      unpickledSessionInfo: IUnpickledSessionInfo
      Returns void
Returns void
- Defined in src/crypto/OlmDevice.ts:350

verifySignature

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

`Static` getOlmVersion

getOlmVersion(): [number, number, number]
Returns [number, number, number]
The version of Olm.
- Defined in src/crypto/OlmDevice.ts:168

Class OlmDevice

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns OlmDevice

Properties

Private Readonly cryptoStore

deviceCurve25519Key

deviceEd25519Key

Private inboundGroupSessionMessageIndexes

Type declaration

id: string

timestamp: number

Private maxOneTimeKeys

olmPrekeyPromise

Private outboundGroupSessionStore

pickleKey

sessionsInProgress

Methods

addInboundGroupSession

Parameters

Returns Promise<void>

addInboundGroupSessionWithheld

Parameters

Returns Promise<void>

createInboundSession

Parameters

Returns Promise<IInboundSession>

Throws

createOutboundGroupSession

Returns string

createOutboundSession

Parameters

Returns Promise<string>

decryptGroupMessage

Parameters

Returns Promise<null | IDecryptedGroupMessage>

decryptMessage

Parameters

Returns Promise<string>

encryptGroupMessage

Parameters

Returns string

encryptMessage

Parameters

Returns Promise<IMessage>

export

Returns Promise<IExportedDevice>

exportInboundGroupSession

Parameters

Returns IMegolmSessionData

filterOutNotifiedErrorDevices

Parameters

Returns Promise<IOlmDevice<DeviceInfo>[]>

forgetOldFallbackKey

Returns Promise<void>

generateFallbackKey

Returns Promise<void>

generateOneTimeKeys

Parameters

Returns Promise<void>

Private getAccount

Parameters

Parameters

Returns void

Returns void

getFallbackKey

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

Private getInboundGroupSession

Parameters

Parameters

Returns void

Returns void

getInboundGroupSessionKey

Parameters

Returns Promise<null | IInboundGroupSessionKey>

`Private` `Readonly` cryptoStore

`Private` inboundGroupSessionMessageIndexes

`Private` maxOneTimeKeys

`Private` outboundGroupSessionStore

`Private` getAccount

`Private` getInboundGroupSession

`Private` getOutboundGroupSession

`Private` getSession

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

`Private` getUtility

`Private` initialiseAccount

`Private` initialiseFromExportedDevice

`Private` saveOutboundGroupSession

`Private` saveSession

`Private` storeAccount