Interface SecretStorageCallbacks

Application callbacks for use with SecretStorage.ServerSideSecretStorageImpl

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

Hierarchy (View Summary)

Properties

getSecretStorageKey?

Properties

OptionalgetSecretStorageKey

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

Called to retrieve a secret storage encryption key

Before a secret can be stored in server-side storage, it must be encrypted with one or more keys. Similarly, after it has been retrieved from storage, it must be decrypted with one of the keys it was encrypted with. These encryption keys are known as "secret storage keys".

Descriptions of the secret storage keys are also stored in server-side storage, per the matrix specification, so before a key can be used in this way, it must have been stored on the server. This is done via ServerSideSecretStorage#addKey.

Obviously the keys themselves are not stored server-side, so the js-sdk calls this callback in order to retrieve a secret storage key from the application.

Type declaration

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

    • Parameters

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

        An options object, containing only the property keys.

        • 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; this method will be called once for each secret storage key to be used for encryption.

          For secret retrieval, keys may contain several entries, and the application can return any one of the requested keys.

      • name: string

        the name of the secret (NB: not the encryption key) being stored or retrieved. This is the "event type" stored in account data.

      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 storage/retrieval operation will fail with an exception.

Settings

Member Visibility

On This Page

Properties