Interface CryptoApi

globalBlacklistUnverifiedDevices

bootstrapCrossSigning

• bootstrapCrossSigning(opts: BootstrapCrossSigningOpts): Promise<void>

• Bootstrap cross-signing by creating keys if needed.

  If everything is already set up, then no changes are made, so this is safe to run to ensure cross-signing is ready for use.

  This function:

  • creates new cross-signing keys if they are not found locally cached nor in secret storage (if it has been set up)
  • publishes the public keys to the server if they are not already published
  • stores the private keys in secret storage if secret storage is set up.

  Parameters

  • opts: BootstrapCrossSigningOpts

    options object

  Returns Promise<void>

bootstrapSecretStorage

• bootstrapSecretStorage(opts: CreateSecretStorageOpts): Promise<void>

• Bootstrap the secret storage by creating a new secret storage key, add it in the secret storage and store the cross signing keys in the secret storage.

  • Generate a new key GeneratedSecretStorageKey with createSecretStorageKey. Only if setupNewSecretStorage is set or if there is no AES key in the secret storage
  • Store this key in the secret storage and set it as the default key.
  • Call cryptoCallbacks.cacheSecretStorageKey if provided.
  • Store the cross signing keys in the secret storage if
    • the cross signing is ready
    • a new key was created during the previous step
    • or the secret storage already contains the cross signing keys

  Parameters

  • opts: CreateSecretStorageOpts

    Options object.

  Returns Promise<void>

checkKeyBackupAndEnable

• checkKeyBackupAndEnable(): Promise<null | KeyBackupCheck>

• Force a re-check of the key backup and enable/disable it as appropriate.

  Fetches the current backup information from the server. If there is a backup, and it is trusted, starts backing up to it; otherwise, disables backups.

  Returns Promise<null | KeyBackupCheck>

  null if there is no backup on the server. Otherwise, data on the backup as returned by the server, and trust information (as returned by isKeyBackupTrusted).

createRecoveryKeyFromPassphrase

• createRecoveryKeyFromPassphrase(
      password?: string,
  ): Promise<GeneratedSecretStorageKey>

• Create a recovery key (ie, a key suitable for use with server-side secret storage).

  The key can either be based on a user-supplied passphrase, or just created randomly.

  Parameters

  • Optionalpassword: string

    Optional passphrase string to use to derive the key, which can later be entered by the user as an alternative to entering the recovery key itself. If omitted, a key is generated randomly.

  Returns Promise<GeneratedSecretStorageKey>

  Object including recovery key and server upload parameters. The private key should be disposed of after displaying to the use.

crossSignDevice

• crossSignDevice(deviceId: string): Promise<void>

• Cross-sign one of our own devices.

  This will create a signature for the device using our self-signing key, and publish that signature. Cross-signing a device indicates, to our other devices and to other users, that we have verified that it really belongs to us.

  Requires that cross-signing has been set up on this device (normally by calling bootstrapCrossSigning).

  Note: Do not call this unless you have verified, somehow, that the device is genuine!

  Parameters

  • deviceId: string

    ID of the device to be signed.

  Returns Promise<void>

deleteKeyBackupVersion

• deleteKeyBackupVersion(version: string): Promise<void>

• Deletes the given key backup.

  Parameters

  • version: string

    The backup version to delete.

  Returns Promise<void>

encryptToDeviceMessages

• encryptToDeviceMessages(
      eventType: string,
      devices: { deviceId: string; userId: string }[],
      payload: ToDevicePayload,
  ): Promise<ToDeviceBatch>

• Encrypts a given payload object via Olm to-device messages to a given set of devices.

  Parameters

  • eventType: string

    the type of the event to send.
  • devices: { deviceId: string; userId: string }[]

    an array of devices to encrypt the payload for.
  • payload: ToDevicePayload

    the payload to encrypt.

  Returns Promise<ToDeviceBatch>

  the batch of encrypted payloads which can then be sent via matrix.MatrixClient#queueToDevice.

