mirror of
https://github.com/ramvignesh-b/pi-ku.git
synced 2026-05-04 08:56:52 +00:00
refactor: simplify crypto utils
This commit is contained in:
ramvignesh-b
+114
-59
@@ -7,6 +7,7 @@ export interface EncryptedLetter {
|
||||
export interface EncryptedLetterMetadata {
|
||||
encrypted_content: string;
|
||||
encrypted_dek: string;
|
||||
sharingKey?: string | null;
|
||||
}
|
||||
|
||||
export interface EncryptedImageUpload {
|
||||
@@ -21,58 +22,87 @@ interface SealedEnvelope {
|
||||
sharingKey: string;
|
||||
}
|
||||
|
||||
// we use a class here to keep track of instantiations (use 1 and the same DEK per letter content and metadata)
|
||||
// TODO: try refactoring into a pure function for consistency
|
||||
export class CryptoUtils {
|
||||
private dek: CryptoKey = {} as CryptoKey;
|
||||
private static readonly PBKDF2_ITERATIONS = 100_000;
|
||||
private static readonly AES_GCM = { name: "AES-GCM", length: 256 };
|
||||
private dek!: CryptoKey;
|
||||
private static readonly PBKDF2_ITERATIONS = 600_000;
|
||||
// NOTE: https://www.w3.org/TR/webcrypto/#aes-gcm
|
||||
private static readonly AES_ALGO = { name: "AES-GCM", length: 256 };
|
||||
private static readonly IV_BYTE_LENGTH = 12;
|
||||
|
||||
// Generates a fresh Data Encryption Key (DEK)
|
||||
// NOTE: this MUST be called once, per letter, for all operations in a session to a fresh Data Encryption Key (DEK)
|
||||
async initialize() {
|
||||
this.dek = await crypto.subtle.generateKey(CryptoUtils.AES_GCM, true, [
|
||||
this.dek = await crypto.subtle.generateKey(CryptoUtils.AES_ALGO, true, [
|
||||
"encrypt",
|
||||
"decrypt",
|
||||
]);
|
||||
}
|
||||
|
||||
// base64 conversion for transit
|
||||
toBase64 = (buf: Uint8Array): string =>
|
||||
btoa(buf.reduce((s, b) => s + String.fromCharCode(b), ""));
|
||||
private toBase64 = (buffer: Uint8Array): string => {
|
||||
// convert buffer to raw string
|
||||
let binaryFileString = "";
|
||||
for (let i = 0; i < buffer.byteLength; i++) {
|
||||
binaryFileString += String.fromCharCode(buffer[i]);
|
||||
}
|
||||
return btoa(binaryFileString);
|
||||
};
|
||||
|
||||
fromBase64 = (b64: string): Uint8Array<ArrayBuffer> => {
|
||||
const str = atob(b64);
|
||||
const arr = new Uint8Array(str.length);
|
||||
for (let i = 0; i < str.length; i++) arr[i] = str.charCodeAt(i);
|
||||
private fromBase64 = (b64String: string): Uint8Array<ArrayBuffer> => {
|
||||
const decodedString = atob(b64String);
|
||||
const arr = new Uint8Array(decodedString.length);
|
||||
for (let i = 0; i < decodedString.length; i++)
|
||||
arr[i] = decodedString.charCodeAt(i);
|
||||
return arr;
|
||||
};
|
||||
|
||||
// bundle IV + data into a single base64 string
|
||||
packWithIv = (iv: Uint8Array, data: ArrayBuffer): string => {
|
||||
const packed = new Uint8Array(iv.length + data.byteLength);
|
||||
packed.set(iv);
|
||||
packed.set(new Uint8Array(data), iv.length);
|
||||
return this.toBase64(packed);
|
||||
// Required structure: [12 bytes IV][Cipher text][16 bytes Auth Tag]
|
||||
// NOTE: Web Crypto API auto appends the auth tag, so we focus on IV and cipher
|
||||
private packWithIv = (iv: Uint8Array, ciphertext: ArrayBuffer): string => {
|
||||
// create a buffer large enough to hold both iv and cipher text (12 + x bytes)
|
||||
const combinedPayload = new Uint8Array(
|
||||
CryptoUtils.IV_BYTE_LENGTH + ciphertext.byteLength,
|
||||
);
|
||||
|
||||
// place the iv at the start
|
||||
combinedPayload.set(iv, 0);
|
||||
|
||||
// place the ciphertext after the iv
|
||||
combinedPayload.set(new Uint8Array(ciphertext), CryptoUtils.IV_BYTE_LENGTH);
|
||||
|
||||
// convert the buffer to Base64 for transit
|
||||
return this.toBase64(combinedPayload);
|
||||
};
|
||||
|
||||
unpackWithIv = (
|
||||
b64: string,
|
||||
): [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>] => {
|
||||
const buf = this.fromBase64(b64);
|
||||
return [new Uint8Array(buf.buffer, 0, 12), new Uint8Array(buf.buffer, 12)];
|
||||
// For decryption: extracts the IV and the data from the base64 string, easy because we know the size of iv already.
|
||||
private unpackWithIv = (
|
||||
encodedString: string,
|
||||
): { iv: Uint8Array<ArrayBuffer>; ciphertext: Uint8Array<ArrayBuffer> } => {
|
||||
// decode from base64 to array buffer
|
||||
const fullBuffer = this.fromBase64(encodedString);
|
||||
|
||||
// extract first 12 bytes for iv
|
||||
const iv = fullBuffer.slice(0, CryptoUtils.IV_BYTE_LENGTH);
|
||||
// extract rest for cipher text
|
||||
const ciphertext = fullBuffer.slice(CryptoUtils.IV_BYTE_LENGTH);
|
||||
|
||||
return { iv: new Uint8Array(iv), ciphertext: new Uint8Array(ciphertext) };
|
||||
};
|
||||
|
||||
/**
|
||||
* Derives a Key Bundle (MasterKey + AuthHash) from a password + email.
|
||||
* Derive a key bundle (Masterkey + authHash) from email + (plain) password combo
|
||||
* WHY?: This is much secure than relying on server to hash and store the password. Also ensures absolute 0 knowledge
|
||||
*/
|
||||
public static async deriveKeyBundle(
|
||||
password: string,
|
||||
email: string,
|
||||
): Promise<{ masterKey: CryptoKey; authHash: string }> {
|
||||
const enc = new TextEncoder();
|
||||
const salt = enc.encode(email.toLowerCase());
|
||||
const encoder = new TextEncoder();
|
||||
const salt = encoder.encode(email.toLowerCase());
|
||||
|
||||
const baseKey = await crypto.subtle.importKey(
|
||||
"raw",
|
||||
enc.encode(password),
|
||||
encoder.encode(password),
|
||||
"PBKDF2",
|
||||
false,
|
||||
["deriveBits", "deriveKey"],
|
||||
@@ -89,53 +119,67 @@ export class CryptoUtils {
|
||||
512,
|
||||
);
|
||||
|
||||
// first 256 bits for MasterKey, last 256 bits for AuthHash
|
||||
// first 256 bits for masterkey, last 256 bits for authHash (password sent in REST)
|
||||
const masterKeyBytes = masterSeed.slice(0, 32);
|
||||
const authHashBytes = masterSeed.slice(32, 64);
|
||||
|
||||
// Create the MasterKey for client-side encryption
|
||||
// Create the masterkey for client-side encryption
|
||||
const masterKey = await crypto.subtle.importKey(
|
||||
"raw",
|
||||
masterKeyBytes,
|
||||
CryptoUtils.AES_GCM,
|
||||
CryptoUtils.AES_ALGO,
|
||||
false,
|
||||
["encrypt", "decrypt", "wrapKey", "unwrapKey"],
|
||||
);
|
||||
|
||||
// Create the hex AuthHash for server-side verification
|
||||
const authHash = Array.from(new Uint8Array(authHashBytes))
|
||||
.map((b) => b.toString(16).padStart(2, "0"))
|
||||
.join("");
|
||||
// convert bytes in to hex string
|
||||
let authHash = "";
|
||||
const authHashBuffer = new Uint8Array(authHashBytes);
|
||||
|
||||
for (let i = 0; i < authHashBuffer.byteLength; i++) {
|
||||
// we force every bytes converted to string to be min 2 chars (otherwise 00 0a will be just a and not "000a")
|
||||
authHash += authHashBuffer[i].toString(16).padStart(2, "0");
|
||||
}
|
||||
|
||||
return { masterKey, authHash };
|
||||
}
|
||||
|
||||
/*
|
||||
* Envelope Encryption - Decryption
|
||||
* WHY?: for guest access where we don't have to share the masterkey just the dek.
|
||||
* This way, raw dek never leaves browser (db stores the encrypted version)
|
||||
*/
|
||||
|
||||
// encrypt the plaintext with a DEK and then encrypt (wrap) that DEK with the user's masterkey.
|
||||
private async sealEnvelope(
|
||||
input: Uint8Array,
|
||||
masterKey: CryptoKey,
|
||||
): Promise<SealedEnvelope> {
|
||||
if (!this.dek) {
|
||||
throw new Error("DEK is not available (forgot to .initialize()?)");
|
||||
}
|
||||
const plainBytes = new Uint8Array(input);
|
||||
const contentIV = crypto.getRandomValues(new Uint8Array(12));
|
||||
const dekIV = crypto.getRandomValues(new Uint8Array(12));
|
||||
const contentIv = crypto.getRandomValues(new Uint8Array(12));
|
||||
const dekIv = crypto.getRandomValues(new Uint8Array(12));
|
||||
|
||||
const ciphertext = await crypto.subtle.encrypt(
|
||||
{ name: "AES-GCM", iv: contentIV },
|
||||
{ name: CryptoUtils.AES_ALGO.name, iv: contentIv },
|
||||
this.dek,
|
||||
plainBytes,
|
||||
);
|
||||
|
||||
// wrap the DEK with the Master Key (for self/owner access)
|
||||
// wrap the DEK with the Master Key (for self access)
|
||||
const wrappedDek = await crypto.subtle.wrapKey("raw", this.dek, masterKey, {
|
||||
name: "AES-GCM",
|
||||
iv: dekIV,
|
||||
name: CryptoUtils.AES_ALGO.name,
|
||||
iv: dekIv,
|
||||
});
|
||||
|
||||
// export raw DEK for the share URL (recipient access, no master key needed)
|
||||
const rawDek = await crypto.subtle.exportKey("raw", this.dek);
|
||||
|
||||
return {
|
||||
encryptedContent: this.packWithIv(contentIV, ciphertext),
|
||||
encrypted_dek: this.packWithIv(dekIV, wrappedDek),
|
||||
encryptedContent: this.packWithIv(contentIv, ciphertext),
|
||||
encrypted_dek: this.packWithIv(dekIv, wrappedDek),
|
||||
sharingKey: this.toBase64(new Uint8Array(rawDek)),
|
||||
};
|
||||
}
|
||||
@@ -146,20 +190,21 @@ export class CryptoUtils {
|
||||
encrypted_dek: string,
|
||||
masterKey: CryptoKey,
|
||||
): Promise<Uint8Array<ArrayBuffer>> {
|
||||
const [dekIv, wrappedDek] = this.unpackWithIv(encrypted_dek);
|
||||
const { iv: dekIv, ciphertext: wrappedDek } =
|
||||
this.unpackWithIv(encrypted_dek);
|
||||
const dek = await crypto.subtle.unwrapKey(
|
||||
"raw",
|
||||
wrappedDek,
|
||||
masterKey,
|
||||
{ name: "AES-GCM", iv: dekIv },
|
||||
CryptoUtils.AES_GCM,
|
||||
{ name: CryptoUtils.AES_ALGO.name, iv: dekIv },
|
||||
CryptoUtils.AES_ALGO,
|
||||
false,
|
||||
["decrypt"],
|
||||
);
|
||||
|
||||
const [contentIv, ciphertext] = this.unpackWithIv(encryptedContent);
|
||||
const { iv: contentIv, ciphertext } = this.unpackWithIv(encryptedContent);
|
||||
const plainBytes = await crypto.subtle.decrypt(
|
||||
{ name: "AES-GCM", iv: contentIv },
|
||||
{ name: CryptoUtils.AES_ALGO.name, iv: contentIv },
|
||||
dek,
|
||||
ciphertext,
|
||||
);
|
||||
@@ -175,14 +220,14 @@ export class CryptoUtils {
|
||||
const dek = await crypto.subtle.importKey(
|
||||
"raw",
|
||||
dekBytes,
|
||||
CryptoUtils.AES_GCM,
|
||||
CryptoUtils.AES_ALGO,
|
||||
false,
|
||||
["decrypt"],
|
||||
);
|
||||
|
||||
const [contentIv, ciphertext] = this.unpackWithIv(encryptedContent);
|
||||
const { iv: contentIv, ciphertext } = this.unpackWithIv(encryptedContent);
|
||||
const plainBytes = await crypto.subtle.decrypt(
|
||||
{ name: "AES-GCM", iv: contentIv },
|
||||
{ name: CryptoUtils.AES_ALGO.name, iv: contentIv },
|
||||
dek,
|
||||
ciphertext,
|
||||
);
|
||||
@@ -199,6 +244,7 @@ export class CryptoUtils {
|
||||
): Promise<EncryptedLetter> {
|
||||
const { encryptedContent, encrypted_dek, sharingKey } =
|
||||
await this.sealEnvelope(new TextEncoder().encode(plaintext), masterKey);
|
||||
|
||||
return { encrypted_content: encryptedContent, encrypted_dek, sharingKey };
|
||||
}
|
||||
|
||||
@@ -211,6 +257,7 @@ export class CryptoUtils {
|
||||
encrypted_dek,
|
||||
masterKey,
|
||||
);
|
||||
|
||||
return new TextDecoder().decode(bytes);
|
||||
}
|
||||
|
||||
@@ -222,18 +269,20 @@ export class CryptoUtils {
|
||||
encrypted_content,
|
||||
sharingKey,
|
||||
);
|
||||
|
||||
return new TextDecoder().decode(bytes);
|
||||
}
|
||||
|
||||
public async encryptMetadata(
|
||||
metadata: Record<string, any>,
|
||||
masterKey: CryptoKey,
|
||||
): Promise<EncryptedLetter> {
|
||||
): Promise<EncryptedLetterMetadata> {
|
||||
const { encryptedContent, encrypted_dek, sharingKey } =
|
||||
await this.sealEnvelope(
|
||||
new TextEncoder().encode(JSON.stringify(metadata)),
|
||||
masterKey,
|
||||
);
|
||||
|
||||
return { encrypted_content: encryptedContent, encrypted_dek, sharingKey };
|
||||
}
|
||||
|
||||
@@ -246,6 +295,7 @@ export class CryptoUtils {
|
||||
encrypted_metadata.encrypted_dek,
|
||||
masterKey,
|
||||
);
|
||||
|
||||
return JSON.parse(new TextDecoder().decode(bytes));
|
||||
}
|
||||
|
||||
@@ -257,6 +307,7 @@ export class CryptoUtils {
|
||||
encrypted_content,
|
||||
sharingKey,
|
||||
);
|
||||
|
||||
return JSON.parse(new TextDecoder().decode(bytes));
|
||||
}
|
||||
|
||||
@@ -283,12 +334,13 @@ export class CryptoUtils {
|
||||
masterKey: CryptoKey,
|
||||
): Promise<string> {
|
||||
const encryptedBytes = new Uint8Array(await encryptedBlob.arrayBuffer());
|
||||
const bytes = await this.openEnvelope(
|
||||
const plainBytes = await this.openEnvelope(
|
||||
this.toBase64(encryptedBytes),
|
||||
encrypted_dek,
|
||||
masterKey,
|
||||
);
|
||||
return URL.createObjectURL(new Blob([bytes]));
|
||||
|
||||
return URL.createObjectURL(new Blob([plainBytes]));
|
||||
}
|
||||
|
||||
public async decryptImageWithSharingKey(
|
||||
@@ -296,28 +348,31 @@ export class CryptoUtils {
|
||||
sharingKey: string,
|
||||
): Promise<string> {
|
||||
const encryptedBytes = new Uint8Array(await encryptedBlob.arrayBuffer());
|
||||
const bytes = await this.openEnvelopeWithSharingKey(
|
||||
const plainBytes = await this.openEnvelopeWithSharingKey(
|
||||
this.toBase64(encryptedBytes),
|
||||
sharingKey,
|
||||
);
|
||||
return URL.createObjectURL(new Blob([bytes]));
|
||||
|
||||
return URL.createObjectURL(new Blob([plainBytes]));
|
||||
}
|
||||
|
||||
// Re-derives the sharing key (raw DEK) on demand (browser only, not sent to server).
|
||||
// derive raw DEK on demand (browser only, not sent to server) for guest access
|
||||
public async extractSharingKey(
|
||||
encrypted_dek: string,
|
||||
masterKey: CryptoKey,
|
||||
): Promise<string> {
|
||||
const [dekIv, wrappedDek] = this.unpackWithIv(encrypted_dek);
|
||||
const { iv: dekIv, ciphertext: wrappedDek } =
|
||||
this.unpackWithIv(encrypted_dek);
|
||||
const rawDek = await crypto.subtle.unwrapKey(
|
||||
"raw",
|
||||
wrappedDek,
|
||||
masterKey,
|
||||
{ name: "AES-GCM", iv: dekIv },
|
||||
CryptoUtils.AES_GCM,
|
||||
{ name: CryptoUtils.AES_ALGO.name, iv: dekIv },
|
||||
CryptoUtils.AES_ALGO,
|
||||
true,
|
||||
["decrypt"],
|
||||
);
|
||||
|
||||
return this.toBase64(
|
||||
new Uint8Array(await crypto.subtle.exportKey("raw", rawDek)),
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user