Interface ICryptoCallbacks

Type declaration

• • (keys, name): Promise<null | [string, Uint8Array]>

  • 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 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.

    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]>

    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.