exportRoomKeys

• exportRoomKeys(): Promise<IMegolmSessionData[]>

• Get a list containing all of the room keys

  This should be encrypted before returning it to the user.

  Returns Promise<IMegolmSessionData[]>

  a promise which resolves to a list of session export objects

exportRoomKeysAsJson

• exportRoomKeysAsJson(): Promise<string>

• Get a JSON list containing all of the room keys

  This should be encrypted before returning it to the user.

  Returns Promise<string>

  a promise which resolves to a JSON string encoding a list of session export objects, each of which is an IMegolmSessionData

OptionalexportSecretsBundle

• exportSecretsBundle(): Promise<
      {
          backup?: { algorithm: string; backup_version: string; key: string };
          cross_signing: {
              master_key: string;
              self_signing_key: string;
              user_signing_key: string;
          };
      },
  >

• Export secrets bundle for transmitting to another device as part of OIDC QR login

  Returns Promise<
      {
          backup?: { algorithm: string; backup_version: string; key: string };
          cross_signing: {
              master_key: string;
              self_signing_key: string;
              user_signing_key: string;
          };
      },
  >

findVerificationRequestDMInProgress

• findVerificationRequestDMInProgress(
      roomId: string,
  ): undefined | VerificationRequest

• Finds a DM verification request that is already in progress for the given room id

  Parameters

  • roomId: string

    the room to use for verification

  Returns undefined | VerificationRequest

  the VerificationRequest that is in progress, if any

  Deprecated

  prefer userId parameter variant.

• findVerificationRequestDMInProgress(
      roomId: string,
      userId?: string,
  ): undefined | VerificationRequest

• Finds a DM verification request that is already in progress for the given room and user.

  Parameters

  • roomId: string

    the room to use for verification.
  • OptionaluserId: string

    search for a verification request for the given user.

  Returns undefined | VerificationRequest

  the VerificationRequest that is in progress, if any.

forceDiscardSession

• forceDiscardSession(roomId: string): Promise<void>

• Discard any existing megolm session for the given room.

  This will ensure that a new session is created on the next call to prepareToEncrypt, or the next time a message is sent.

  This should not normally be necessary: it should only be used as a debugging tool if there has been a problem with encryption.

  Parameters

  • roomId: string

    the room to discard sessions for

  Returns Promise<void>

getActiveSessionBackupVersion

• getActiveSessionBackupVersion(): Promise<null | string>

• Get the current status of key backup.

  Returns Promise<null | string>

  If automatic key backups are enabled, the version of the active backup. Otherwise, null.

getCrossSigningKeyId

• getCrossSigningKeyId(type?: CrossSigningKey): Promise<null | string>

• Get the ID of one of the user's cross-signing keys, if both private and matching public parts of that key are available (ie. cached in the local crypto store).

  The public part may not be available if a /keys/query request has not yet been performed, or if the device that created the keys failed to publish them.

  If either part of the keypair is not available, this will return null.

  Parameters

  • Optionaltype: CrossSigningKey

    The type of key to get the ID of. One of CrossSigningKey.Master, CrossSigningKey.SelfSigning, or CrossSigningKey.UserSigning. Defaults to CrossSigningKey.Master.

  Returns Promise<null | string>

  If cross-signing has been initialised on this device, the ID of the given key. Otherwise, null

getCrossSigningStatus

• getCrossSigningStatus(): Promise<CrossSigningStatus>

• Get the status of our cross-signing keys.

  Returns Promise<CrossSigningStatus>

  The current status of cross-signing keys: whether we have public and private keys cached locally, and whether the private keys are in secret storage.

  Throws

  May throw matrix.ClientStoppedError if the MatrixClient is stopped before or during the call.

getDeviceVerificationStatus

• getDeviceVerificationStatus(
      userId: string,
      deviceId: string,
  ): Promise<null | DeviceVerificationStatus>

