EAR protocol response handling (#7656)

Finishes the initial implementation of the EAR protocol by adding
response decryption and parsing.

Author: tnorling

change/@azure-msal-browser-089af563-acd6-4dc8-94f9-006b2ae237a6.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "EAR Protocol response handling",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-6643b5ab-2508-4bf8-b495-dea9648e0c03.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Additional PerformanceEvents",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-415cc606-dd38-4077-ae89-34f12c5e6127.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Move addition of extraQueryParameters during request generation",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

lib/msal-browser/apiReview/msal-browser.api.md

@@ -188,6 +188,7 @@ declare namespace BrowserAuthErrorCodes {
     export {
         pkceNotCreated,
         earJwkEmpty,
+        earJweEmpty,
         cryptoNonExistent,
         emptyNavigateUri,
         hashEmptyError,
@@ -233,7 +234,8 @@ declare namespace BrowserAuthErrorCodes {
         invalidBase64String,
         invalidPopTokenRequest,
         failedToBuildHeaders,
-        failedToParseHeaders
+        failedToParseHeaders,
+        failedToDecryptEarResponse
     }
 }
 export { BrowserAuthErrorCodes }
@@ -711,6 +713,11 @@ const databaseUnavailable = "database_unavailable";
 // @public (undocumented)
 export const DEFAULT_IFRAME_TIMEOUT_MS = 10000;
 
+// Warning: (ae-missing-release-tag) "earJweEmpty" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+const earJweEmpty = "ear_jwe_empty";
+
 // Warning: (ae-missing-release-tag) "earJwkEmpty" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -839,6 +846,11 @@ export { ExternalTokenResponse }
 // @public (undocumented)
 const failedToBuildHeaders = "failed_to_build_headers";
 
+// Warning: (ae-missing-release-tag) "failedToDecryptEarResponse" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+const failedToDecryptEarResponse = "failed_to_decrypt_ear_response";
+
 // Warning: (ae-missing-release-tag) "failedToParseHeaders" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)

lib/msal-browser/src/crypto/BrowserCrypto.ts

@@ -13,7 +13,7 @@ import {
 } from "@azure/msal-common/browser";
 import { KEY_FORMAT_JWK } from "../utils/BrowserConstants.js";
 import { base64Encode, urlEncodeArr } from "../encode/Base64Encode.js";
-import { base64DecToArr } from "../encode/Base64Decode.js";
+import { base64Decode, base64DecToArr } from "../encode/Base64Decode.js";
 
 /**
  * This file defines functions used by the browser library to perform cryptography operations such as
@@ -242,6 +242,79 @@ export async function generateEarKey(): Promise<string> {
     return base64Encode(JSON.stringify(jwk));
 }
 
+/**
+ * Parses earJwk for encryption key and returns CryptoKey object
+ * @param earJwk
+ * @returns
+ */
+async function importEarKey(earJwk: string): Promise<CryptoKey> {
+    const b64DecodedJwk = base64Decode(earJwk);
+    const jwkJson = JSON.parse(b64DecodedJwk);
+    const rawKey = jwkJson.k;
+    const keyBuffer = base64DecToArr(rawKey);
+
+    return window.crypto.subtle.importKey(RAW, keyBuffer, AES_GCM, false, [
+        DECRYPT,
+    ]);
+}
+
+/**
+ * Decrypt ear_jwe response returned in the Encrypted Authorize Response (EAR) flow
+ * @param earJwk
+ * @param earJwe
+ * @returns
+ */
+export async function decryptEarResponse(
+    earJwk: string,
+    earJwe: string
+): Promise<string> {
+    const earJweParts = earJwe.split(".");
+    if (earJweParts.length !== 5) {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.failedToDecryptEarResponse,
+            "jwe_length"
+        );
+    }
+
+    const key = await importEarKey(earJwk).catch(() => {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.failedToDecryptEarResponse,
+            "import_key"
+        );
+    });
+
+    try {
+        const header = new TextEncoder().encode(earJweParts[0]);
+        const iv = base64DecToArr(earJweParts[2]);
+        const ciphertext = base64DecToArr(earJweParts[3]);
+        const tag = base64DecToArr(earJweParts[4]);
+        const tagLengthBits = tag.byteLength * 8;
+
+        // Concat ciphertext and tag
+        const encryptedData = new Uint8Array(ciphertext.length + tag.length);
+        encryptedData.set(ciphertext);
+        encryptedData.set(tag, ciphertext.length);
+
+        const decryptedData = await window.crypto.subtle.decrypt(
+            {
+                name: AES_GCM,
+                iv: iv,
+                tagLength: tagLengthBits,
+                additionalData: header,
+            },
+            key,
+            encryptedData
+        );
+
+        return new TextDecoder().decode(decryptedData);
+    } catch (e) {
+        throw createBrowserAuthError(
+            BrowserAuthErrorCodes.failedToDecryptEarResponse,
+            "decrypt"
+        );
+    }
+}
+
 /**
  * Generates symmetric base encryption key. This may be stored as all encryption/decryption keys will be derived from this one.
  */

lib/msal-browser/src/error/BrowserAuthError.ts

@@ -17,6 +17,8 @@ export const BrowserAuthErrorMessages = {
         "The PKCE code challenge and verifier could not be generated.",
     [BrowserAuthErrorCodes.earJwkEmpty]:
         "No EAR encryption key provided. This is unexpected.",
+    [BrowserAuthErrorCodes.earJweEmpty]:
+        "Server response does not contain ear_jwe property. This is unexpected.",
     [BrowserAuthErrorCodes.cryptoNonExistent]:
         "The crypto object or function is not available.",
     [BrowserAuthErrorCodes.emptyNavigateUri]:
@@ -96,6 +98,8 @@ export const BrowserAuthErrorMessages = {
         "Failed to build request headers object.",
     [BrowserAuthErrorCodes.failedToParseHeaders]:
         "Failed to parse response headers",
+    [BrowserAuthErrorCodes.failedToDecryptEarResponse]:
+        "Failed to decrypt ear response",
 };
 
 /**

lib/msal-browser/src/error/BrowserAuthErrorCodes.ts

@@ -5,6 +5,7 @@
 
 export const pkceNotCreated = "pkce_not_created";
 export const earJwkEmpty = "ear_jwk_empty";
+export const earJweEmpty = "ear_jwe_empty";
 export const cryptoNonExistent = "crypto_nonexistent";
 export const emptyNavigateUri = "empty_navigate_uri";
 export const hashEmptyError = "hash_empty_error";
@@ -58,3 +59,4 @@ export const invalidBase64String = "invalid_base64_string";
 export const invalidPopTokenRequest = "invalid_pop_token_request";
 export const failedToBuildHeaders = "failed_to_build_headers";
 export const failedToParseHeaders = "failed_to_parse_headers";
+export const failedToDecryptEarResponse = "failed_to_decrypt_ear_response";