46 lines
2.3 KiB
Markdown
46 lines
2.3 KiB
Markdown
# GTransfer
|
|
|
|
A self-hosted, end-to-end encrypted file transfer service. The server stores only ciphertext and never has access to encryption keys or plaintext.
|
|
|
|
## How encryption works
|
|
|
|
### Upload
|
|
|
|
1. **Key generation** — the browser generates a random 256-bit AES-GCM key using the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). The key never leaves the browser.
|
|
|
|
2. **Encryption** — the file is encrypted with AES-GCM. A random 96-bit (12-byte) IV is generated for each upload. The IV is prepended to the ciphertext to produce the payload:
|
|
```
|
|
payload = IV (12 bytes) || ciphertext
|
|
```
|
|
|
|
3. **File ID** — the server needs a way to identify the file without knowing the key. The client computes `SHA-256(rawKey)` and uses the hex digest as the file ID. This is a one-way operation — the server cannot reverse it to obtain the key.
|
|
|
|
4. **Upload** — the encrypted payload and file ID are sent to the server. The server stores the ciphertext and records the file ID, name, expiry, and download limit in the database.
|
|
|
|
5. **Share link** — the raw key is base64url-encoded and placed in the [URL fragment](https://developer.mozilla.org/en-US/docs/Web/API/URL/hash):
|
|
```
|
|
https://example.com/download#<base64url(rawKey)>
|
|
```
|
|
Browsers never include the fragment in HTTP requests, so the key is never transmitted to the server.
|
|
|
|
### Download
|
|
|
|
1. **Key extraction** — the browser reads the key from the URL fragment and decodes it from base64url.
|
|
|
|
2. **File lookup** — the client computes `SHA-256(rawKey)` to derive the file ID and fetches the encrypted payload from `/download/<id>/data`.
|
|
|
|
3. **Decryption** — the IV is read from the first 12 bytes of the payload, and the remainder is decrypted with AES-GCM. AES-GCM is authenticated encryption, so any tampering with the ciphertext causes decryption to fail with an authentication error.
|
|
|
|
4. **Download** — the plaintext is written to a `Blob` and the browser is prompted to save it.
|
|
|
|
### Security properties
|
|
|
|
| Property | Detail |
|
|
|---|---|
|
|
| Encryption | AES-256-GCM |
|
|
| IV | 96-bit random, unique per upload |
|
|
| Key derivation | None — key is randomly generated |
|
|
| File ID | SHA-256(rawKey) — server cannot reverse to key |
|
|
| Key transport | URL fragment — never sent to server |
|
|
| Server access | Ciphertext, file metadata, SHA-256 of key only |
|