Class: module:crypto

module:crypto

new module:crypto(baseApis, eventEmitter, sessionStore, userId, deviceId)

Cryptography bits
Parameters:
Name Type Description
baseApis module:base-apis~MatrixBaseApis base matrix api interface
eventEmitter external:EventEmitter event source where we can register for event notifications
sessionStore module:store/session/webstorage~WebStorageSessionStore Store to be used for end-to-end crypto session data
userId string The user ID for the local user
deviceId string The identifier for this device.
Source:

Members

(static) DecryptionError

Source:
See:

Methods

(static) getOlmVersion() → {string}

Source:
Returns:
The version of Olm.
Type
string

_sendPingToDevice(userId, deviceIdnullable, roomId)

Send a "m.new_device" message to remind it that we exist and are a member of a room. This is rate limited to send a message at most once an hour per desination.
Parameters:
Name Type Attributes Description
userId string The ID of the user to ping.
deviceId string <nullable>
The ID of the device to ping. If null, all devices.
roomId string The ID of the room we want to remind them about.
Source:

_signObject(obj)

sign the given object with our ed25519 key
Parameters:
Name Type Description
obj Object Object to which we will add a 'signatures' property
Source:

decryptEvent(event) → {module:crypto.DecryptionResult}

Decrypt a received event
Parameters:
Name Type Description
event object raw event
Source:
Returns:
decryption result
Type
module:crypto.DecryptionResult

downloadKeys(userIds, forceDownload) → {Promise}

Download the keys for a list of users and stores the keys in the session store.
Parameters:
Name Type Description
userIds Array The users to fetch.
forceDownload bool Always download the keys even if cached.
Source:
Returns:
A promise which resolves to a map userId->deviceId->DeviceInfo.
Type
Promise

encryptEventIfNeeded(event, roomnullable) → (nullable) {module:client.Promise}

Encrypt an event according to the configuration of the room, if necessary.
Parameters:
Name Type Attributes Description
event module:models/event.MatrixEvent event to be sent
room module:models/room <nullable>
destination room. Null if the destination is not a room we have seen over the sync pipe.
Source:
Returns:
Promise which resolves when the event has been encrypted, or null if nothing was needed
Type
module:client.Promise

ensureOlmSessionsForUsers(users) → {module:client.Promise}

Try to make sure we have established olm sessions for the given users.
Parameters:
Name Type Description
users Array.<string> list of user ids
Source:
Returns:
resolves once the sessions are complete, to an Object mapping from userId to deviceId to module:crypto~OlmSessionResult
Type
module:client.Promise

getDeviceByIdentityKey(userId, algorithm, sender_key) → (nullable) {module:crypto/deviceinfo}

Find a device by curve25519 identity key
Parameters:
Name Type Description
userId string owner of the device
algorithm string encryption algorithm
sender_key string curve25519 key to match
Source:
Returns:
Type
module:crypto/deviceinfo

getDeviceEd25519Key() → {string}

Get the Ed25519 key for this device
Source:
Returns:
base64-encoded ed25519 key.
Type
string

getEventSenderDeviceInfo(event) → (nullable) {module:crypto/deviceinfo}

Get the device which sent an event
Parameters:
Name Type Description
event module:models/event.MatrixEvent event to be checked
Source:
Returns:
Type
module:crypto/deviceinfo

getOlmSessionsForUser(userId) → {Object.<string, {deviceIdKey: string, sessions: Array.<object>}>}

Get information on the active olm sessions with a user

Returns a map from device id to an object with keys 'deviceIdKey' (the device's curve25519 identity key) and 'sessions' (an array of objects in the same format as that returned by module:crypto/OlmDevice#getSessionInfoForDevice).

This method is provided for debugging purposes.

Parameters:
Name Type Description
userId string id of user to inspect
Source:
Returns:
Type
Object.<string, {deviceIdKey: string, sessions: Array.<object>}>

getStoredDevicesForUser(userId) → {Array.<module:crypto/deviceinfo>}

Get the stored device keys for a user id
Parameters:
Name Type Description
userId string the user to list keys for.
Source:
Returns:
list of devices
Type
Array.<module:crypto/deviceinfo>

isRoomEncrypted(roomId) → {bool}

Whether encryption is enabled for a room.
Parameters:
Name Type Description
roomId string the room id to query.
Source:
Returns:
whether encryption is enabled.
Type
bool

listDeviceKeys(userId) → {Array.<object>}

List the stored device keys for a user id
Parameters:
Name Type Description
userId string the user to list keys for.
Deprecated:
Source:
Returns:
list of devices with "id", "verified", "blocked", "key", and "display_name" parameters.
Type
Array.<object>

setDeviceVerification(userId, deviceId, verifiednullable, blockednullable)

Update the blocked/verified state of the given device
Parameters:
Name Type Attributes Description
userId string owner of the device
deviceId string unique identifier for the device
verified boolean <nullable>
whether to mark the device as verified. Null to leave unchanged.
blocked boolean <nullable>
whether to mark the device as blocked. Null to leave unchanged.
Source:

setRoomEncryption(roomId, config)

Configure a room to use encryption (ie, save a flag in the sessionstore).
Parameters:
Name Type Description
roomId string The room ID to enable encryption in.
config object The encryption config for the room.
Source:

uploadKeys(maxKeys) → {object}

Upload the device keys to the homeserver and ensure that the homeserver has enough one-time keys.
Parameters:
Name Type Description
maxKeys number The maximum number of keys to generate
Source:
Returns:
A promise that will resolve when the keys are uploaded.
Type
object

(inner) _verifySignature(olmDevice, obj, signingUserId, signingDeviceId, signingKey)

Verify the signature on an object
Parameters:
Name Type Description
olmDevice module:crypto/OlmDevice olm wrapper to use for verify op
obj Object object to check signature on. Note that this will be stripped of its 'signatures' and 'unsigned' properties.
signingUserId string ID of the user whose signature should be checked
signingDeviceId string ID of the device whose signature should be checked
signingKey string base64-ed ed25519 public key
Source:

Type Definitions

DecryptionResult

Type:
  • Object
Properties:
Name Type Description
payload Object decrypted payload (with properties 'type', 'content').
keysClaimed Object.<string, string> keys that the sender of the event claims ownership of: map from key type to base64-encoded key
keysProved Object.<string, string> keys that the sender of the event is known to have ownership of: map from key type to base64-encoded key
Source:

OlmSessionResult

Type:
  • Object
Properties:
Name Type Attributes Description
device module:crypto/deviceinfo device info
sessionId string <nullable>
base64 olm session id; null if no session could be established
Source: