Class CryptoService

End-to-end encryption of the client: owns the OlmMachine, decrypts syncs and encrypts outgoing events.

Inheritance
object
CryptoService
Implements
Inherited Members
Namespace: Uniform.Matrix.Client.Services
Assembly: Uniform.Matrix.Client.dll
Syntax
public sealed class CryptoService : IDisposable
Remarks

When the stored encryption state cannot be read, e.g. with another crypto.key, the client runs without encryption: encrypted messages stay unreadable and sending to encrypted rooms is refused.

Constructors

| Edit this page View Source

CryptoService(EfCryptoStore, AccountPaths, ILogger<CryptoService>)

Create the service; encryption starts with StartAsync(MatrixClient, CancellationToken).

Declaration
public CryptoService(EfCryptoStore store, AccountPaths paths, ILogger<CryptoService> logger)
Parameters
Type Name Description
EfCryptoStore store
AccountPaths paths
ILogger<CryptoService> logger

Properties

| Edit this page View Source

Available

Whether encryption works; false before StartAsync(MatrixClient, CancellationToken) or when the stored state cannot be read.

Declaration
public bool Available { get; }
Property Value
Type Description
bool
| Edit this page View Source

DeviceId

This device's ID, when available.

Declaration
public string? DeviceId { get; }
Property Value
Type Description
string
| Edit this page View Source

IdentityKeys

This device's identity keys, when available.

Declaration
public IdentityKeys? IdentityKeys { get; }
Property Value
Type Description
IdentityKeys
| Edit this page View Source

RoomEventSender

Send a room event, encrypted in encrypted rooms: the room, event type and content; set by the outbox, which in-room verification answers through.

Declaration
public Func<string, string, JsonObject, CancellationToken, Task>? RoomEventSender { get; set; }
Property Value
Type Description
Func<string, string, JsonObject, CancellationToken, Task>
| Edit this page View Source

UnavailableReason

Why encryption is not available, or null.

Declaration
public string? UnavailableReason { get; }
Property Value
Type Description
string
| Edit this page View Source

Verifications

Verifications in progress.

Declaration
public IReadOnlyList<Verification> Verifications { get; }
Property Value
Type Description
IReadOnlyList<Verification>
| Edit this page View Source

WhenStarted

Completes once StartAsync(MatrixClient, CancellationToken) has finished, with or without encryption; check Available after it.

Declaration
public Task WhenStarted { get; }
Property Value
Type Description
Task

Methods

| Edit this page View Source

AcceptVerificationAsync(Verification, CancellationToken)

Accept an incoming verification request.