• Get the verification status of a given device.

  Parameters

  • userId: string

    The ID of the user whose device is to be checked.
  • deviceId: string

    The ID of the device to check

  Returns Promise<null | DeviceVerificationStatus>

  null if the device is unknown, or has not published any encryption keys (implying it does not support encryption); otherwise the verification status of the device.

getEncryptionInfoForEvent

• getEncryptionInfoForEvent(
      event: MatrixEvent,
  ): Promise<null | EventEncryptionInfo>

• Get information about the encryption of the given event.

  Parameters

  • event: MatrixEvent

    the event to get information for

  Returns Promise<null | EventEncryptionInfo>

  null if the event is not encrypted, or has not (yet) been successfully decrypted. Otherwise, an object with information about the encryption of the event.

getKeyBackupInfo

• getKeyBackupInfo(): Promise<null | KeyBackupInfo>

• Return the details of the latest backup on the server, when we last checked.

  This normally returns a cached value, but if we haven't yet made a request to the server, it will fire one off. It will always return the details of the active backup if key backup is enabled.

  Return null if there is no backup.

  Returns Promise<null | KeyBackupInfo>

  the key backup information

getOwnDeviceKeys

• getOwnDeviceKeys(): Promise<OwnDeviceKeys>

• Get the public part of the device keys for the current device.

  Returns Promise<OwnDeviceKeys>

  The public device keys.

getSessionBackupPrivateKey

• getSessionBackupPrivateKey(): Promise<null | Uint8Array<ArrayBufferLike>>

• Fetch the backup decryption key we have saved in our store.

  This can be used for gossiping the key to other devices.

  Returns Promise<null | Uint8Array<ArrayBufferLike>>

  the key, if any, or null

getTrustCrossSignedDevices

• getTrustCrossSignedDevices(): boolean

• Return whether we trust other user's signatures of their devices.

  Returns boolean

  true if we trust cross-signed devices, otherwise false.

  See

  CryptoApi.setTrustCrossSignedDevices

getUserDeviceInfo

• getUserDeviceInfo(
      userIds: string[],
      downloadUncached?: boolean,
  ): Promise<DeviceMap>

• Get the device information for the given list of users.

  For any users whose device lists are cached (due to sharing an encrypted room with the user), the cached device data is returned.

  If there are uncached users, and the downloadUncached parameter is set to true, a /keys/query request is made to the server to retrieve these devices.

  Parameters

  • userIds: string[]

    The users to fetch.
  • OptionaldownloadUncached: boolean

    If true, download the device list for users whose device list we are not currently tracking. Defaults to false, in which case such users will not appear at all in the result map.

  Returns Promise<DeviceMap>

  A map {@link DeviceMap}.

getUserVerificationStatus

• getUserVerificationStatus(userId: string): Promise<UserVerificationStatus>

• Get the verification status of a given user.

  Parameters

  • userId: string

    The ID of the user to check.

  Returns Promise<UserVerificationStatus>

getVerificationRequestsToDeviceInProgress

• getVerificationRequestsToDeviceInProgress(userId: string): VerificationRequest[]

• Returns to-device verification requests that are already in progress for the given user id.

  Parameters

  • userId: string

    the ID of the user to query

  Returns VerificationRequest[]

  the VerificationRequests that are in progress

getVersion

• getVersion(): string

• Return the current version of the crypto module. For example: Rust SDK ${versions.matrix_sdk_crypto} (${versions.git_sha}), Vodozemac ${versions.vodozemac}.

  Returns string

  the formatted version

importRoomKeys

• importRoomKeys(
      keys: IMegolmSessionData[],
      opts?: ImportRoomKeysOpts,
  ): Promise<void>

• Import a list of room keys previously exported by exportRoomKeys

  Parameters

  • keys: IMegolmSessionData[]

    a list of session export objects
  • Optionalopts: ImportRoomKeysOpts

    options object

  Returns Promise<void>

  a promise which resolves once the keys have been imported

importRoomKeysAsJson

• importRoomKeysAsJson(keys: string, opts?: ImportRoomKeysOpts): Promise<void>

• Import a JSON string encoding a list of room keys previously exported by exportRoomKeysAsJson

  Parameters

  • keys: string

    a JSON string encoding a list of session export objects, each of which is an IMegolmSessionData
  • Optionalopts: ImportRoomKeysOpts

    options object

  Returns Promise<void>

  a promise which resolves once the keys have been imported

OptionalimportSecretsBundle

• importSecretsBundle(
      secrets: {
          backup?: { algorithm: string; backup_version: string; key: string };
          cross_signing: {
              master_key: string;
              self_signing_key: string;
              user_signing_key: string;
          };
      },
  ): Promise<void>

• Import secrets bundle transmitted from another device.

  Parameters

  • secrets: {
        backup?: { algorithm: string; backup_version: string; key: string };
        cross_signing: {
            master_key: string;
            self_signing_key: string;
            user_signing_key: string;
        };
    }

    The secrets bundle received from the other device

  Returns Promise<void>

isCrossSigningReady

• isCrossSigningReady(): Promise<boolean>

• Checks whether cross signing:

  • is enabled on this account and trusted by this device
  • has private keys either cached locally or stored in secret storage

  If this function returns false, bootstrapCrossSigning() can be used to fix things such that it returns true. That is to say, after bootstrapCrossSigning() completes successfully, this function should return true.

  Returns Promise<boolean>

  True if cross-signing is ready to be used on this device

  Throws

  May throw matrix.ClientStoppedError if the MatrixClient is stopped before or during the call.

isDehydrationSupported

• isDehydrationSupported(): Promise<boolean>

• Returns whether MSC3814 dehydrated devices are supported by the crypto backend and by the server.

  This should be called before calling startDehydration, and if this returns false, startDehydration should not be called.

  Returns Promise<boolean>

isEncryptionEnabledInRoom

• isEncryptionEnabledInRoom(roomId: string): Promise<boolean>

• Check if we believe the given room to be encrypted.

  This method returns true if the room has been configured with encryption. The setting is persistent, so that even if the encryption event is removed from the room state, it still returns true. This helps to guard against a downgrade attack wherein a server admin attempts to remove encryption.

  Parameters

  • roomId: string

  Returns Promise<boolean>

  true if the room with the supplied ID is encrypted. false if the room is not encrypted, or is unknown to us.

isKeyBackupTrusted

• isKeyBackupTrusted(info: KeyBackupInfo): Promise<BackupTrustInfo>

• Determine if a key backup can be trusted.

  Parameters

  • info: KeyBackupInfo

    key backup info dict from matrix.MatrixClient.getKeyBackupVersion.

  Returns Promise<BackupTrustInfo>

isSecretStorageReady

• isSecretStorageReady(): Promise<boolean>

• Checks whether secret storage:

  • is enabled on this account
  • is storing cross-signing private keys
  • is storing session backup key (if enabled)

  If this function returns false, bootstrapSecretStorage() can be used to fix things such that it returns true. That is to say, after bootstrapSecretStorage() completes successfully, this function should return true.

  Returns Promise<boolean>

  True if secret storage is ready to be used on this device

loadSessionBackupPrivateKeyFromSecretStorage

• loadSessionBackupPrivateKeyFromSecretStorage(): Promise<void>

• Attempt to fetch the backup decryption key from secret storage.

  If the key is found in secret storage, checks it against the latest backup on the server; if they match, stores the key in the crypto store by calling storeSessionBackupPrivateKey, which enables automatic restore of individual keys when an Unable-to-decrypt error is encountered.

  If we are unable to fetch the key from secret storage, there is no backup on the server, or the key does not match, throws an exception.

  Returns Promise<void>

pinCurrentUserIdentity

