@protontech/drive-sdk 0.0.10

package/src/crypto/hmac.ts

@@ -0,0 +1,46 @@
+const HASH_ALGORITHM = 'SHA-256';
+const KEY_LENGTH_BYTES = 32;
+export type HmacCryptoKey = CryptoKey;
+
+type HmacKeyUsage = 'sign' | 'verify';
+
+/**
+ * Import an HMAC-SHA256 key in order to use it with `signData` and `verifyData`.
+ */
+export const importHmacKey = async (
+    key: Uint8Array,
+    keyUsage: HmacKeyUsage[] = ['sign', 'verify']
+): Promise<HmacCryptoKey> => {
+    // From https://datatracker.ietf.org/doc/html/rfc2104:
+    // The key for HMAC can be of any length (keys longer than B bytes are first hashed using H).
+    // However, less than L bytes (L = 32 bytes for SHA-256) is strongly discouraged as it would
+    // decrease the security strength of the function.  Keys longer than L bytes are acceptable
+    // but the extra length would not significantly increase the function strength.
+    // (A longer key may be advisable if the randomness of the key is considered weak.)
+    if (key.length < KEY_LENGTH_BYTES) {
+        throw new Error('Unexpected HMAC key size: key is too short');
+    }
+    return crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: HASH_ALGORITHM }, false, keyUsage);
+};
+
+/**
+ * Sign data using HMAC-SHA256
+ * @param key - WebCrypto secret key for signing
+ * @param data - data to sign
+ * @param additionalData - additional data to authenticate
+ */
+export const computeHmacSignature = async (key: HmacCryptoKey, data: Uint8Array) => {
+    const signatureBuffer = await crypto.subtle.sign({ name: 'HMAC', hash: HASH_ALGORITHM }, key, data);
+    return new Uint8Array(signatureBuffer);
+};
+
+/**
+ * Verify data using HMAC-SHA256
+ * @param key - WebCrypto secret key for verification
+ * @param signature - signature over data
+ * @param data - data to verify
+ * @param additionalData - additional data to authenticate
+ */
+export const verifyData = async (key: HmacCryptoKey, signature: Uint8Array, data: Uint8Array) => {
+    return crypto.subtle.verify({ name: 'HMAC', hash: HASH_ALGORITHM }, key, signature, data);
+};

package/src/crypto/index.ts

@@ -0,0 +1,6 @@
+export type { OpenPGPCrypto, PrivateKey, PublicKey, SessionKey, SRPModule, SRPVerifier } from './interface';
+export { VERIFICATION_STATUS } from './interface';
+export { DriveCrypto } from './driveCrypto';
+export type { OpenPGPCryptoProxy } from './openPGPCrypto';
+export { OpenPGPCryptoWithCryptoProxy } from './openPGPCrypto';
+export { uint8ArrayToBase64String, base64StringToUint8Array } from './utils';

package/src/crypto/interface.ts

@@ -0,0 +1,230 @@
+// TODO: Use CryptoProxy once available.
+export interface PublicKey {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    readonly _idx: any;
+    readonly _keyContentHash: [string, string];
+
+    getVersion(): number;
+    getFingerprint(): string;
+    getSHA256Fingerprints(): string[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getKeyID(): any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getKeyIDs(): any[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getAlgorithmInfo(): any;
+    getCreationTime(): Date;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    isPrivate: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    isPrivateKeyV4: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    isPrivateKeyV6: any;
+    getExpirationTime(): Date | number | null;
+    getUserIDs(): string[];
+    isWeak(): boolean;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    equals(otherKey: any, ignoreOtherCerts?: boolean): boolean;
+    subkeys: {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getAlgorithmInfo(): any;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getKeyID(): any;
+    }[];
+}
+
+export interface PrivateKey extends PublicKey {
+    readonly _dummyType: 'private';
+}
+
+export interface SessionKey {
+    data: Uint8Array;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    algorithm: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    aeadAlgorithm?: any;
+}
+
+export enum VERIFICATION_STATUS {
+    NOT_SIGNED = 0,
+    SIGNED_AND_VALID = 1,
+    SIGNED_AND_INVALID = 2
+}
+
+export interface SRPModule {
+    getSrpVerifier: (password: string) => Promise<SRPVerifier>,
+}
+
+export type SRPVerifier = {
+    modulusId: string,
+    version: number,
+    salt: string,
+    verifier: string,
+}
+
+/**
+ * OpenPGP crypto layer to provide necessary PGP operations for Drive crypto.
+ * 
+ * This layer focuses on providing general openPGP functions. Every operation
+ * should prefer binary input and output. Ideally, armoring should be done
+ * later in serialisation step, but for now, it is part of the interface to
+ * be somewhat compatible with current web app, and also be more efficient
+ * (current CryptoProxy can do encryption and armoring in one operation with
+ * less passing data between web workers). In the future, we want to separate
+ * this out of here more.
+ */
+export interface OpenPGPCrypto {
+    /**
+     * Generate a random passphrase.
+     * 
+     * 32 random bytes are generated and encoded into a base64 string.
+     */
+    generatePassphrase: () => string,
+
+    generateSessionKey: (encryptionKeys: PrivateKey[]) => Promise<SessionKey>,
+
+    encryptSessionKey: (sessionKey: SessionKey, encryptionKeys: PublicKey | PublicKey[]) => Promise<{
+        keyPacket: Uint8Array,
+    }>,
+
+    encryptSessionKeyWithPassword: (sessionKey: SessionKey, password: string) => Promise<{
+        keyPacket: Uint8Array,
+    }>,
+
+    /**
+     * Generate a new key pair locked by a passphrase.
+     * 
+     * The key pair is generated using the Curve25519 algorithm.
+     */
+    generateKey: (passphrase: string) => Promise<{
+        privateKey: PrivateKey,
+        armoredKey: string,
+    }>,
+
+    encryptArmored: (
+        data: Uint8Array,
+        encryptionKeys: PrivateKey[],
+        sessionKey?: SessionKey,
+    ) => Promise<{
+        armoredData: string,
+    }>,
+
+    encryptAndSign: (
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) => Promise<{
+        encryptedData: Uint8Array,
+    }>,
+
+    encryptAndSignArmored: (
+        data: Uint8Array,
+        sessionKey: SessionKey | undefined,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) => Promise<{
+        armoredData: string,
+    }>,
+
+    encryptAndSignDetached: (
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) => Promise<{
+        encryptedData: Uint8Array,
+        signature: Uint8Array,
+    }>,
+
+    encryptAndSignDetachedArmored: (
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) => Promise<{
+        armoredData: string,
+        armoredSignature: string,
+    }>,
+
+    sign: (
+        data: Uint8Array,
+        signingKey: PrivateKey,
+        signatureContext: string,
+    ) => Promise<{
+        signature: Uint8Array,
+    }>,
+
+    signArmored: (
+        data: Uint8Array,
+        signingKey: PrivateKey | PrivateKey[],
+    ) => Promise<{
+        signature: string,
+    }>,
+
+    verify: (
+        data: Uint8Array,
+        armoredSignature: string,
+        verificationKeys: PublicKey | PublicKey[],
+    ) => Promise<{
+        verified: VERIFICATION_STATUS,
+    }>,
+
+    decryptSessionKey: (
+        data: Uint8Array,
+        decryptionKeys: PrivateKey | PrivateKey[],
+    ) => Promise<SessionKey>,
+
+    decryptArmoredSessionKey: (
+        armoredData: string,
+        decryptionKeys: PrivateKey | PrivateKey[],
+    ) => Promise<SessionKey>,
+
+    decryptKey: (
+        armoredKey: string,
+        passphrase: string,
+    ) => Promise<PrivateKey>,
+
+    decryptAndVerify(
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        verificationKeys: PublicKey | PublicKey[],
+    ): Promise<{
+        data: Uint8Array,
+        verified: VERIFICATION_STATUS,
+    }>,
+
+    decryptAndVerifyDetached(
+        data: Uint8Array,
+        signature: Uint8Array | undefined,
+        sessionKey: SessionKey,
+        verificationKeys?: PublicKey | PublicKey[],
+    ): Promise<{
+        data: Uint8Array,
+        verified: VERIFICATION_STATUS,
+    }>,
+
+    decryptArmored(
+        armoredData: string,
+        decryptionKeys: PrivateKey | PrivateKey[],
+    ): Promise<Uint8Array>,
+
+    decryptArmoredAndVerify: (
+        armoredData: string,
+        decryptionKeys: PrivateKey | PrivateKey[],
+        verificationKeys: PublicKey | PublicKey[],
+    ) => Promise<{
+        data: Uint8Array,
+        verified: VERIFICATION_STATUS,
+    }>,
+
+    decryptArmoredAndVerifyDetached: (
+        armoredData: string,
+        armoredSignature: string,
+        sessionKey: SessionKey,
+        verificationKeys: PublicKey | PublicKey[],
+    ) => Promise<{
+        data: Uint8Array,
+        verified: VERIFICATION_STATUS,
+    }>,
+}

package/src/crypto/openPGPCrypto.ts

@@ -0,0 +1,398 @@
+import { OpenPGPCrypto, PrivateKey, PublicKey, SessionKey, VERIFICATION_STATUS } from './interface';
+import { uint8ArrayToBase64String } from './utils';
+
+/**
+ * Interface matching CryptoProxy interface from client's monorepo:
+ * clients/packages/crypto/lib/proxy/proxy.ts.
+ */
+export interface OpenPGPCryptoProxy {
+    generateKey: (options: { userIDs: { name: string }[], type: 'ecc', curve: 'ed25519Legacy' }) => Promise<PrivateKey>,
+    exportPrivateKey: (options: { privateKey: PrivateKey, passphrase: string | null }) => Promise<string>,
+    importPrivateKey: (options: { armoredKey: string, passphrase: string | null }) => Promise<PrivateKey>,
+    generateSessionKey: (options: { recipientKeys: PrivateKey[] }) => Promise<SessionKey>,
+    encryptSessionKey: (options: SessionKey & { format: 'binary', encryptionKeys?: PublicKey | PublicKey[], passwords?: string[] }) => Promise<Uint8Array>,
+    decryptSessionKey: (options: { armoredMessage?: string, binaryMessage?: Uint8Array, decryptionKeys: PrivateKey | PrivateKey[] }) => Promise<SessionKey | undefined>,
+    encryptMessage: (options: {
+        format?: 'armored' | 'binary',
+        binaryData: Uint8Array,
+        sessionKey?: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKeys?: PrivateKey,
+        detached?: boolean,
+    }) => Promise<{
+        message: string | Uint8Array,
+        signature?: string | Uint8Array,
+    }>,
+    decryptMessage: (options: {
+        format: 'utf8' | 'binary',
+        armoredMessage?: string,
+        binaryMessage?: Uint8Array,
+        armoredSignature?: string,
+        binarySignature?: Uint8Array,
+        sessionKeys?: SessionKey,
+        decryptionKeys?: PrivateKey | PrivateKey[],
+        verificationKeys?: PublicKey | PublicKey[],
+    }) => Promise<{
+        data: Uint8Array | string,
+        // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+        // Web clients are using newer pmcrypto, but CLI is using older version due to build issues with Bun.
+        verified?: VERIFICATION_STATUS,
+        verificationStatus?: VERIFICATION_STATUS,
+    }>,
+    signMessage: (options: {
+        format: 'binary' | 'armored',
+        binaryData: Uint8Array,
+        signingKeys: PrivateKey | PrivateKey[],
+        detached: boolean,
+        signatureContext?: { critical: boolean, value: string },
+    }) => Promise<Uint8Array | string>,
+    verifyMessage: (options: {
+        binaryData: Uint8Array,
+        armoredSignature: string,
+        verificationKeys: PublicKey | PublicKey[],
+    }) => Promise<{
+        // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+        // Web clients are using newer pmcrypto, but CLI is using older version due to build issues with Bun.
+        verified?: VERIFICATION_STATUS,
+        verificationStatus?: VERIFICATION_STATUS,
+    }>,
+}
+
+/**
+ * Implementation of OpenPGPCrypto interface using CryptoProxy from clients
+ * monorepo that must be passed as dependency. In the future, CryptoProxy
+ * will be published separately and this implementation will use it directly.
+ */
+export class OpenPGPCryptoWithCryptoProxy implements OpenPGPCrypto {
+    constructor(private cryptoProxy: OpenPGPCryptoProxy) {
+        this.cryptoProxy = cryptoProxy;
+    }
+
+    generatePassphrase(): string {
+        const value = crypto.getRandomValues(new Uint8Array(32));
+        return uint8ArrayToBase64String(value);
+    }
+
+    async generateSessionKey(encryptionKeys: PrivateKey[]) {
+        return this.cryptoProxy.generateSessionKey({ recipientKeys: encryptionKeys });
+    }
+
+    async encryptSessionKey(sessionKey: SessionKey, encryptionKeys: PublicKey | PublicKey[]) {
+        const keyPacket = await this.cryptoProxy.encryptSessionKey({
+            ...sessionKey,
+            format: 'binary',
+            encryptionKeys,
+        });
+        return {
+            keyPacket
+        };
+    }
+
+    async encryptSessionKeyWithPassword(sessionKey: SessionKey, password: string) {
+        const keyPacket = await this.cryptoProxy.encryptSessionKey({
+            ...sessionKey,
+            format: 'binary',
+            passwords: [password],
+        });
+        return {
+            keyPacket,
+        };
+    }
+
+    async generateKey(passphrase: string) {
+        const privateKey = await this.cryptoProxy.generateKey({
+            userIDs: [{ name: 'Drive key' }],
+            type: 'ecc',
+            curve: 'ed25519Legacy',
+        });
+
+        const armoredKey = await this.cryptoProxy.exportPrivateKey({
+            privateKey,
+            passphrase,
+        });
+
+        return {
+            armoredKey,
+            privateKey,
+        };
+    }
+
+    async encryptArmored(
+        data: Uint8Array,
+        encryptionKeys: PrivateKey[],
+        sessionKey?: SessionKey,
+    ) {
+        const { message: armoredData } = await this.cryptoProxy.encryptMessage({
+            binaryData: data,
+            sessionKey,
+            encryptionKeys,
+        });
+        return {
+            armoredData: armoredData as string,
+        }
+    }
+
+    async encryptAndSign(
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) {
+        const { message: encryptedData } = await this.cryptoProxy.encryptMessage({
+            binaryData: data,
+            sessionKey,
+            signingKeys: signingKey,
+            encryptionKeys,
+            format: 'binary',
+            detached: false,
+        });
+        return {
+            encryptedData: encryptedData as Uint8Array,
+        };
+    }
+
+    async encryptAndSignArmored(
+        data: Uint8Array,
+        sessionKey: SessionKey | undefined,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) {
+        const { message: armoredData } = await this.cryptoProxy.encryptMessage({
+            binaryData: data,
+            encryptionKeys,
+            sessionKey,
+            signingKeys: signingKey,
+            detached: false,
+        });
+        return {
+            armoredData: armoredData as string,
+        };
+    }
+
+    async encryptAndSignDetached(
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) {
+        const { message: encryptedData, signature } = await this.cryptoProxy.encryptMessage({
+            binaryData: data,
+            sessionKey,
+            signingKeys: signingKey,
+            encryptionKeys,
+            format: 'binary',
+            detached: true,
+        });
+        return {
+            encryptedData: encryptedData as Uint8Array,
+            signature: signature as Uint8Array,
+        }
+    }
+
+    async encryptAndSignDetachedArmored(
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        encryptionKeys: PrivateKey[],
+        signingKey: PrivateKey,
+    ) {
+        const { message: armoredData, signature: armoredSignature } = await this.cryptoProxy.encryptMessage({
+            binaryData: data,
+            sessionKey,
+            signingKeys: signingKey,
+            encryptionKeys,
+            detached: true,
+        });
+        return {
+            armoredData: armoredData as string,
+            armoredSignature: armoredSignature as string,
+        }
+    }
+
+    async sign(
+        data: Uint8Array,
+        signingKeys: PrivateKey | PrivateKey[],
+        signatureContext: string,
+    ) {
+        const signature = await this.cryptoProxy.signMessage({
+            binaryData: data,
+            signingKeys,
+            detached: true,
+            format: 'binary',
+            signatureContext: { critical: true, value: signatureContext },
+        });
+        return {
+            signature: signature as Uint8Array,
+        };
+    }
+
+    async signArmored(
+        data: Uint8Array,
+        signingKeys: PrivateKey | PrivateKey[],
+    ) {
+        const signature = await this.cryptoProxy.signMessage({
+            binaryData: data,
+            signingKeys,
+            detached: true,
+            format: 'armored',
+        });
+        return {
+            signature: signature as string,
+        };
+    }
+
+    async verify(
+        data: Uint8Array,
+        armoredSignature: string,
+        verificationKeys: PublicKey | PublicKey[],
+    ) {
+        const { verified, verificationStatus } = await this.cryptoProxy.verifyMessage({
+            binaryData: data,
+            armoredSignature,
+            verificationKeys,
+        });
+        return {
+            // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+            // Proper typing is too complex, it will be removed to support only newer pmcrypto.
+            verified: verified || verificationStatus!,
+        };
+    }
+
+    async decryptSessionKey(
+        data: Uint8Array,
+        decryptionKeys: PrivateKey | PrivateKey[],
+    ) {
+        const sessionKey = await this.cryptoProxy.decryptSessionKey({
+            binaryMessage: data,
+            decryptionKeys,
+        });
+
+        if (!sessionKey) {
+            throw new Error('Could not decrypt session key');
+        }
+
+        return sessionKey;
+    }
+
+    async decryptArmoredSessionKey(
+        armoredData: string,
+        decryptionKeys: PrivateKey | PrivateKey[],
+    ) {
+        const sessionKey = await this.cryptoProxy.decryptSessionKey({
+            armoredMessage: armoredData,
+            decryptionKeys,
+        });
+
+        if (!sessionKey) {
+            throw new Error('Could not decrypt session key');
+        }
+
+        return sessionKey;
+    }
+
+    async decryptKey(
+        armoredKey: string,
+        passphrase: string,
+    ) {
+        const key = await this.cryptoProxy.importPrivateKey({
+            armoredKey,
+            passphrase,
+        });
+        return key;
+    }
+
+    async decryptAndVerify(
+        data: Uint8Array,
+        sessionKey: SessionKey,
+        verificationKeys: PublicKey[],
+    ) {
+        const { data: decryptedData, verified, verificationStatus } = await this.cryptoProxy.decryptMessage({
+            binaryMessage: data,
+            sessionKeys: sessionKey,
+            verificationKeys,
+            format: 'binary',
+        });
+
+        return {
+            data: decryptedData as Uint8Array,
+            // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+            // Proper typing is too complex, it will be removed to support only newer pmcrypto.
+            verified: verified || verificationStatus!,
+        }
+    }
+
+    async decryptAndVerifyDetached(
+        data: Uint8Array,
+        signature: Uint8Array | undefined,
+        sessionKey: SessionKey,
+        verificationKeys?: PublicKey[],
+    ) {
+        const { data: decryptedData, verified, verificationStatus } = await this.cryptoProxy.decryptMessage({
+            binaryMessage: data,
+            binarySignature: signature,
+            sessionKeys: sessionKey,
+            verificationKeys,
+            format: 'binary',
+        });
+
+        return {
+            data: decryptedData as Uint8Array,
+            // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+            // Proper typing is too complex, it will be removed to support only newer pmcrypto.
+            verified: verified || verificationStatus!,
+        }
+    }
+
+    async decryptArmored(
+        armoredData: string,
+        decryptionKeys: PrivateKey | PrivateKey[],
+    ) {
+        const { data } = await this.cryptoProxy.decryptMessage({
+            armoredMessage: armoredData,
+            decryptionKeys,
+            format: 'binary',
+        });
+        return data as Uint8Array;
+    }
+
+    async decryptArmoredAndVerify(
+        armoredData: string,
+        decryptionKeys: PrivateKey | PrivateKey[],
+        verificationKeys: PublicKey | PublicKey[],
+    ) {
+        const { data, verified, verificationStatus } = await this.cryptoProxy.decryptMessage({
+            armoredMessage: armoredData,
+            decryptionKeys,
+            verificationKeys,
+            format: 'binary',
+        });
+
+        return {
+            data: data as Uint8Array,
+            // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+            // Proper typing is too complex, it will be removed to support only newer pmcrypto.
+            verified: verified || verificationStatus!,
+        }
+    }
+
+    async decryptArmoredAndVerifyDetached(
+        armoredData: string,
+        armoredSignature: string,
+        sessionKey: SessionKey,
+        verificationKeys: PublicKey | PublicKey[],
+    ) {
+        const { data, verified, verificationStatus } = await this.cryptoProxy.decryptMessage({
+            armoredMessage: armoredData,
+            armoredSignature,
+            sessionKeys: sessionKey,
+            verificationKeys,
+            format: 'binary',
+        });
+
+        return {
+            data: data as Uint8Array,
+            // pmcrypto 8.3.0 changes `verified` to `verificationStatus`.
+            // Proper typing is too complex, it will be removed to support only newer pmcrypto.
+            verified: verified || verificationStatus!,
+        }
+    }
+}