@yume-chan/adb 2.6.2 → 3.0.0-beta.0

package/src/daemon/auth/packet-processor.ts

@@ -0,0 +1,212 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import { EmptyUint8Array, encodeUtf8 } from "@yume-chan/struct";
+
+import {
+    calculateBase64EncodedLength,
+    encodeBase64,
+} from "../../utils/base64.js";
+import { rsaSign } from "../crypto.js";
+import type { AdbPacketData } from "../packet.js";
+import { AdbCommand } from "../packet.js";
+
+import type { AdbDaemonAuthProcessor } from "./authenticator.js";
+import {
+    adbGeneratePublicKey,
+    adbGetPublicKeyFingerprint,
+    adbGetPublicKeySize,
+} from "./public-key.js";
+import type { AdbPrivateKey } from "./type.js";
+
+export type MaybeError<T> = T | Error;
+
+export type AdbKeyIterable =
+    | Iterable<MaybeError<AdbPrivateKey>>
+    | AsyncIterable<MaybeError<AdbPrivateKey>>;
+
+export interface AdbCredentialManager {
+    /**
+     * Generates and stores a RSA private key with modulus length `2048` and public exponent `65537`.
+     */
+    generateKey(): MaybePromiseLike<AdbPrivateKey>;
+
+    /**
+     * Synchronously or asynchronously iterates through all stored RSA private keys.
+     *
+     * Each call to `iterateKeys` must return a different iterator that iterate through all stored keys.
+     */
+    iterateKeys(): AdbKeyIterable;
+}
+
+export interface AdbKeyInfo {
+    fingerprint: string;
+    name: string | undefined;
+}
+
+export const AdbDaemonAuthType = {
+    Token: 1,
+    Signature: 2,
+    PublicKey: 3,
+} as const;
+
+export type AdbDaemonAuthType =
+    (typeof AdbDaemonAuthType)[keyof typeof AdbDaemonAuthType];
+
+export interface AdbDaemonDefaultAuthProcessorInit {
+    credentialManager: AdbCredentialManager;
+    onKeyLoadError?: ((error: Error) => void) | undefined;
+    onSignatureAuthentication?: ((key: AdbKeyInfo) => void) | undefined;
+    onSignatureRejected?: ((key: AdbKeyInfo) => void) | undefined;
+    onPublicKeyAuthentication?: ((key: AdbKeyInfo) => void) | undefined;
+}
+
+export class AdbDaemonDefaultAuthProcessor implements AdbDaemonAuthProcessor {
+    #credentialManager: AdbCredentialManager;
+    #onKeyLoadError: ((error: Error) => void) | undefined;
+    #onSignatureAuthentication: ((key: AdbKeyInfo) => void) | undefined;
+    #onSignatureRejected: ((key: AdbKeyInfo) => void) | undefined;
+    #onPublicKeyAuthentication: ((key: AdbKeyInfo) => void) | undefined;
+
+    #iterator:
+        | Iterator<MaybeError<AdbPrivateKey>, void, void>
+        | AsyncIterator<MaybeError<AdbPrivateKey>, void, void>
+        | undefined;
+
+    #prevKeyInfo: AdbKeyInfo | undefined;
+    #firstKey: AdbPrivateKey | undefined;
+
+    constructor(init: AdbDaemonDefaultAuthProcessorInit) {
+        this.#credentialManager = init.credentialManager;
+        this.#onKeyLoadError = init.onKeyLoadError;
+        this.#onSignatureAuthentication = init.onSignatureAuthentication;
+        this.#onSignatureRejected = init.onSignatureRejected;
+        this.#onPublicKeyAuthentication = init.onPublicKeyAuthentication;
+    }
+
+    /**
+     * Gets the next available private key.
+     * @returns The next available private key, or `undefined` if no more key is available
+     */
+    async #getNextKey() {
+        if (!this.#iterator) {
+            const iterable = this.#credentialManager.iterateKeys();
+            if (Symbol.iterator in iterable) {
+                this.#iterator = iterable[Symbol.iterator]();
+            } else if (Symbol.asyncIterator in iterable) {
+                this.#iterator = iterable[Symbol.asyncIterator]();
+            } else {
+                throw new Error("`iterateKeys` doesn't return an iterator");
+            }
+        }
+
+        while (true) {
+            const { done, value } = await this.#iterator.next();
+            if (done) {
+                return undefined;
+            }
+
+            if (value instanceof Error) {
+                // Report the error, then continue calling `next`
+                this.#onKeyLoadError?.(value);
+                continue;
+            }
+
+            return value;
+        }
+    }
+
+    /**
+     * Tries to sign the challenge using the next private key.
+     *
+     * @param challenge The data to sign
+     * @returns An `AdbPacket` containing the response, or `undefined` if no key is available
+     */
+    async #sign(challenge: Uint8Array): Promise<AdbPacketData | undefined> {
+        const key = await this.#getNextKey();
+        if (!key) {
+            return undefined;
+        }
+
+        if (!this.#firstKey) {
+            this.#firstKey = key;
+        }
+
+        // A new challenge implies the previous signature was rejected.
+        if (this.#prevKeyInfo) {
+            this.#onSignatureRejected?.(this.#prevKeyInfo);
+        }
+
+        const fingerprint = adbGetPublicKeyFingerprint(key);
+        this.#prevKeyInfo = { fingerprint, name: key.name };
+        this.#onSignatureAuthentication?.(this.#prevKeyInfo);
+
+        return {
+            command: AdbCommand.Auth,
+            arg0: AdbDaemonAuthType.Signature,
+            arg1: 0,
+            payload: rsaSign(key, challenge),
+        };
+    }
+
+    async process(packet: AdbPacketData): Promise<AdbPacketData> {
+        if (packet.arg0 !== AdbDaemonAuthType.Token) {
+            throw new Error("Unsupported authentication packet");
+        }
+
+        const signature = await this.#sign(packet.payload);
+        if (signature) {
+            return signature;
+        }
+
+        let key = this.#firstKey;
+        if (!key) {
+            key = await this.#credentialManager.generateKey();
+        }
+
+        const publicKeyLength = adbGetPublicKeySize();
+        const [publicKeyBase64Length] =
+            calculateBase64EncodedLength(publicKeyLength);
+
+        const nameBuffer = key.name?.length
+            ? encodeUtf8(key.name)
+            : EmptyUint8Array;
+        const publicKeyBuffer = new Uint8Array(
+            publicKeyBase64Length +
+                (nameBuffer.length ? nameBuffer.length + 1 : 0) + // Space character + name
+                1, // Null character
+        );
+
+        adbGeneratePublicKey(key, publicKeyBuffer);
+        const fingerprint = adbGetPublicKeyFingerprint(
+            publicKeyBuffer.subarray(0, publicKeyLength),
+        );
+
+        encodeBase64(
+            publicKeyBuffer.subarray(0, publicKeyLength),
+            publicKeyBuffer,
+        );
+
+        if (nameBuffer.length) {
+            publicKeyBuffer[publicKeyBase64Length] = 0x20;
+            publicKeyBuffer.set(nameBuffer, publicKeyBase64Length + 1);
+        }
+
+        this.#onPublicKeyAuthentication?.({
+            fingerprint,
+            name: key.name,
+        });
+
+        return {
+            command: AdbCommand.Auth,
+            arg0: AdbDaemonAuthType.PublicKey,
+            arg1: 0,
+            payload: publicKeyBuffer,
+        };
+    }
+
+    async close(): Promise<undefined> {
+        await this.#iterator?.return?.();
+
+        this.#iterator = undefined;
+        this.#firstKey = undefined;
+    }
+}