• pinCurrentUserIdentity(userId: string): Promise<void>

• "Pin" the current identity of the given user, accepting it as genuine.

  This is useful if the user has changed identity since we first saw them (leading to UserVerificationStatus.needsUserApproval), and we are now accepting their new identity.

  Throws an error if called on our own user ID, or on a user ID that we don't have an identity for.

  Parameters

  • userId: string

  Returns Promise<void>

prepareToEncrypt

• prepareToEncrypt(room: Room): void

• Perform any background tasks that can be done before a message is ready to send, in order to speed up sending of the message.

  Parameters

  • room: Room

    the room the event is in

  Returns void

requestDeviceVerification

• requestDeviceVerification(
      userId: string,
      deviceId: string,
  ): Promise<VerificationRequest>

• Request an interactive verification with the given device.

  This is normally used on one of our own devices, when the current device is already cross-signed, and we want to validate another device.

  If a verification for this user/device is already in flight, returns it. Otherwise, initiates a new one.

  To control the methods offered, set matrix.ICreateClientOpts.verificationMethods when creating the MatrixClient.

  Parameters

  • userId: string

    ID of the owner of the device to verify
  • deviceId: string

    ID of the device to verify

  Returns Promise<VerificationRequest>

  a VerificationRequest when the request has been sent to the other party.

requestOwnUserVerification

• requestOwnUserVerification(): Promise<VerificationRequest>

• Send a verification request to our other devices.

  This is normally used when the current device is new, and we want to ask another of our devices to cross-sign.

  If an all-devices verification is already in flight, returns it. Otherwise, initiates a new one.

  To control the methods offered, set matrix.ICreateClientOpts.verificationMethods when creating the MatrixClient.

  Returns Promise<VerificationRequest>

  a VerificationRequest when the request has been sent to the other party.

requestVerificationDM

• requestVerificationDM(
      userId: string,
      roomId: string,
  ): Promise<VerificationRequest>

• Request a key verification from another user, using a DM.

  Parameters

  • userId: string

    the user to request verification with.
  • roomId: string

    the room to use for verification.

  Returns Promise<VerificationRequest>

  resolves to a VerificationRequest when the request has been sent to the other party.

resetKeyBackup

• resetKeyBackup(): Promise<void>

• Creates a new key backup version.

  If there are existing backups they will be replaced.

  The decryption key will be saved in Secret Storage (the matrix.SecretStorage.SecretStorageCallbacks.getSecretStorageKey Crypto callback will be called) and the backup engine will be started.

  Returns Promise<void>

restoreKeyBackup

• restoreKeyBackup(opts?: KeyBackupRestoreOpts): Promise<KeyBackupRestoreResult>

• Download and restore the full key backup from the homeserver.

  Before calling this method, a decryption key, and the backup version to restore, must have been saved in the crypto store. This happens in one of the following ways:

  • When a new backup version is created with CryptoApi.resetKeyBackup, a new key is created and cached.
  • The key can be loaded from secret storage with CryptoApi.loadSessionBackupPrivateKeyFromSecretStorage.
  • The key can be received from another device via secret sharing, typically as part of the interactive verification flow.
  • The key and backup version can also be set explicitly via CryptoApi.storeSessionBackupPrivateKey, though this is not expected to be a common operation.

  Warning: the full key backup may be quite large, so this operation may take several hours to complete. Use of KeyBackupRestoreOpts.progressCallback is recommended.

  Parameters

  • Optionalopts: KeyBackupRestoreOpts

  Returns Promise<KeyBackupRestoreResult>

restoreKeyBackupWithPassphrase

• restoreKeyBackupWithPassphrase(
      passphrase: string,
      opts?: KeyBackupRestoreOpts,
  ): Promise<KeyBackupRestoreResult>

