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에 남겨주세요.