Declaration
public Task AcceptVerificationAsync(Verification verification, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Verification verification
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

CancelVerificationAsync(Verification, string, CancellationToken)

Cancel a verification; m.mismatched_sas when the emoji differ.

Declaration
public Task CancelVerificationAsync(Verification verification, string code = "m.user", CancellationToken cancellationToken = default)
Parameters
Type Name Description
Verification verification
string code
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

ConfirmVerificationAsync(Verification, CancellationToken)

Confirm that the emoji match.

Declaration
public Task ConfirmVerificationAsync(Verification verification, CancellationToken cancellationToken = default)
Parameters
Type Name Description
Verification verification
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

DecryptAsync(string, ClientEvent, CancellationToken)

Decrypt one event; return it unchanged when not encrypted or not decryptable.

Declaration
public Task<ClientEvent> DecryptAsync(string roomId, ClientEvent clientEvent, CancellationToken cancellationToken)
Parameters
Type Name Description
string roomId
ClientEvent clientEvent
CancellationToken cancellationToken
Returns
Type Description
Task<ClientEvent>
| Edit this page View Source

DecryptSyncAsync(SyncResponse, CancellationToken)

Process the encryption parts of sync and return it with Megolm timeline events decrypted where keys are known.

Declaration
public Task<SyncResponse> DecryptSyncAsync(SyncResponse sync, CancellationToken cancellationToken)
Parameters
Type Name Description
SyncResponse sync
CancellationToken cancellationToken
Returns
Type Description
Task<SyncResponse>
| Edit this page View Source

Dispose()

Wipe key material in memory.

Declaration
public void Dispose()
| Edit this page View Source

EncryptAsync(string, string, JsonElement, IReadOnlyCollection<string>, EncryptionContent?, CancellationToken)

Encrypt an event for an encrypted room; throw InvalidOperationException when encryption is unavailable, so nothing is sent in the clear.

Declaration
public Task<EncryptedContent> EncryptAsync(string roomId, string eventType, JsonElement content, IReadOnlyCollection<string> memberIds, EncryptionContent? settings, CancellationToken cancellationToken)
Parameters
Type Name Description
string roomId

Encrypted room.
string eventType

Type of the event to encrypt.
JsonElement content

Event content.
IReadOnlyCollection<string> memberIds

Joined and invited members, whose devices get the room key.
EncryptionContent settings

Room's m.room.encryption content.
CancellationToken cancellationToken

Cancellation token.
Returns
Type Description
Task<EncryptedContent>
| Edit this page View Source

FormatFingerprint(string)

Format an Ed25519 key in groups of four, as clients show fingerprints for comparison.

Declaration
public static string FormatFingerprint(string key)
Parameters
Type Name Description
string key
Returns
Type Description
string
| Edit this page View Source

GetDeviceTrust(string, string)

Return the trust of a known device, or null when the device is unknown or encryption is off.

Declaration
public DeviceTrust? GetDeviceTrust(string userId, string deviceId)
Parameters
Type Name Description
string userId
string deviceId
Returns
Type Description
DeviceTrust?
| Edit this page View Source

GetDevices(string)

Return the known devices of userId; call TrackUserAsync(string, CancellationToken) first.

Declaration
public IReadOnlyList<DeviceInfo> GetDevices(string userId)
Parameters
Type Name Description
string userId
Returns
Type Description
IReadOnlyList<DeviceInfo>
| Edit this page View Source

GetSecurityStatusAsync(CancellationToken)

Report cross-signing, backup and secret storage state of the account.

Declaration
public Task<SecurityStatus> GetSecurityStatusAsync(CancellationToken cancellationToken = default)
Parameters
Type Name Description
CancellationToken cancellationToken
Returns
Type Description
Task<SecurityStatus>
| Edit this page View Source

GetSignedDevices(string)

Return the user's devices signed by their current self-signing key, which can vouch for others of the account, whether or not this device trusts the identity; none when encryption is off.

Declaration
public IReadOnlyList<DeviceInfo> GetSignedDevices(string userId)
Parameters
Type Name Description
string userId
Returns
Type Description
IReadOnlyList<DeviceInfo>
| Edit this page View Source

IsUserVerified(string)

Return whether this device has verified userId: their cross-signing identity is trusted, or, without one, every device of theirs known here is verified; false when encryption is off.

Declaration
public bool IsUserVerified(string userId)
Parameters
Type Name Description
string userId
Returns
Type Description
bool
| Edit this page View Source

RecoverAsync(string, CancellationToken)

Restore keys from secret storage with the recovery key and import the backup. See RecoverAsync(string, CancellationToken).

Declaration
public Task<RecoveryResult> RecoverAsync(string recoveryKey, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string recoveryKey
CancellationToken cancellationToken
Returns
Type Description
Task<RecoveryResult>
| Edit this page View Source

RequestVerificationAsync(string, string?, CancellationToken)

Start verifying a device of userId, or all of them.

Declaration
public Task<Verification> RequestVerificationAsync(string userId, string? deviceId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
string deviceId
CancellationToken cancellationToken
Returns
Type Description
Task<Verification>
| Edit this page View Source

RequestVerificationInRoomAsync(string, string, Func<JsonObject, CancellationToken, Task<string>>, CancellationToken)

Ask another user to verify in a room, their direct chat, with a request message that sendRequest sends and returns the event ID of.

Declaration
public Task<Verification> RequestVerificationInRoomAsync(string roomId, string userId, Func<JsonObject, CancellationToken, Task<string>> sendRequest, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string roomId
string userId
Func<JsonObject, CancellationToken, Task<string>> sendRequest
CancellationToken cancellationToken
Returns
Type Description
Task<Verification>
| Edit this page View Source

SendEncryptedToDevicesAsync(string, JsonObject, IReadOnlyCollection<(string UserId, string DeviceId)>, CancellationToken)

Send a to-device event to each of devices, encrypted over Olm; return how many it went to, none without encryption.

Declaration
public Task<int> SendEncryptedToDevicesAsync(string type, JsonObject content, IReadOnlyCollection<(string UserId, string DeviceId)> devices, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string type
JsonObject content
IReadOnlyCollection<(string UserId, string DeviceId)> devices
CancellationToken cancellationToken
Returns
Type Description
Task<int>
| Edit this page View Source

SetUpRecoveryAsync(string?, CancellationToken)

Set up cross-signing, key backup and secret storage; return the recovery key. See SetUpRecoveryAsync(string?, CancellationToken).

Declaration
public Task<string> SetUpRecoveryAsync(string? password, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string password
CancellationToken cancellationToken
Returns
Type Description
Task<string>
| Edit this page View Source

StartAsync(MatrixClient, CancellationToken)

Load or create the device's encryption account and upload its keys; log and continues without encryption on failure.

Declaration
public Task StartAsync(MatrixClient client, CancellationToken cancellationToken)
Parameters
Type Name Description
MatrixClient client
CancellationToken cancellationToken
Returns
Type Description
Task
| Edit this page View Source

TakeReceivedKeys()

Return room keys received since the last call, to decrypt stored events that were waiting for them.

Declaration
public IReadOnlyList<(string RoomId, string SessionId)> TakeReceivedKeys()
Returns
Type Description
IReadOnlyList<(string Type, string StateKey)>
| Edit this page View Source

TrackUserAsync(string, CancellationToken)

Fetch the devices of userId, so their trust is known.

Declaration
public Task TrackUserAsync(string userId, CancellationToken cancellationToken = default)
Parameters
Type Name Description
string userId
CancellationToken cancellationToken
Returns
Type Description
Task

Events

| Edit this page View Source

ToDeviceReceived

Raised for each to-device event that came encrypted over Olm, decrypted, e.g. MatrixRTC's media keys; on the sync loop, so a handler should be quick.

Declaration
public event Action<DecryptedToDeviceEvent>? ToDeviceReceived
Event Type
Type Description
Action<DecryptedToDeviceEvent>
| Edit this page View Source

VerificationChanged

Raised when a verification starts, changes or ends; raised off the UI thread.

Declaration
public event Action<Verification>? VerificationChanged
Event Type
Type Description
Action<Verification>
| Edit this page View Source

VerificationIgnored

Raised when a verification message is dropped, with its sender, device and why, see VerificationIgnored.

Declaration
public event Action<string, string?, string>? VerificationIgnored
Event Type
Type Description
Action<string, string, string>

Implements