Interface CryptoApi

Public interface to the cryptography parts of the js-sdk

Remarks

Currently, this is a work-in-progress. In time, more methods will be added here.

interface CryptoApi {
    globalBlacklistUnverifiedDevices: boolean;
    bootstrapCrossSigning(opts: BootstrapCrossSigningOpts): Promise<void>;
    bootstrapSecretStorage(opts: CreateSecretStorageOpts): Promise<void>;
    checkKeyBackupAndEnable(): Promise<null | KeyBackupCheck>;
    createRecoveryKeyFromPassphrase(password?: string): Promise<GeneratedSecretStorageKey>;
    crossSignDevice(deviceId: string): Promise<void>;
    deleteKeyBackupVersion(version: string): Promise<void>;
    encryptToDeviceMessages(eventType: string, devices: {
        deviceId: string;
        userId: string;
    }[], payload: ToDevicePayload): Promise<ToDeviceBatch>;
    exportRoomKeys(): Promise<IMegolmSessionData[]>;
    exportRoomKeysAsJson(): Promise<string>;
    exportSecretsBundle?(): Promise<{
        backup?: {
            algorithm: string;
            backup_version: string;
            key: string;
        };
        cross_signing: {
            master_key: string;
            self_signing_key: string;
            user_signing_key: string;
        };
    }>;
    findVerificationRequestDMInProgress(roomId: string): undefined | VerificationRequest;
    findVerificationRequestDMInProgress(roomId: string, userId?: string): undefined | VerificationRequest;
    forceDiscardSession(roomId: string): Promise<void>;
    getActiveSessionBackupVersion(): Promise<null | string>;
    getCrossSigningKeyId(type?: CrossSigningKey): Promise<null | string>;
    getCrossSigningStatus(): Promise<CrossSigningStatus>;
    getDeviceVerificationStatus(userId: string, deviceId: string): Promise<null | DeviceVerificationStatus>;
    getEncryptionInfoForEvent(event: MatrixEvent): Promise<null | EventEncryptionInfo>;
    getOwnDeviceKeys(): Promise<OwnDeviceKeys>;
    getSessionBackupPrivateKey(): Promise<null | Uint8Array>;
    getTrustCrossSignedDevices(): boolean;
    getUserDeviceInfo(userIds: string[], downloadUncached?: boolean): Promise<DeviceMap>;
    getUserVerificationStatus(userId: string): Promise<UserVerificationStatus>;
    getVerificationRequestsToDeviceInProgress(userId: string): VerificationRequest[];
    getVersion(): string;
    importRoomKeys(keys: IMegolmSessionData[], opts?: ImportRoomKeysOpts): Promise<void>;
    importRoomKeysAsJson(keys: string, opts?: ImportRoomKeysOpts): Promise<void>;
    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>;
    isCrossSigningReady(): Promise<boolean>;
    isDehydrationSupported(): Promise<boolean>;
    isEncryptionEnabledInRoom(roomId: string): Promise<boolean>;
    isKeyBackupTrusted(info: KeyBackupInfo): Promise<BackupTrustInfo>;
    isSecretStorageReady(): Promise<boolean>;
    pinCurrentUserIdentity(userId: string): Promise<void>;
    prepareToEncrypt(room: Room): void;
    requestDeviceVerification(userId: string, deviceId: string): Promise<VerificationRequest>;
    requestOwnUserVerification(): Promise<VerificationRequest>;
    requestVerificationDM(userId: string, roomId: string): Promise<VerificationRequest>;
    resetKeyBackup(): Promise<void>;
    setDeviceIsolationMode(isolationMode: DeviceIsolationMode): void;
    setDeviceVerified(userId: string, deviceId: string, verified?: boolean): Promise<void>;
    setTrustCrossSignedDevices(val: boolean): void;
    startDehydration(createNewKey?: boolean): Promise<void>;
    storeSessionBackupPrivateKey(key: Uint8Array): Promise<void>;
    storeSessionBackupPrivateKey(key: Uint8Array, version: string): Promise<void>;
    userHasCrossSigningKeys(userId?: string, downloadUncached?: boolean): Promise<boolean>;
}

Hierarchy (view full)

Properties

globalBlacklistUnverifiedDevices

Methods

