Interface CryptoCallbacks

Crypto callbacks provided by the application

interface CryptoCallbacks {
    cacheSecretStorageKey?: (
        keyId: string,
        keyInfo: SecretStorageKeyDescriptionAesV1,
        key: Uint8Array<ArrayBufferLike>,
    ) => void;
    getBackupKey?: () => Promise<Uint8Array<ArrayBufferLike>>;
    getCrossSigningKey?: (
        keyType: string,
        pubKey: string,
    ) => Promise<null | Uint8Array<ArrayBufferLike>>;
    getDehydrationKey?: (
        keyInfo: SecretStorageKeyDescriptionAesV1,
        checkFunc: (key: Uint8Array<ArrayBufferLike>) => void,
    ) => Promise<Uint8Array<ArrayBufferLike>>;
    getSecretStorageKey?: (
        opts: { keys: Record<string, SecretStorageKeyDescriptionAesV1> },
        name: string,
    ) => Promise<null | [string, Uint8Array<ArrayBufferLike>]>;
    onSecretRequested?: (
        userId: string,
        deviceId: string,
        requestId: string,
        secretName: string,
        deviceTrust: DeviceVerificationStatus,
    ) => Promise<undefined | string>;
    saveCrossSigningKeys?: (
        keys: Record<string, Uint8Array<ArrayBufferLike>>,
    ) => void;
    shouldUpgradeDeviceVerifications?: (
        users: Record<string, any>,
    ) => Promise<string[]>;
}

Properties

cacheSecretStorageKey? getBackupKey? getCrossSigningKey? getDehydrationKey? getSecretStorageKey? onSecretRequested? saveCrossSigningKeys? shouldUpgradeDeviceVerifications?

Properties

OptionalcacheSecretStorageKey

cacheSecretStorageKey?: (
    keyId: string,
    keyInfo: SecretStorageKeyDescriptionAesV1,
    key: Uint8Array<ArrayBufferLike>,
) => void

Called by CryptoApi.bootstrapSecretStorage when a new default secret storage key is created.

Applications can use this to (temporarily) cache the secret storage key, for later return by getSecretStorageKey.

Type declaration

OptionalgetBackupKey

getBackupKey?: () => Promise<Uint8Array<ArrayBufferLike>>

@deprecated: unused with the Rust crypto stack.

OptionalgetCrossSigningKey

getCrossSigningKey?: (
    keyType: string,
    pubKey: string,
) => Promise<null | Uint8Array<ArrayBufferLike>>

@deprecated: unused with the Rust crypto stack.

OptionalgetDehydrationKey

getDehydrationKey?: (
    keyInfo: SecretStorageKeyDescriptionAesV1,
    checkFunc: (key: Uint8Array<ArrayBufferLike>) => void,
) => Promise<Uint8Array<ArrayBufferLike>>

@deprecated: unused with the Rust crypto stack.

OptionalgetSecretStorageKey

getSecretStorageKey?: (
    opts: { keys: Record<string, SecretStorageKeyDescriptionAesV1> },
    name: string,
) => Promise<null | [string, Uint8Array<ArrayBufferLike>]>

Called to retrieve a secret storage encryption key.

Server-side secret storage is, as the name implies, a mechanism for storing secrets which should be shared between clients on the server. For example, it is typically used for storing the key backup decryption key and the private cross-signing keys.

The secret storage mechanism encrypts the secrets before uploading them to the server using a secret storage key. The schema supports multiple keys, but in practice only one tends to be used at once; this is the "default secret storage key" and may be known as the "recovery key" (or, sometimes, the "security key").

Secret storage can be set up by calling CryptoApi.bootstrapSecretStorage. Having done so, when the crypto stack needs to access secret storage (for example, when setting up a new device, or to store newly-generated secrets), it will use this callback (getSecretStorageKey).

Note that the secret storage key may be needed several times in quick succession: it is recommended that applications use a temporary cache to avoid prompting the user multiple times for the key. See also cacheSecretStorageKey which is called when a new key is created.

The helper method deriveRecoveryKeyFromPassphrase may be useful if the secret storage key was derived from a passphrase.

Type declaration

    • (
          opts: { keys: Record<string, SecretStorageKeyDescriptionAesV1> },
          name: string,
      ): Promise<null | [string, Uint8Array<ArrayBufferLike>]>

    • Parameters

      • opts: { keys: Record<string, SecretStorageKeyDescriptionAesV1> }

        An options object.

        • keys: Record<string, SecretStorageKeyDescriptionAesV1>

          Details of the secret storage keys required: a map from the key ID (excluding the m.secret_storage.key. prefix) to details of the key.

          When storing a secret, keys will contain exactly one entry.

          For secret retrieval, keys may contain several entries, and the application can return any one of the requested keys. Unless your application specifically wants to offer the user the ability to have more than one secret storage key active at a time, it is recommended to call ServerSideSecretStorage.getDefaultKeyId to figure out which is the current default key, and to return null if the default key is not listed in keys.

      • name: string

        the name of the secret (NB: not the encryption key) being stored or retrieved. When the item is stored in account data, it will have this type.

      Returns Promise<null | [string, Uint8Array<ArrayBufferLike>]>

      a pair [keyId, privateKey], where keyId is one of the keys from the keys parameter, and privateKey is the raw private encryption key, as appropriate for the encryption algorithm. (For m.secret_storage.v1.aes-hmac-sha2, it is the input to an HKDF as defined in the specification.)

      Alternatively, if none of the keys are known, may return null — in which case the original operation that requires access to a secret in secret storage may fail with an exception.

OptionalonSecretRequested

onSecretRequested?: (
    userId: string,
    deviceId: string,
    requestId: string,
    secretName: string,
    deviceTrust: DeviceVerificationStatus,
) => Promise<undefined | string>

@deprecated: unused with the Rust crypto stack.

OptionalsaveCrossSigningKeys

saveCrossSigningKeys?: (
    keys: Record<string, Uint8Array<ArrayBufferLike>>,
) => void

@deprecated: unused with the Rust crypto stack.

OptionalshouldUpgradeDeviceVerifications

shouldUpgradeDeviceVerifications?: (
    users: Record<string, any>,
) => Promise<string[]>

@deprecated: unused with the Rust crypto stack.

Settings

Member Visibility

On This Page

Properties