Class: module:crypto/OlmDevice

module:crypto/OlmDevice

new module:crypto/OlmDevice(sessionStore)

Manages the olm cryptography functions. Each OlmDevice has a single OlmAccount and a number of OlmSessions. Accounts and sessions are kept pickled in a sessionStore.
Parameters:
Name Type Description
sessionStore Object A store to be used for data in end-to-end crypto
Properties:
Name Type Description
deviceCurve25519Key string Curve25519 key for the account
deviceEd25519Key string Ed25519 key for the account
Source:

Methods

(static) getOlmVersion() → {array}

Source:
Returns:
The version of Olm.
Type
array

addInboundGroupSession(roomId, senderKey, sessionId, sessionKey, keysClaimed)

Add an inbound group session to the session store
Parameters:
Name Type Description
roomId string room in which this session will be used
senderKey string base64-encoded curve25519 key of the sender
sessionId string session identifier
sessionKey string base64-encoded secret key
keysClaimed Object.<string, string> Other keys the sender claims.
Source:

createInboundSession(theirDeviceIdentityKey, message_type, ciphertext) → {Object}

Generate a new inbound session, given an incoming message
Parameters:
Name Type Description
theirDeviceIdentityKey string remote user's Curve25519 identity key
message_type number message_type field from the received message (must be 0)
ciphertext string base64-encoded body from the received message
Source:
Returns:
decrypted payload, and session id of new session
Type
Object

createOutboundGroupSession() → {string}

Generate a new outbound group session
Source:
Returns:
sessionId for the outbound session.
Type
string

createOutboundSession(theirIdentityKey, theirOneTimeKey) → {string}

Generate a new outbound session The new session will be stored in the sessionStore.
Parameters:
Name Type Description
theirIdentityKey string remote user's Curve25519 identity key
theirOneTimeKey string remote user's one-time Curve25519 key
Source:
Returns:
sessionId for the outbound session.
Type
string

decryptGroupMessage(roomId, senderKey, sessionId, body) → {null|Object}

Decrypt a received message with an inbound group session
Parameters:
Name Type Description
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
Source:
Returns:
  • the sessionId is unknown
    Type
    null
  • result
    Type
    Object

decryptMessage(theirDeviceIdentityKey, sessionId, message_type, ciphertext) → {string}

Decrypt an incoming message using an existing session
Parameters:
Name Type Description
theirDeviceIdentityKey string Curve25519 identity key for the remote device
sessionId string the id of the active session
message_type number message_type field from the received message
ciphertext string base64-encoded body from the received message
Source:
Returns:
decrypted payload.
Type
string

encryptGroupMessage(sessionId, payloadString) → {string}

Encrypt an outgoing message with an outbound group session
Parameters:
Name Type Description
sessionId string the id of the outboundgroupsession
payloadString string payload to be encrypted and sent
Source:
Returns:
ciphertext
Type
string

encryptMessage(theirDeviceIdentityKey, sessionId, payloadString) → {string}

Encrypt an outgoing message using an existing session
Parameters:
Name Type Description
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
Source:
Returns:
ciphertext
Type
string

generateOneTimeKeys(numKeys)

Generate some new one-time keys
Parameters:
Name Type Description
numKeys number number of keys to generate
Source:

getOneTimeKeys() → {object}

Get the current (unused, unpublished) one-time keys for this account.
Source:
Returns:
one time keys; an object with the single property curve25519, which is itself an object mapping key id to Curve25519 key.
Type
object

getOutboundGroupSessionKey(sessionId) → {Object}

Get the session keys for an outbound group session
Parameters:
Name Type Description
sessionId string the id of the outbound group session
Source:
Returns:
current chain index, and base64-encoded secret key.
Type
Object

getSessionIdForDevice(theirDeviceIdentityKey) → (nullable) {string}

Get the right olm session id for encrypting messages to the given identity key
Parameters:
Name Type Description
theirDeviceIdentityKey string Curve25519 identity key for the remote device
Source:
Returns:
session id, or null if no established session
Type
string

getSessionIdsForDevice(theirDeviceIdentityKey) → {Array.<string>}

Get a list of known session IDs for the given device
Parameters:
Name Type Description
theirDeviceIdentityKey string Curve25519 identity key for the remote device
Source:
Returns:
a list of known session ids for the device
Type
Array.<string>

getSessionInfoForDevice(deviceIdentityKey) → {Array.<{sessionId: string, hasReceivedMessage: Boolean}>}

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:
Name Type Description
deviceIdentityKey string Curve25519 identity key for the device
Source:
Returns:
Type
Array.<{sessionId: string, hasReceivedMessage: Boolean}>

markKeysAsPublished()

Marks all of the one-time keys as published.
Source:

matchesSession(theirDeviceIdentityKey, sessionId, message_type, ciphertext) → {boolean}

Determine if an incoming messages is a prekey message matching an existing session
Parameters:
Name Type Description
theirDeviceIdentityKey string Curve25519 identity key for the remote device
sessionId string the id of the active session
message_type number message_type field from the received message
ciphertext string base64-encoded body from the received message
Source:
Returns:
true if the received message is a prekey message which matches the given session.
Type
boolean

maxNumberOfOneTimeKeys() → {number}

Get the maximum number of one-time keys we can store.
Source:
Returns:
number of keys
Type
number

sign(message) → {string}

Signs a message with the ed25519 key for this account.
Parameters:
Name Type Description
message string message to be signed
Source:
Returns:
base64-encoded signature
Type
string

verifySignature(key, message, signature)

Verify an ed25519 signature.
Parameters:
Name Type Description
key string ed25519 key
message string message which was signed
signature string base64-encoded signature to be checked
Source: