It's not possible to construct an OlmMachine with its constructor because building an OlmMachine is asynchronous. Please use the finalize method.

The unique device ID that identifies this OlmMachine.

Get the public parts of our Olm identity keys.

The unique user ID that owns this OlmMachine instance.

Encrypt a batch of room keys and return a request that needs to be sent out to backup the room keys.

Create a new cross signing identity and get the upload request to push the new public keys to the server.

Warning: This will delete any existing cross signing keys that might exist on the server and thus will reset the trust between all the devices.

Uploading these keys will require user interactive auth.

Arguments

• reset, whether the method should create a new identity or use the existing one during the request. If set to true, the request will attempt to upload a new identity. If set to false, the request will attempt to upload the existing identity. Since the uploading process requires user interactive authentication, which involves sending out the same request multiple times, setting this argument to false enables you to reuse the same request.

Shut down the OlmMachine.

The OlmMachine cannot be used after this method has been called, otherwise it will panic.

All associated resources will be closed too, like the crypto storage connections.

Safety

The caller is responsible to not use any objects that came from this OlmMachine after this close method has been called.

Get the status of the private cross signing keys.

This can be used to check which private cross signing keys we have stored locally.

Decrypt an event from a room timeline.

Arguments

• event, the event that should be decrypted.
• room_id, the ID of the room where the event was sent to.

Disable and reset our backup state.

This will remove any pending backup request, remove the backup key and reset the backup state of each room key we have.

Activate the given backup key to be used with the given backup version.

Warning: The caller needs to make sure that the given BackupKey is trusted, otherwise we might be encrypting room keys that a malicious party could decrypt.

The [OlmMachine::verify_backup] method can be used to do so.

Encrypt a JSON-encoded content for the given room.

Arguments

• room_id, the ID of the room for which the message should be encrypted.
• event_type, the plaintext type of the event.
• content, the JSON-encoded content of the message that should be encrypted.

Export room keys in unencrypted format for a given session_id. This currently exports a json blob.

Get the backup keys we have saved in our store.

Get the a key claiming request for the user/device pairs that we are missing Olm sessions for.

Returns null if no key claiming request needs to be sent out.

Sessions need to be established between devices so group sessions for a room can be shared with them.

This should be called every time a group session needs to be shared as well as between sync calls. After a sync some devices may request room keys without us having a valid Olm session with them, making it impossible to server the room key request, thus it’s necessary to check for missing sessions between sync as well.

Note: Care should be taken that only one such request at a time is in flight, e.g. using a lock.

The response of a successful key claiming requests needs to be passed to the OlmMachine with the mark_request_as_sent.

Arguments

• users, the list of users that we should check if we lack a session with one of their devices. This can be an empty array or null when calling this method between sync requests.

Are we able to encrypt room keys.

This returns true if we have an active BackupKey and backup version registered with the state machine.

Mark the request with the given request ID as sent.

Arguments

• request_id, the unique ID of the request that was sent out. This is needed to couple the response with the now sent out request.
• request_type, the request type associated to the request ID.
• response, the response that was received from the server after the outgoing request was sent out.

Get the outgoing requests that need to be sent out.

This returns a list of KeysUploadRequest, or KeysQueryRequest, or KeysClaimRequest, or ToDeviceRequest, or SignatureUploadRequest, or RoomMessageRequest. Those requests need to be sent out to the server and the responses need to be passed back to the state machine using mark_request_as_sent.

Handle a to-device and one-time key counts from a sync response.

This will decrypt and handle to-device events returning the decrypted versions of them, as a JSON-encoded string.

To decrypt an event from the room timeline, please use decrypt_room_event.

Arguments

• to_device_events, the to-device events of the current sync response.
• changed_devices, the list of devices that changed in this sync response.
• one_time_keys_count, the current one-time keys counts that the sync response returned.

Get the number of backed up room keys and the total number of room keys.

Store the backup decryption key in the crypto store.

This is useful if the client wants to support gossiping of the backup key.

Get to-device requests to share a room key with users in a room.

Arguments

• room_id, the room ID of the room where the room key will be used.
• users, the list of users that should receive the room key.
• encryption_settings, the encryption settings.

Sign the given message using our device key and if available cross-signing master key.

Update the tracked users.

This will mark users that weren’t seen before for a key query and tracking.

If the user is already known to the Olm machine it will not be considered for a key query.

Arguments

• users, an array over user IDs that should be marked for tracking.

Check if the given backup has been verified by us or by another of our devices that we trust.

The backup_info should be a stringified JSON object with the following format:

{
    "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
    "auth_data": {
        "public_key":"XjhWTCjW7l59pbfx9tlCBQolfnIQWARoKOzjTOPSlWM",
        "signatures": {}
    }
}
Copy

Create a new OlmMachine asynchronously.

The persistence of the encryption keys and all the inner objects are controlled by the store_path argument.

Arguments

• user_id, the unique ID of the user that owns this machine.
• device_id, the unique id of the device that owns this machine.
• store_path, the path to a directory where the state of the machine should be persisted; if not set, the created machine will keep the encryption keys only in memory, and once the object is dropped, the keys will be lost.
• store_passphrase, the passphrase that should be used to encrypt the data at rest in the store. Warning, if no passphrase is given, the store and all its data will remain unencrypted. This argument is ignored if store_path is not set.