browser-file-cryptoにストリーミング暗号化が追加されました.

1月初めにbrowser-file-cryptoをオープンソースとして公開した際、 最後に「ストリーミング暗号化をサポートする予定」とお伝えしていました。 その機能がv1.1で追加されました。

なぜストリーミング暗号化が必要だったのか？

従来の方式はファイル全体をメモリに読み込んで暗号化していました。 500MBのファイルを暗号化すると、メモリに500MB以上が使われます。小さなファイルなら問題ないですが、GB単位のファイルはブラウザタブがクラッシュする可能性があります。

TimeFileでは特に数十～数百GB以上のファイルアップロードをサポートしているため、この問題を直接経験しました。 セキュア共有機能を使うには暗号化が必要ですが、大容量ファイルでは暗号化自体ができなかったのです。

解決策はチャンク単位で少しずつ処理することです。64KBずつだけメモリに読み込んで暗号化すれば、ファイルサイズに関係なくメモリ使用量が一定に保たれます。

何が追加されたのか？

ストリーミング暗号化/復号化関数

GB単位のファイルもメモリの心配なく暗号化できます。

1import { encryptFileStream, decryptFileStream } from '@time-file/browser-file-crypto';
2
3const encrypted = await encryptFileStream(largeFile, {
4  password: 'secret',
5  chunkSize: 64 * 1024,  // デフォルト: 64KB
6  onProgress: ({ processedBytes, totalBytes, progress }) => {
7    console.log(`${progress}% 完了`);
8  }
9});

自動モード（ハイブリッド）— おすすめ！

ファイルサイズに応じて自動的に最適な方式を選択します。小さなファイルは従来の方式（より高速）、大きなファイルはストリーミング方式（メモリ効率）を使用します。

1import { encryptFileAuto } from '@time-file/browser-file-crypto';
2
3const encrypted = await encryptFileAuto(file, {
4  password: 'secret',
5  autoStreaming: true,
6  streamingThreshold: 100 * 1024 * 1024  // 100MB（デフォルト）
7});
8// 100MB以下: 従来の方式（より高速）
9// 100MB超: ストリーミング方式（メモリ効率）

ストリーミングダウンロード + 復号化

大容量ファイルをダウンロードしながら同時に復号化できます。

1import { downloadAndDecryptStream } from '@time-file/browser-file-crypto';
2
3await downloadAndDecryptStream(url, {
4  fileName: 'large-file.zip',
5  password: 'secret',
6  onProgress: ({ phase, processedBytes }) => {
7    // phase: 'downloading' | 'decrypting' | 'complete'
8  }
9});

下位互換性

• decryptFile()がストリーミングフォーマットを自動認識します
• 既存コードを変更せずにストリーミング暗号化されたファイルを復号化できます
• getEncryptionType()の戻り値拡張: 'password-stream'、'keyfile-stream'を追加

TimeFileではどのように使っているのか？

TimeFileではFeature Flagでストリーミング暗号化機能を制御しています。 セキュア共有機能でencryptFileAutoを使用し、autoStreaming: trueオプションで大容量ファイルを自動処理しています。 これにより100GBのファイルもブラウザで暗号化できるようになりました。 ユーザーはファイルサイズを気にせず、ただアップロードするだけで大丈夫です。

技術的な詳細

ストリーミングファイルフォーマット

従来のフォーマットと区別するために新しいマーカーを使用しています。

• 0x11: パスワードベースストリーミング（ヘッダー34バイト）
• 0x12: キーファイルベースストリーミング（ヘッダー18バイト）

チャンク別独立認証

各64KBチャンクにAES-GCM認証タグ（16バイト）が付きます。

• ファイルの一部が破損していても即座に検出可能
• ファイル全体を復号化する前に整合性を検証可能
• 最初のチャンク失敗 → INVALID_PASSWORDまたはINVALID_KEYFILE
• 以降のチャンク失敗 → DECRYPTION_FAILED（データ破損）

IV導出方式

各チャンクは固有のIV（Initialization Vector）を使用する必要があります。AES-GCMは同じ鍵で同一のIVを再使用してはいけないからです。

1chunk_iv = base_iv XOR chunk_index

• base_iv: ヘッダーに保存された12バイトのランダム値
• chunk_index: 0, 1, 2, 3, ...
• XOR演算でチャンクごとに異なるIVを生成

ブラウザサポート

ストリーミング暗号化はTransformStream APIを使用しています。

• Chrome 67+
• Firefox 102+
• Safari 14.1+
• Edge 79+

2020年以降にリリースされたブラウザはほとんど対応しており、Node.js 18以上でも使用できます。

アップデート方法

1npm install @time-file/browser-file-crypto@latest

1pnpm add @time-file/browser-file-crypto@latest

今後の予定

Web Workerサポートを検討しています。現在はメインスレッドで暗号化しているため、大きなファイルを処理する時にUIが一瞬止まることがあります。

リンク

- npm: https://www.npmjs.com/package/@time-file/browser-file-crypto - GitHub: https://github.com/Time-File/browser-file-crypto - ストリーミングドキュメント: docs/streaming.md フィードバックやバグレポートはGitHub Issuesにお願いします。