diff --git a/docs/index.md b/docs/index.md index d0a69b7..2482312 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,6 +22,7 @@ Information about the parts of the WROLPi interface. * [Files](modules/files/index.md) * [Videos](modules/videos/index.md) + * [Encrypted Cookies](modules/videos/cookies.md) * [Archives](modules/archives/index.md) * [Map](modules/map/index.md) * [Zim](modules/zim/index.md) diff --git a/docs/modules/videos/cookies-locked.png b/docs/modules/videos/cookies-locked.png new file mode 100644 index 0000000..902db9c Binary files /dev/null and b/docs/modules/videos/cookies-locked.png differ diff --git a/docs/modules/videos/cookies-txt-extension.png b/docs/modules/videos/cookies-txt-extension.png new file mode 100644 index 0000000..773bdeb Binary files /dev/null and b/docs/modules/videos/cookies-txt-extension.png differ diff --git a/docs/modules/videos/cookies-txt-firefox.png b/docs/modules/videos/cookies-txt-firefox.png new file mode 100644 index 0000000..3f136ff Binary files /dev/null and b/docs/modules/videos/cookies-txt-firefox.png differ diff --git a/docs/modules/videos/cookies-unlock.png b/docs/modules/videos/cookies-unlock.png new file mode 100644 index 0000000..e7c067b Binary files /dev/null and b/docs/modules/videos/cookies-unlock.png differ diff --git a/docs/modules/videos/cookies-upload.png b/docs/modules/videos/cookies-upload.png new file mode 100644 index 0000000..53e8f84 Binary files /dev/null and b/docs/modules/videos/cookies-upload.png differ diff --git a/docs/modules/videos/cookies.md b/docs/modules/videos/cookies.md new file mode 100644 index 0000000..77f240d --- /dev/null +++ b/docs/modules/videos/cookies.md @@ -0,0 +1,166 @@ +# Encrypted Cookies + +WROLPi supports encrypted cookie storage for downloading videos from sites that require +authentication. Cookies are encrypted at rest and only decrypted to memory. + +## Warning! "Use as a Last Resort" + +Using cookies to download videos may violate the terms of service of some websites. +Your account could be rate-limited, blocked, or banned. WROLPi is not responsible +for any consequences of using this feature. Only use cookies when other download +methods fail. + +## Why Use Cookies? + +Some video sites require authentication to: + +- Access age-restricted content +- Download subscriber-only videos +- Avoid rate limiting for logged-in users +- Access private or unlisted content + +## Copying Cookies from Your Browser + +To use this feature, you need to copy cookies from a browser where you're logged +into the video site. The easiest method is using a browser extension. + +### Recommended Browser Extensions + +#### cookies.txt (Chrome/Brave/Edge) + +1. Install [cookies.txt](https://chrome.google.com/webstore/detail/cookiestxt/njabckikapfpffapmjgojcnbfjonfjfg) from the Chrome Web Store +2. Navigate to the video site and log in +3. Click the extension icon +4. Click **Copy** to copy the cookies to your clipboard + +![cookies.txt extension](cookies-txt-extension.png) + +#### cookies.txt (Firefox) + +1. Install [cookies.txt](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/) from Firefox Add-ons +2. Navigate to the video site and log in +3. Click the extension icon +4. Click **Copy** to copy the cookies to your clipboard + +![cookies.txt Firefox extension](cookies-txt-firefox.png) + +## Uploading Encrypted Cookies + +Once you have exported your cookies: + +1. Navigate to **Videos > Settings** +2. Scroll to the **Encrypted Cookies** section +3. Paste your cookie file contents into the text area +4. Enter a password (minimum 8 characters) +5. Click **Encrypt & Save** + +![Upload encrypted cookies](cookies-upload.png) + +Your cookies are now encrypted and stored securely. + +## Unlocking Cookies for Downloads + +Cookies remain locked by default. To use them for downloading: + +1. Navigate to **Videos > Settings** +2. In the **Encrypted Cookies** section, enter your password +3. Click **Unlock** + +![Unlock cookies](cookies-unlock.png) + +Once unlocked: + +- Cookies remain available in memory until locked or system restart +- All video downloads will automatically use the cookies +- The cookies indicator shows "Unlocked" status + +## Locking Cookies + +To clear cookies from memory: + +1. Navigate to **Videos > Settings** +2. Click **Lock** in the Encrypted Cookies section + +This immediately clears the decrypted cookies from memory. They remain encrypted +on disk and can be unlocked again with your password. + +![Locked cookies](cookies-locked.png) + +## Deleting Cookies + +To permanently remove stored cookies: + +1. Navigate to **Videos > Settings** +2. Click **Delete** in the Encrypted Cookies section +3. Confirm the deletion + +This removes the encrypted cookie file. You'll need to re-export and upload cookies +if you want to use them again. + +## Troubleshooting + +### Wrong Password + +If you enter an incorrect password when unlocking, you'll see an error message. +The encrypted cookies are not modified. Try again with the correct password. + +### Cookies Expired + +Cookies have expiration dates set by the website. If downloads start failing +after cookies worked previously: + +1. Log into the video site in your browser +2. Export fresh cookies using your browser extension +3. Upload and encrypt the new cookies (no need to delete the old cookies, they will be replaced) + +### Download Still Fails + +If downloads fail even with unlocked cookies: + +- Verify you copied cookies while logged in +- Close the browser window immediately after copying cookies to prevent them from being replaced +- Check that you copied cookies for the correct domain +- Try a different browser or clear cookies and re-authenticate +- Some sites may require additional authentication steps + +## File Locations + +| Item | Location | +|------|----------| +| Encrypted cookies | `{media_directory}/config/cookies.txt.enc` | +| Temporary files | `/dev/shm/w_*.tmp` (RAM-based) | + +## Security Details + +WROLPi implements several security measures to protect your cookies: + +| Feature | Implementation | +|---------|----------------| +| **Encryption Algorithm** | Fernet (AES-128-CBC + HMAC-SHA256) | +| **Key Derivation** | PBKDF2-SHA256 with 480,000 iterations | +| **Salt** | 16 bytes random per encryption | +| **Password Minimum** | 8 characters | +| **Storage Location** | Encrypted file only; never plaintext on disk | +| **Memory Storage** | RAM-based temporary files (`/dev/shm`) | +| **Temp File Permissions** | `0o600` (owner-only) | +| **Secure Deletion** | Overwrite with zeros before unlinking | + +### How Encryption Works + +When you upload cookies: + +1. A random 16-byte salt is generated +2. Your password is combined with the salt using PBKDF2-SHA256 (480,000 iterations) +3. The derived key encrypts your cookies using Fernet +4. The encrypted data is stored as `cookies.txt.enc` in your config directory +5. Your password is never stored + +When you unlock cookies for downloading: + +1. You provide your password +2. The salt is extracted from the encrypted file +3. Your password regenerates the encryption key +4. Cookies are decrypted to shared memory (not disk) +5. Each download gets a unique temporary file in `/dev/shm` (RAM) +6. Temporary files are overwritten with zeros and deleted after use + diff --git a/docs/modules/videos/index.md b/docs/modules/videos/index.md index 61d0c3c..a2f2f30 100644 --- a/docs/modules/videos/index.md +++ b/docs/modules/videos/index.md @@ -37,10 +37,6 @@ video from the WROLPi channel, then your video will be stored in `videos/WROLPi` * The file format the video will be encapsulated in. * `mp4` is the most universally compatible (but proprietary). * `mkv` is an open-standard media format. -* **Use Browser Profile** - * A browser profile is a set of cookies and settings that are used to download videos. This is useful for - downloading videos from sites that require authentication or have other restrictions. - See [Browser Profiles](#browser-profiles) * **Channel Tag** * The selected Tag will be applied to any new Channel created in the process of downloading these videos. The Channel will be placed in the respective tag directory in the `videos` directory. @@ -67,30 +63,16 @@ Behavior when downloading videos can be configured in the `Videos > Settings` pa * Download the thumbnail for the video, if available. * **Extra yt-dlp Arguments** * The text here will be split by spaces and passed as extra arguments to yt-dlp. -* **Browser Profile** - * Shows the browser profiles available to the `wrolpi` user. This is passed as the `--cookies-from-browser` argument - to yt-dlp. -* **Always Use Browser Profile** - * Will download videos using `--cookies-from-browser` always. This is not recommended! +* **Sleep Between Requests** + * Instructs yt-dlp to sleep between metadata requests. Helps reduce potential throttling. +* **User Agent** + * The browser identity sent with requests. **If using encrypted cookies, select "Use Current Browser" to match the browser your cookies came from.** -## How to Use Browser Profiles +## Authentication for Downloads -Downloading videos that require authentication or have other restrictions can be done using a browser profile. This is -done by logging in as the `wrolpi` user, and authenticating in the browser to the site you want to download from. - -### Steps to use a browser profile: - -1. Boot your Raspberry Pi. -2. Log in as your user (possibly `pi`) -3. Open the terminal, change the password of the wrolpi user: - * `sudo passwd wrolpi` -4. Log out of your user using **Menu** > **Logout** > **Logout** -5. Select the `wrolpi` user in the dropdown. -6. Launch a browser (Chromium or Firefox) and log in to the site you want to download from. -7. Navigate to your WROLPi app, you should see the browser profile you just created in `Videos > Settings` -8. Select the browser profile you just created in `Videos > Settings` and click **Save**. - -You can now enable **Use Browser Profile** in the download modal. +Some video sites require authentication to access age-restricted, subscriber-only, or private content. +WROLPi supports [Encrypted Cookies](cookies.md) for authentication. Export cookies from your browser +and upload them encrypted to WROLPi. ## Download Channels/Playlists diff --git a/docs/modules/videos/videos-settings.png b/docs/modules/videos/videos-settings.png index d1b4114..3e92b28 100644 Binary files a/docs/modules/videos/videos-settings.png and b/docs/modules/videos/videos-settings.png differ