package/src/daemon/auth/public-key.ts

@@ -0,0 +1,112 @@
+import { md5Digest } from "../../utils/md5.js";
+import type { SimpleRsaPrivateKey } from "../crypto.js";
+import { modInverse, setBigUint } from "../crypto.js";
+
+import type { AdbPrivateKey } from "./type.js";
+
+const ModulusLengthInBytes = 2048 / 8;
+const ModulusLengthInWords = ModulusLengthInBytes / 4;
+
+export function adbGetPublicKeySize() {
+    return 4 + 4 + ModulusLengthInBytes + ModulusLengthInBytes + 4;
+}
+
+export function adbGeneratePublicKey(
+    privateKey: SimpleRsaPrivateKey,
+): Uint8Array<ArrayBuffer>;
+export function adbGeneratePublicKey(
+    privateKey: SimpleRsaPrivateKey,
+    output: Uint8Array,
+): number;
+export function adbGeneratePublicKey(
+    privateKey: SimpleRsaPrivateKey,
+    output?: Uint8Array,
+): Uint8Array | number {
+    // cspell: ignore: mincrypt
+    // Android 6 and earlier has its own encryption library called mincrypt
+    // This is the RSA public key format used by mincrypt:
+    // https://android.googlesource.com/platform/system/core/+/bb0c180e62703c2068a1b2c9f8ba6d634bf1553c/include/mincrypt/rsa.h#46
+    // `n0inv` and `rr` are pre-calculated to speed up RSA operations
+
+    // Android 7 switched its encryption library to BoringSSL, but still keeps the key format:
+    // https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#38
+    // Except when reading a key, `n0inv` and `rr` are ignored (they are still populated when generating a key):
+    // https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#55
+
+    // The public key is a struct (in little endian) of:
+    //
+    // [
+    //   modulusLengthInWords, // 32-bit integer, a "word" is 32-bit so it must be 2048 / 8 / 4
+    //                         // (the comment in Android source code is incorrect saying "This must be ANDROID_PUBKEY_MODULUS_SIZE")
+    //   n0inv,                // 32-bit integer, the modular inverse of (lower 32 bits of `n`)
+    //   modulus,              // `n`
+    //   rr,                   // Montgomery parameter R^2
+    //   exponent,             // 32-bit integer, must be 3 or 65537
+    // ]
+
+    let outputType: "Uint8Array" | "number";
+    const outputLength = adbGetPublicKeySize();
+    if (!output) {
+        output = new Uint8Array(outputLength);
+        outputType = "Uint8Array";
+    } else {
+        if (output.length < outputLength) {
+            throw new TypeError("output buffer is too small");
+        }
+
+        outputType = "number";
+    }
+
+    const outputView = new DataView(
+        output.buffer,
+        output.byteOffset,
+        output.length,
+    );
+    let outputOffset = 0;
+
+    // modulusLengthInWords
+    outputView.setUint32(outputOffset, ModulusLengthInWords, true);
+    outputOffset += 4;
+
+    // extract `n` from private key
+    const { n } = privateKey;
+
+    // Calculate `n0inv`
+    const n0inv = -modInverse(Number(n % 2n ** 32n), 2 ** 32);
+    outputView.setInt32(outputOffset, n0inv, true);
+    outputOffset += 4;
+
+    // Write `n` (a.k.a. `modulus`)
+    setBigUint(output, outputOffset, ModulusLengthInBytes, n, true);
+    outputOffset += ModulusLengthInBytes;
+
+    // Calculate rr = (2 ** (rsa_size)) ** 2 % n
+    const rr = 2n ** 4096n % n;
+    setBigUint(output, outputOffset, ModulusLengthInBytes, rr, true);
+    outputOffset += ModulusLengthInBytes;
+
+    // exponent
+    outputView.setUint32(outputOffset, 65537, true);
+
+    if (outputType === "Uint8Array") {
+        return output;
+    } else {
+        return outputLength;
+    }
+}
+
+// https://cs.android.com/android/platform/superproject/main/+/main:frameworks/base/services/core/java/com/android/server/adb/AdbDebuggingManager.java;l=1419;drc=61197364367c9e404c7da6900658f1b16c42d0da
+export function adbGetPublicKeyFingerprint(privateKey: AdbPrivateKey): string;
+export function adbGetPublicKeyFingerprint(publicKey: Uint8Array): string;
+export function adbGetPublicKeyFingerprint(
+    key: AdbPrivateKey | Uint8Array,
+): string {
+    if ("d" in key) {
+        key = adbGeneratePublicKey(key);
+    }
+
+    const md5 = md5Digest(key);
+    return Array.from(md5, (byte) => byte.toString(16).padStart(2, "0")).join(
+        ":",
+    );
+}