bootstrapCrossSigning bootstrapSecretStorage checkKeyBackupAndEnable createRecoveryKeyFromPassphrase crossSignDevice deleteKeyBackupVersion encryptToDeviceMessages exportRoomKeys exportRoomKeysAsJson exportSecretsBundle? findVerificationRequestDMInProgress forceDiscardSession getActiveSessionBackupVersion getCrossSigningKeyId getCrossSigningStatus getDeviceVerificationStatus getEncryptionInfoForEvent getOwnDeviceKeys getSessionBackupPrivateKey getTrustCrossSignedDevices getUserDeviceInfo getUserVerificationStatus getVerificationRequestsToDeviceInProgress getVersion importRoomKeys importRoomKeysAsJson importSecretsBundle? isCrossSigningReady isDehydrationSupported isEncryptionEnabledInRoom isKeyBackupTrusted isSecretStorageReady pinCurrentUserIdentity prepareToEncrypt requestDeviceVerification requestOwnUserVerification requestVerificationDM resetKeyBackup setDeviceIsolationMode setDeviceVerified setTrustCrossSignedDevices startDehydration storeSessionBackupPrivateKey userHasCrossSigningKeys

Properties

globalBlacklistUnverifiedDevices

globalBlacklistUnverifiedDevices: boolean

Global override for whether the client should ever send encrypted messages to unverified devices. This provides the default for rooms which do not specify a value.

If true, all unverified devices will be blacklisted by default

Methods

bootstrapCrossSigning

  • bootstrapCrossSigning(opts): 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

    Returns Promise<void>

bootstrapSecretStorage

  • bootstrapSecretStorage(opts): 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

    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?): 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): 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

encryptToDeviceMessages

exportRoomKeys

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): 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, userId?): 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): 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?): 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

getDeviceVerificationStatus

  • getDeviceVerificationStatus(userId, deviceId): 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

getOwnDeviceKeys

getSessionBackupPrivateKey

getTrustCrossSignedDevices

getUserDeviceInfo

  • getUserDeviceInfo(userIds, downloadUncached?): 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

getVerificationRequestsToDeviceInProgress

  • getVerificationRequestsToDeviceInProgress(userId): 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

importRoomKeysAsJson

  • importRoomKeysAsJson(keys, opts?): 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): 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

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

    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): 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

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

pinCurrentUserIdentity

  • pinCurrentUserIdentity(userId): 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): 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, deviceId): 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

requestVerificationDM

  • requestVerificationDM(userId, roomId): 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

setDeviceIsolationMode

setDeviceVerified

  • setDeviceVerified(userId, deviceId, verified?): 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): 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?): 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): 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

    Returns Promise<void>

    Deprecated

    prefer the variant with a version parameter.

  • storeSessionBackupPrivateKey(key, version): 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

      the backup decryption key

    • version: string

      the backup version corresponding to this decryption key

    Returns Promise<void>

userHasCrossSigningKeys

  • userHasCrossSigningKeys(userId?, downloadUncached?): 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.

Settings

Member Visibility

On This Page

Properties
Methods
bootstrapCrossSigningbootstrapSecretStoragecheckKeyBackupAndEnablecreateRecoveryKeyFromPassphrasecrossSignDevicedeleteKeyBackupVersionencryptToDeviceMessagesexportRoomKeysexportRoomKeysAsJsonexportSecretsBundlefindVerificationRequestDMInProgressforceDiscardSessiongetActiveSessionBackupVersiongetCrossSigningKeyIdgetCrossSigningStatusgetDeviceVerificationStatusgetEncryptionInfoForEventgetOwnDeviceKeysgetSessionBackupPrivateKeygetTrustCrossSignedDevicesgetUserDeviceInfogetUserVerificationStatusgetVerificationRequestsToDeviceInProgressgetVersionimportRoomKeysimportRoomKeysAsJsonimportSecretsBundleisCrossSigningReadyisDehydrationSupportedisEncryptionEnabledInRoomisKeyBackupTrustedisSecretStorageReadypinCurrentUserIdentityprepareToEncryptrequestDeviceVerificationrequestOwnUserVerificationrequestVerificationDMresetKeyBackupsetDeviceIsolationModesetDeviceVerifiedsetTrustCrossSignedDevicesstartDehydrationstoreSessionBackupPrivateKeyuserHasCrossSigningKeys