• Restores a key backup using a passphrase. The decoded key (derived from the passphrase) is stored locally by calling CryptoApi#storeSessionBackupPrivateKey.

  Parameters

  • passphrase: string

    The passphrase to use to restore the key backup.
  • Optionalopts: KeyBackupRestoreOpts

  Returns Promise<KeyBackupRestoreResult>

  Deprecated

  Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/shared via 4S.

setDeviceIsolationMode

• setDeviceIsolationMode(isolationMode: DeviceIsolationMode): void

• The DeviceIsolationMode mode to use.

  Parameters

  • isolationMode: DeviceIsolationMode

  Returns void

setDeviceVerified

• setDeviceVerified(
      userId: string,
      deviceId: string,
      verified?: boolean,
  ): Promise<void>

• Mark the given device as locally verified.

  Marking a device as locally verified has much the same effect as completing the verification dance, or receiving a cross-signing signature for it.

  Parameters

  • userId: string

    owner of the device
  • deviceId: string

    unique identifier for the device.
  • Optionalverified: boolean

    whether to mark the device as verified. Defaults to 'true'.

  Returns Promise<void>

  Throws

  an error if the device is unknown, or has not published any encryption keys.

  Remarks

  Fires matrix.CryptoEvent.DeviceVerificationChanged

setTrustCrossSignedDevices

• setTrustCrossSignedDevices(val: boolean): void

• Set whether to trust other user's signatures of their devices.

  If false, devices will only be considered 'verified' if we have verified that device individually (effectively disabling cross-signing).

  true by default.

  Parameters

  • val: boolean

    the new value

  Returns void

startDehydration

• startDehydration(createNewKey?: boolean): Promise<void>

• Start using device dehydration.

  • Rehydrates a dehydrated device, if one is available.
  • Creates a new dehydration key, if necessary, and stores it in Secret Storage.
    • If createNewKey is set to true, always creates a new key.
    • If a dehydration key is not available, creates a new one.
  • Creates a new dehydrated device, and schedules periodically creating new dehydrated devices.

  This function must not be called unless isDehydrationSupported returns true, and must not be called until after cross-signing and secret storage have been set up.

  Parameters

  • OptionalcreateNewKey: boolean

    whether to force creation of a new dehydration key. This can be used, for example, if Secret Storage is being reset. Defaults to false.

  Returns Promise<void>

storeSessionBackupPrivateKey

• storeSessionBackupPrivateKey(key: Uint8Array<ArrayBufferLike>): Promise<void>

• Store the backup decryption key.

  This should be called if the client has received the key from another device via secret sharing (gossiping). It is the responsability of the caller to check that the decryption key is valid for the current backup version.

  Parameters

  • key: Uint8Array<ArrayBufferLike>

    the backup decryption key

  Returns Promise<void>

  Deprecated

  prefer the variant with a version parameter.

• storeSessionBackupPrivateKey(
      key: Uint8Array<ArrayBufferLike>,
      version: string,
  ): Promise<void>

• Store the backup decryption key.

  This should be called if the client has received the key from another device via secret sharing (gossiping). It is the responsability of the caller to check that the decryption key is valid for the given backup version.

  Parameters

  • key: Uint8Array<ArrayBufferLike>

    the backup decryption key
  • version: string

    the backup version corresponding to this decryption key

  Returns Promise<void>

userHasCrossSigningKeys

• userHasCrossSigningKeys(
      userId?: string,
      downloadUncached?: boolean,
  ): Promise<boolean>

• Check if the given user has published cross-signing keys.

  • If the user is tracked, a /keys/query request is made to update locally the cross signing keys.
  • If the user is not tracked locally and downloadUncached is set to true, a /keys/query request is made to the server to retrieve the cross signing keys.
  • Otherwise, return false

  Parameters

  • OptionaluserId: string

    the user ID to check. Defaults to the local user.
  • OptionaldownloadUncached: boolean

    If true, download the device list for users whose device list we are not currently tracking. Defaults to false, in which case false will be returned for such users.

  Returns Promise<boolean>

  true if the cross signing keys are available.