package/src/daemon/auth/type.ts

@@ -0,0 +1,5 @@
+import type { SimpleRsaPrivateKey } from "../crypto.js";
+
+export interface AdbPrivateKey extends SimpleRsaPrivateKey {
+    name?: string | undefined;
+}

package/src/daemon/crypto.ts

@@ -48,11 +48,14 @@ export function setBigUint(
     littleEndian?: boolean,
 ) {
     if (littleEndian) {
+        const end = byteOffset + length;
         while (value > 0n) {
             setInt64LittleEndian(array, byteOffset, value);
             byteOffset += 8;
             value >>= 64n;
         }
+        // Clear the trailing bytes
+        array.subarray(byteOffset, end).fill(0);
     } else {
         let position = byteOffset + length - 8;
         while (value > 0n) {
@@ -60,9 +63,16 @@ export function setBigUint(
             position -= 8;
             value >>= 64n;
         }
+        // Clear the leading bytes
+        array.subarray(byteOffset, position + 8).fill(0);
     }
 }
 
+export interface SimpleRsaPrivateKey {
+    n: bigint;
+    d: bigint;
+}
+
 // These values are correct only if
 // modulus length is 2048 and
 // public exponent (e) is 65537
@@ -89,10 +99,16 @@ const RsaPrivateKeyNLength = 2048 / 8;
 const RsaPrivateKeyDOffset = 303;
 const RsaPrivateKeyDLength = 2048 / 8;
 
-export function rsaParsePrivateKey(key: Uint8Array): [n: bigint, d: bigint] {
+export function rsaParsePrivateKey(key: Uint8Array): SimpleRsaPrivateKey {
+    if (key.length < RsaPrivateKeyDOffset + RsaPrivateKeyDLength) {
+        throw new Error(
+            "RSA private key is too short. Expecting a PKCS#8 formatted RSA private key with modulus length 2048 bits and public exponent 65537.",
+        );
+    }
+
     const n = getBigUint(key, RsaPrivateKeyNOffset, RsaPrivateKeyNLength);
     const d = getBigUint(key, RsaPrivateKeyDOffset, RsaPrivateKeyDLength);
-    return [n, d];
+    return { n, d };
 }
 
 function nonNegativeMod(m: number, d: number) {
@@ -133,97 +149,6 @@ export function modInverse(a: number, m: number) {
     return nonNegativeMod(y, m);
 }
 
-const ModulusLengthInBytes = 2048 / 8;
-const ModulusLengthInWords = ModulusLengthInBytes / 4;
-
-export function adbGetPublicKeySize() {
-    return 4 + 4 + ModulusLengthInBytes + ModulusLengthInBytes + 4;
-}
-
-export function adbGeneratePublicKey(
-    privateKey: Uint8Array,
-): Uint8Array<ArrayBuffer>;
-export function adbGeneratePublicKey(
-    privateKey: Uint8Array,
-    output: Uint8Array,
-): number;
-export function adbGeneratePublicKey(
-    privateKey: Uint8Array,
-    output?: Uint8Array,
-): Uint8Array | number {
-    // cspell: ignore: mincrypt
-    // Android 6 and earlier has its own encryption library called mincrypt
-    // This is the RSA public key format used by mincrypt:
-    // https://android.googlesource.com/platform/system/core/+/bb0c180e62703c2068a1b2c9f8ba6d634bf1553c/include/mincrypt/rsa.h#46
-    // `n0inv` and `rr` are pre-calculated to speed up RSA operations
-
-    // Android 7 switched its encryption library to BoringSSL, but still keeps the key format:
-    // https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#38
-    // Except when reading a key, `n0inv` and `rr` are ignored (they are still populated when generating a key):
-    // https://android.googlesource.com/platform/system/core.git/+/91784040db2b9273687f88d8b95f729d4a61ecc2/libcrypto_utils/android_pubkey.cpp#55
-
-    // The public key is a struct (in little endian) of:
-    //
-    // [
-    //   modulusLengthInWords, // 32-bit integer, a "word" is 32-bit so it must be 2048 / 8 / 4
-    //                         // (the comment in Android source code is incorrect saying "This must be ANDROID_PUBKEY_MODULUS_SIZE")
-    //   n0inv,                // 32-bit integer, the modular inverse of (lower 32 bits of `n`)
-    //   modulus,              // `n`
-    //   rr,                   // Montgomery parameter R^2
-    //   exponent,             // 32-bit integer, must be 3 or 65537
-    // ]
-
-    let outputType: "Uint8Array" | "number";
-    const outputLength = adbGetPublicKeySize();
-    if (!output) {
-        output = new Uint8Array(outputLength);
-        outputType = "Uint8Array";
-    } else {
-        if (output.length < outputLength) {
-            throw new TypeError("output buffer is too small");
-        }
-
-        outputType = "number";
-    }
-
-    const outputView = new DataView(
-        output.buffer,
-        output.byteOffset,
-        output.length,
-    );
-    let outputOffset = 0;
-
-    // modulusLengthInWords
-    outputView.setUint32(outputOffset, ModulusLengthInWords, true);
-    outputOffset += 4;
-
-    // extract `n` from private key
-    const [n] = rsaParsePrivateKey(privateKey);
-
-    // Calculate `n0inv`
-    const n0inv = -modInverse(Number(n % 2n ** 32n), 2 ** 32);
-    outputView.setInt32(outputOffset, n0inv, true);
-    outputOffset += 4;
-
-    // Write `n` (a.k.a. `modulus`)
-    setBigUint(output, outputOffset, ModulusLengthInBytes, n, true);
-    outputOffset += ModulusLengthInBytes;
-
-    // Calculate rr = (2 ** (rsa_size)) ** 2 % n
-    const rr = 2n ** 4096n % n;
-    setBigUint(output, outputOffset, ModulusLengthInBytes, rr, true);
-    outputOffset += ModulusLengthInBytes;
-
-    // exponent
-    outputView.setUint32(outputOffset, 65537, true);
-
-    if (outputType === "Uint8Array") {
-        return output;
-    } else {
-        return outputLength;
-    }
-}
-
 /**
  * Modular exponentiation.
  *
@@ -282,17 +207,27 @@ export const SHA1_DIGEST_INFO = new Uint8Array([
     SHA1_DIGEST_LENGTH,
 ]);
 
-// SubtleCrypto.sign() will hash the given data and sign the hash
-// But we don't need the hashing step
-// (In another word, ADB just requires the client to
-// encrypt the given data with its private key)
-// However SubtileCrypto.encrypt() doesn't accept 'RSASSA-PKCS1-v1_5' algorithm
-// So we need to implement the encryption by ourself
+// Standard `RSASSA-PKCS1-v1_5` algorithm will hash the given data
+// and sign the hash
+// https://datatracker.ietf.org/doc/html/rfc8017#section-8.2
+//
+// But ADB authentication passes 20 bytes of random value to
+// OpenSSL's `RSA_sign` method which treat the input as a hash
+// https://docs.openssl.org/1.0.2/man3/RSA_sign/
+//
+// Since it's non-standard and not supported by Web Crypto API,
+// we need to implement the signing by ourself
 export function rsaSign(
-    privateKey: Uint8Array,
+    privateKey: SimpleRsaPrivateKey,
     data: Uint8Array,
 ): Uint8Array<ArrayBuffer> {
-    const [n, d] = rsaParsePrivateKey(privateKey);
+    if (data.length !== SHA1_DIGEST_LENGTH) {
+        throw new Error(
+            `rsaSign expects ${SHA1_DIGEST_LENGTH} bytes (SHA-1 digest length) of data but got ${data.length} bytes`,
+        );
+    }
+
+    const { n, d } = privateKey;
 
     // PKCS#1 padding
     const padded = new Uint8Array(256);

package/src/daemon/dispatcher.ts

@@ -19,7 +19,7 @@ import {
 } from "@yume-chan/stream-extra";
 import { EmptyUint8Array, decodeUtf8, encodeUtf8 } from "@yume-chan/struct";
 
-import type { AdbIncomingSocketHandler, AdbSocket, Closeable } from "../adb.js";
+import type { Adb, Closeable } from "../adb.js";
 
 import type { AdbPacketData, AdbPacketInit } from "./packet.js";
 import { AdbCommand, calculateChecksum } from "./packet.js";
@@ -114,7 +114,7 @@ export class AdbPacketDispatcher implements Closeable {
 
     readonly #incomingSocketHandlers = new Map<
         string,
-        AdbIncomingSocketHandler
+        Adb.IncomingSocketHandler
     >();
     readonly #readAbortController = new AbortController();
 
@@ -146,13 +146,20 @@ export class AdbPacketDispatcher implements Closeable {
                                 this.#handleOkay(packet);
                                 break;
                             case AdbCommand.Open:
-                                await this.#handleOpen(packet);
+                                // Don't await
+                                // The handler may take a long time to accept the socket,
+                                // don't block other sockets' packet processing.
+                                this.#handleOpen(packet).catch((e) => {
+                                    // Propagate fatal errors to consumer
+                                    controller.error(e);
+                                });
                                 break;
                             case AdbCommand.Write:
-                                // Don't await - let each socket handle its own backpressure
-                                // without blocking other sockets' packet processing.
-                                // Fatal errors are propagated via WritableStream's controller.
+                                // Don't await
+                                // The socket might be stalled because of backpressure,
+                                // don't block other sockets' packet processing.
                                 this.#handleWrite(packet).catch((e) => {
+                                    // Propagate fatal errors to consumer
                                     controller.error(e);
                                 });
                                 break;
@@ -392,7 +399,7 @@ export class AdbPacketDispatcher implements Closeable {
         await Promise.race(promises);
     }
 
-    async createSocket(service: string): Promise<AdbSocket> {
+    async createSocket(service: string): Promise<Adb.Socket> {
         if (this.options.appendNullToServiceString) {
             service += "\0";
         }
@@ -421,7 +428,7 @@ export class AdbPacketDispatcher implements Closeable {
         return controller.socket;
     }
 
-    addReverseTunnel(service: string, handler: AdbIncomingSocketHandler) {
+    addReverseTunnel(service: string, handler: Adb.IncomingSocketHandler) {
         this.#incomingSocketHandlers.set(service, handler);
     }
 

package/src/daemon/index.ts

@@ -1,4 +1,4 @@
-export * from "./auth.js";
+export * from "./auth/index.js";
 export * from "./crypto.js";
 export * from "./device.js";
 export * from "./dispatcher.js";

package/src/daemon/socket.ts

@@ -9,7 +9,7 @@ import type {
 import { MaybeConsumable, PushReadableStream } from "@yume-chan/stream-extra";
 import { EmptyUint8Array } from "@yume-chan/struct";
 
-import type { AdbSocket } from "../adb.js";
+import type { Adb } from "../adb.js";
 
 import type { AdbPacketDispatcher } from "./dispatcher.js";
 import { AdbCommand } from "./packet.js";
@@ -34,7 +34,7 @@ export interface AdbDaemonSocketInit extends AdbDaemonSocketInfo {
 }
 
 export class AdbDaemonSocketController
-    implements AdbDaemonSocketInfo, AdbSocket, Disposable
+    implements AdbDaemonSocketInfo, Adb.Socket, Disposable
 {
     readonly #dispatcher!: AdbPacketDispatcher;
 
@@ -177,7 +177,7 @@ export class AdbDaemonSocketController
 /**
  * A duplex stream representing a socket to ADB daemon.
  */
-export class AdbDaemonSocket implements AdbDaemonSocketInfo, AdbSocket {
+export class AdbDaemonSocket implements AdbDaemonSocketInfo, Adb.Socket {
     readonly #controller: AdbDaemonSocketController;
 
     get localId(): number {