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.

Hierarchy

OlmDevice

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:156

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:1038

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:1158

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:551

createOutboundGroupSession

createOutboundGroupSession(): string
Generate a new outbound group session

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

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:509

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:1195

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:783

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:921

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:741

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:296

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:1415

filterOutNotifiedErrorDevices

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

forgetOldFallbackKey

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

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:472

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:458

`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:265

getFallbackKey

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

`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:984

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:1353

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:420

`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:882

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:941

`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:329

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: PrefixedLogger
  
  A possibly customised log
Returns Promise<null | string>
session id, or null if no established session
- Defined in src/crypto/OlmDevice.ts:642

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:604

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: PrefixedLogger = logger
  
  A possibly customised log
Returns Promise<{
    hasReceivedMessage: boolean;
    lastReceivedMessageTs: number;
    sessionId: string;
}[]>
- Defined in src/crypto/OlmDevice.ts:686

getSharedHistoryInboundGroupSessions

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

`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:388

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:1303

init

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

`Private` initialiseAccount

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

`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:220

markKeysAsPublished

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

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

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:826

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:436

recordSessionProblem

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

`Private` saveOutboundGroupSession

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

`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:369

sessionMayHaveProblems

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

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:403

`Private` storeAccount

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

`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:961

`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:347

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:1465

`Static` getOlmVersion

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

Class OlmDevice

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

cryptoStore: CryptoStore

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

roomId: string

senderKey: string

forwardingCurve25519KeyChain: string[]

sessionId: string

sessionKey: string

keysClaimed: Record<string, string>

exportFormat: boolean

extraSessionData: OlmGroupSessionExtraData = {}

Returns Promise<void>

addInboundGroupSessionWithheld

Parameters

roomId: string

senderKey: string

sessionId: string

code: string

reason: string

Returns Promise<void>

createInboundSession

Parameters

theirDeviceIdentityKey: string

messageType: number

ciphertext: string

Returns Promise<IInboundSession>

Throws

createOutboundGroupSession

Returns string

createOutboundSession

Parameters

theirIdentityKey: string

theirOneTimeKey: string

Returns Promise<string>

decryptGroupMessage

Parameters

roomId: string

senderKey: string

sessionId: string

body: string

eventId: string

timestamp: number

Returns Promise<null | IDecryptedGroupMessage>

decryptMessage

Parameters

theirDeviceIdentityKey: string

sessionId: string

messageType: number

ciphertext: string

Returns Promise<string>

encryptGroupMessage

Parameters

sessionId: string

payloadString: string

Returns string

encryptMessage

`Private` `Readonly` cryptoStore

`Private` inboundGroupSessionMessageIndexes

`Private` maxOneTimeKeys

`Private` outboundGroupSessionStore

`Private` getAccount

`Private` getInboundGroupSession

`Optional` chainIndex: number

`Private` getOutboundGroupSession