Move out crypto/aes (#4431)

* Move `SecretEncryptedPayload` in `src/utils/@types` * Move `encryptAES` to a dedicated file. Moved in a utils folder. * Move `deriveKeys` to a dedicated file in order to share it * Move `decryptAES` to a dedicated file. Moved in a utils folder. * Move `calculateKeyCheck` to a dedicated file. Moved in a utils folder. * Remove AES functions in `aes.ts` and export new ones for backward compatibility * Update import to use new functions * Add `src/utils` entrypoint in `README.md` * - Rename `SecretEncryptedPayload` to `AESEncryptedSecretStoragePayload`. - Move into `src/@types` * Move `calculateKeyCheck` into `secret-storage.ts`. * Move `deriveKeys` into `src/utils/internal` folder. * - Rename `encryptAES` on `encryptAESSecretStorageItem` - Change named export by default export * - Rename `decryptAES` on `decryptAESSecretStorageItem` - Change named export by default export * Update documentation * Update `decryptAESSecretStorageItem` doc * Add lnk to spec for `calculateKeyCheck` * Fix downstream tests
matrix-org · Oct 1, 2024 · 5f3b899 · 5f3b899
1 parent 866fd6f
commit 5f3b899
Show file tree

Hide file tree

Showing 22 changed files with 329 additions and 198 deletions.
diff --git a/README.md b/README.md
@@ -191,6 +191,7 @@ As well as the primary entry point (`matrix-js-sdk`), there are several other en
 | `matrix-js-sdk/lib/crypto-api` | Cryptography functionality. |
 | `matrix-js-sdk/lib/types` | Low-level types, reflecting data structures defined in the Matrix spec. |
 | `matrix-js-sdk/lib/testing` | Test utilities, which may be useful in test code but should not be used in production code. |
+| `matrix-js-sdk/lib/utils/*.js` | A set of modules exporting standalone functions (and their types). |
 
 ## Examples
 

diff --git a/spec/integ/crypto/cross-signing.spec.ts b/spec/integ/crypto/cross-signing.spec.ts
@@ -21,7 +21,7 @@ import { IDBFactory } from "fake-indexeddb";
 import { CRYPTO_BACKENDS, InitCrypto, syncPromise } from "../../test-utils/test-utils";
 import { AuthDict, createClient, CryptoEvent, MatrixClient } from "../../../src";
 import { mockInitialApiRequests, mockSetupCrossSigningRequests } from "../../test-utils/mockEndpoints";
-import { encryptAES } from "../../../src/crypto/aes";
+import encryptAESSecretStorageItem from "../../../src/utils/encryptAESSecretStorageItem.ts";
 import { CryptoCallbacks, CrossSigningKey } from "../../../src/crypto-api";
 import { SECRET_STORAGE_ALGORITHM_V1_AES } from "../../../src/secret-storage";
 import { ISyncResponder, SyncResponder } from "../../test-utils/SyncResponder";
@@ -169,17 +169,17 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("cross-signing (%s)", (backend: s
  mockInitialApiRequests(aliceClient.getHomeserverUrl());
 
  // Encrypt the private keys and return them in the /sync response as if they are in Secret Storage
- const masterKey = await encryptAES(
+ const masterKey = await encryptAESSecretStorageItem(
  MASTER_CROSS_SIGNING_PRIVATE_KEY_BASE64,
  encryptionKey,
  "m.cross_signing.master",
  );
- const selfSigningKey = await encryptAES(
+ const selfSigningKey = await encryptAESSecretStorageItem(
  SELF_CROSS_SIGNING_PRIVATE_KEY_BASE64,
  encryptionKey,
  "m.cross_signing.self_signing",
  );
- const userSigningKey = await encryptAES(
+ const userSigningKey = await encryptAESSecretStorageItem(
  USER_CROSS_SIGNING_PRIVATE_KEY_BASE64,
  encryptionKey,
  "m.cross_signing.user_signing",

diff --git a/spec/unit/crypto/secrets.spec.ts b/spec/unit/crypto/secrets.spec.ts
@@ -20,7 +20,7 @@ import { IObject } from "../../../src/crypto/olmlib";
 import { MatrixEvent } from "../../../src/models/event";
 import { TestClient } from "../../TestClient";
 import { makeTestClients } from "./verification/util";
-import { encryptAES } from "../../../src/crypto/aes";
+import encryptAESSecretStorageItem from "../../../src/utils/encryptAESSecretStorageItem.ts";
 import { createSecretStorageKey, resetCrossSigningKeys } from "./crypto-utils";
 import { logger } from "../../../src/logger";
 import { ClientEvent, ICreateClientOpts, MatrixClient } from "../../../src/client";
@@ -612,7 +612,7 @@ describe("Secrets", function () {
  type: "m.megolm_backup.v1",
  content: {
  encrypted: {
- key_id: await encryptAES(
+ key_id: await encryptAESSecretStorageItem(
  "123,45,6,7,89,1,234,56,78,90,12,34,5,67,8,90",
  secretStorageKeys.key_id,
  "m.megolm_backup.v1",

diff --git a/spec/unit/rust-crypto/rust-crypto.spec.ts b/spec/unit/rust-crypto/rust-crypto.spec.ts
@@ -69,7 +69,7 @@ import { logger } from "../../../src/logger";
 import { OutgoingRequestsManager } from "../../../src/rust-crypto/OutgoingRequestsManager";
 import { ClientEvent, ClientEventHandlerMap } from "../../../src/client";
 import { Curve25519AuthData } from "../../../src/crypto-api/keybackup";
-import { encryptAES } from "../../../src/crypto/aes";
+import encryptAESSecretStorageItem from "../../../src/utils/encryptAESSecretStorageItem.ts";
 import { CryptoStore, SecretStorePrivateKeys } from "../../../src/crypto/store/base";
 
 const TEST_USER = "@alice:example.com";
@@ -425,7 +425,7 @@ describe("initRustCrypto", () => {
  }, 10000);
 
  async function encryptAndStoreSecretKey(type: string, key: Uint8Array, pickleKey: string, store: CryptoStore) {
- const encryptedKey = await encryptAES(encodeBase64(key), Buffer.from(pickleKey), type);
+ const encryptedKey = await encryptAESSecretStorageItem(encodeBase64(key), Buffer.from(pickleKey), type);
  store.storeSecretStorePrivateKey(undefined, type as keyof SecretStorePrivateKeys, encryptedKey);
  }
 

diff --git a/spec/unit/secret-storage.spec.ts b/spec/unit/secret-storage.spec.ts
@@ -25,8 +25,8 @@ import {
  ServerSideSecretStorageImpl,
  trimTrailingEquals,
 } from "../../src/secret-storage";
-import { calculateKeyCheck } from "../../src/crypto/aes";
 import { randomString } from "../../src/randomstring";
+import { calculateKeyCheck } from "../../src/calculateKeyCheck.ts";
 
 describe("ServerSideSecretStorageImpl", function () {
  describe(".addKey", function () {

diff --git a/src/@types/AESEncryptedSecretStoragePayload.ts b/src/@types/AESEncryptedSecretStoragePayload.ts
@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * An AES-encrypted secret storage payload.
+ * See https://spec.matrix.org/v1.11/client-server-api/#msecret_storagev1aes-hmac-sha2-1
+ */
+export interface AESEncryptedSecretStoragePayload {
+ [key: string]: any; // extensible
+ /** the initialization vector in base64 */
+ iv: string;
+ /** the ciphertext in base64 */
+ ciphertext: string;
+ /** the HMAC in base64 */
+ mac: string;
+}
diff --git a/src/calculateKeyCheck.ts b/src/calculateKeyCheck.ts
@@ -0,0 +1,34 @@
+/*
+ * Copyright 2024 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// string of zeroes, for calculating the key check
+import encryptAESSecretStorageItem from "./utils/encryptAESSecretStorageItem.ts";
+import { AESEncryptedSecretStoragePayload } from "./@types/AESEncryptedSecretStoragePayload.ts";
+
+const ZERO_STR = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
+
+/**
+ * Calculate the MAC for checking the key.
+ * See https://spec.matrix.org/v1.11/client-server-api/#msecret_storagev1aes-hmac-sha2, steps 3 and 4.
+ *
+ * @param key - the key to use
+ * @param iv - The initialization vector as a base64-encoded string.
+ * If omitted, a random initialization vector will be created.
+ * @returns An object that contains, `mac` and `iv` properties.
+ */
+export function calculateKeyCheck(key: Uint8Array, iv?: string): Promise<AESEncryptedSecretStoragePayload> {
+ return encryptAESSecretStorageItem(ZERO_STR, key, "", iv);
+}
diff --git a/src/crypto-api/keybackup.ts b/src/crypto-api/keybackup.ts
@@ -15,7 +15,7 @@ limitations under the License.
 */
 
 import { ISigned } from "../@types/signed.ts";
-import { IEncryptedPayload } from "../crypto/aes.ts";
+import { AESEncryptedSecretStoragePayload } from "../@types/AESEncryptedSecretStoragePayload.ts";
 
 export interface Curve25519AuthData {
  public_key: string;
@@ -77,7 +77,7 @@ export interface Curve25519SessionData {
 }
 
 /* eslint-disable camelcase */
-export interface KeyBackupSession<T = Curve25519SessionData | IEncryptedPayload> {
+export interface KeyBackupSession<T = Curve25519SessionData | AESEncryptedSecretStoragePayload> {
  first_message_index: number;
  forwarded_count: number;
  is_verified: boolean;

diff --git a/src/crypto/CrossSigning.ts b/src/crypto/CrossSigning.ts
@@ -22,7 +22,6 @@ import type { PkSigning } from "@matrix-org/olm";
 import { IObject, pkSign, pkVerify } from "./olmlib.ts";
 import { logger } from "../logger.ts";
 import { IndexedDBCryptoStore } from "../crypto/store/indexeddb-crypto-store.ts";
-import { decryptAES, encryptAES } from "./aes.ts";
 import { DeviceInfo } from "./deviceinfo.ts";
 import { ISignedKey, MatrixClient } from "../client.ts";
 import { OlmDevice } from "./OlmDevice.ts";
@@ -36,6 +35,8 @@ import {
  UserVerificationStatus as UserTrustLevel,
 } from "../crypto-api/index.ts";
 import { decodeBase64, encodeBase64 } from "../base64.ts";
+import encryptAESSecretStorageItem from "../utils/encryptAESSecretStorageItem.ts";
+import decryptAESSecretStorageItem from "../utils/decryptAESSecretStorageItem.ts";
 
 // backwards-compatibility re-exports
 export { UserTrustLevel };
@@ -662,7 +663,7 @@ export function createCryptoStoreCacheCallbacks(store: CryptoStore, olmDevice: O
 
  if (key && key.ciphertext) {
  const pickleKey = Buffer.from(olmDevice.pickleKey);
- const decrypted = await decryptAES(key, pickleKey, type);
+ const decrypted = await decryptAESSecretStorageItem(key, pickleKey, type);
  return decodeBase64(decrypted);
  } else {
  return key;
@@ -676,7 +677,7 @@ export function createCryptoStoreCacheCallbacks(store: CryptoStore, olmDevice: O
  throw new Error(`storeCrossSigningKeyCache expects Uint8Array, got ${key}`);
  }
  const pickleKey = Buffer.from(olmDevice.pickleKey);
- const encryptedKey = await encryptAES(encodeBase64(key), pickleKey, type);
+ const encryptedKey = await encryptAESSecretStorageItem(encodeBase64(key), pickleKey, type);
  return store.doTxn("readwrite", [IndexedDBCryptoStore.STORE_ACCOUNT], (txn) => {
  store.storeSecretStorePrivateKey(txn, type, encryptedKey);
  });

diff --git a/src/crypto/aes.ts b/src/crypto/aes.ts
@@ -14,153 +14,13 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { decodeBase64, encodeBase64 } from "../base64.ts";
-
-// salt for HKDF, with 8 bytes of zeros
-const zeroSalt = new Uint8Array(8);
-
-export interface IEncryptedPayload {
- [key: string]: any; // extensible
- /** the initialization vector in base64 */
- iv: string;
- /** the ciphertext in base64 */
- ciphertext: string;
- /** the HMAC in base64 */
- mac: string;
-}
-
-/**
- * Encrypt a string using AES-CTR.
- *
- * @param data - the plaintext to encrypt
- * @param key - the encryption key to use as an input to the HKDF function which is used to derive the AES key for
- * encryption. Obviously, the same key must be provided when decrypting.
- * @param name - the name of the secret. Used as an input to the HKDF operation which is used to derive the AES key,
- * so again the same value must be provided when decrypting.
- * @param ivStr - the base64-encoded initialization vector to use. If not supplied, a random one will be generated.
- *
- * @returns The encrypted result, including the ciphertext itself, the initialization vector (as supplied in `ivStr`,
- * or generated), and an HMAC on the ciphertext — all base64-encoded.
- */
-export async function encryptAES(
- data: string,
- key: Uint8Array,
- name: string,
- ivStr?: string,
-): Promise<IEncryptedPayload> {
- let iv: Uint8Array;
- if (ivStr) {
- iv = decodeBase64(ivStr);
- } else {
- iv = new Uint8Array(16);
- globalThis.crypto.getRandomValues(iv);
-
- // clear bit 63 of the IV to stop us hitting the 64-bit counter boundary
- // (which would mean we wouldn't be able to decrypt on Android). The loss
- // of a single bit of iv is a price we have to pay.
- iv[8] &= 0x7f;
- }
-
- const [aesKey, hmacKey] = await deriveKeys(key, name);
- const encodedData = new TextEncoder().encode(data);
-
- const ciphertext = await globalThis.crypto.subtle.encrypt(
- {
- name: "AES-CTR",
- counter: iv,
- length: 64,
- },
- aesKey,
- encodedData,
- );
-
- const hmac = await globalThis.crypto.subtle.sign({ name: "HMAC" }, hmacKey, ciphertext);
-
- return {
- iv: encodeBase64(iv),
- ciphertext: encodeBase64(ciphertext),
- mac: encodeBase64(hmac),
- };
-}
-
-/**
- * Decrypt an AES-encrypted string.
- *
- * @param data - the encrypted data, returned by {@link encryptAES}.
- * @param key - the encryption key to use as an input to the HKDF function which is used to derive the AES key. Must
- * be the same as provided to {@link encryptAES}.
- * @param name - the name of the secret. Also used as an input to the HKDF operation which is used to derive the AES
- * key, so again must be the same as provided to {@link encryptAES}.
- */
-export async function decryptAES(data: IEncryptedPayload, key: Uint8Array, name: string): Promise<string> {
- const [aesKey, hmacKey] = await deriveKeys(key, name);
-
- const ciphertext = decodeBase64(data.ciphertext);
-
- if (!(await globalThis.crypto.subtle.verify({ name: "HMAC" }, hmacKey, decodeBase64(data.mac), ciphertext))) {
- throw new Error(`Error decrypting secret ${name}: bad MAC`);
- }
-
- const plaintext = await globalThis.crypto.subtle.decrypt(
- {
- name: "AES-CTR",
- counter: decodeBase64(data.iv),
- length: 64,
- },
- aesKey,
- ciphertext,
- );
-
- return new TextDecoder().decode(new Uint8Array(plaintext));
-}
-
-async function deriveKeys(key: Uint8Array, name: string): Promise<[CryptoKey, CryptoKey]> {
- const hkdfkey = await globalThis.crypto.subtle.importKey("raw", key, { name: "HKDF" }, false, ["deriveBits"]);
- const keybits = await globalThis.crypto.subtle.deriveBits(
- {
- name: "HKDF",
- salt: zeroSalt,
- // eslint-disable-next-line @typescript-eslint/ban-ts-comment
- // @ts-ignore: https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/879
- info: new TextEncoder().encode(name),
- hash: "SHA-256",
- },
- hkdfkey,
- 512,
- );
-
- const aesKey = keybits.slice(0, 32);
- const hmacKey = keybits.slice(32);
-
- const aesProm = globalThis.crypto.subtle.importKey("raw", aesKey, { name: "AES-CTR" }, false, [
- "encrypt",
- "decrypt",
- ]);
-
- const hmacProm = globalThis.crypto.subtle.importKey(
- "raw",
- hmacKey,
- {
- name: "HMAC",
- hash: { name: "SHA-256" },
- },
- false,
- ["sign", "verify"],
- );
-
- return Promise.all([aesProm, hmacProm]);
-}
-
-// string of zeroes, for calculating the key check
-const ZERO_STR = "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0";
-
-/** Calculate the MAC for checking the key.
- *
- * @param key - the key to use
- * @param iv - The initialization vector as a base64-encoded string.
- * If omitted, a random initialization vector will be created.
- * @returns An object that contains, `mac` and `iv` properties.
- */
-export function calculateKeyCheck(key: Uint8Array, iv?: string): Promise<IEncryptedPayload> {
- return encryptAES(ZERO_STR, key, "", iv);
-}
+import encryptAESSecretStorageItem from "../utils/encryptAESSecretStorageItem.ts";
+import decryptAESSecretStorageItem from "../utils/decryptAESSecretStorageItem.ts";
+import { AESEncryptedSecretStoragePayload } from "../@types/AESEncryptedSecretStoragePayload.ts";
+
+// Export for backwards compatibility
+export type { AESEncryptedSecretStoragePayload as IEncryptedPayload };
+// Export with new names instead of using `as` to not break react-sdk tests
+export const encryptAES = encryptAESSecretStorageItem;
+export const decryptAES = decryptAESSecretStorageItem;
+export { calculateKeyCheck } from "../calculateKeyCheck.ts";