idk/i2p.plugins.firefox
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

add docs

Browse Source
This commit is contained in:
idk
2022-12-31 20:00:56 +00:00
parent 8acde05618
commit a06fe41b25
5 changed files with 329 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
docs/BUILD.md Normal file
View File

@ -0,0 +1,228 @@
# Building
## Build Dependencies
You will need `ant` and java `java` and for building the jar. You will need
`jpackage` for many of the potential build targets. I've been using Java 18
on Debian mostly, on Debian and Ubuntu, install the dependencies with:
```sh
sudo apt-get install openjdk-18* ant
```
Some of the targets use scripts written in Go to help generate resources. If
you want to update the profiles, you will need them. To install Go on Debian
and Ubuntu:
```sh
sudo apt-get install golang-go
```
Add `$HOME/go/bin` to your `$PATH` so `ant` can find Go applications.
`export PATH=$PATH:$HOME/go/bin`
Then use Go to download the applications you need and add them to `$HOME/go/bin`.
If you want to build the Chromium profiles you will need a Go application
called `crx3` which is used to interact with the Chrome app store to download
and update extensions.
```sh
go install github.com/mediabuyerbot/go-crx3/crx3@latest
```
Another Go application, called `amo-version`, is used to fetch extensions from addons.mozilla.org.
Like the Chrome profiles, generating the Firefox profiles requires this application. If you don't
want to update the profiles, you don't need it.
```sh
go install github.com/eyedeekay/amo-version@latest
```
One last Go application, called `dzip` is used to generate zip files deterministically for
redistribution.
```sh
go install github.com/delicb/dzip@latest
```
If you don't want to use it, you can work around it by creating a file called
`dzip` in `/usr/local/bin/dzip` and adding the contents:
```sh
#! /usr/bin/env sh
zip -r $@
```
This will break deterministic builds, but for testing it will continue to work. More elaborate
scripts or other deterministic zip utilities can be easily substituted in by placing them
in the `$PATH` under the name `dzip`.
For Fedora, use Yum, for Arch use pacman or something else but make sure to tell everyone
about it. Once you have that installed, when building, make sure to add `$GOPATH/bin/`
to your `$PATH`.
```sh
export PATH=$PATH:$HOME/go/bin
```
Will almost always work.
## Building
This is not actually a plugin yet, but it will be soon. The important bit is the jar.
To generate that, you can either generate the full plugin, which will not work but
produces the jar as a by-product, or you can:
```sh
ant jar
```
To build just the jar. You'll know it worked if you can:
```sh
java -cp ./src/build/i2pfirefox.jar net.i2p.i2pfirefox.I2PFirefox
```
and a new Firefox instance comes up with a fresh profile, ready-to-use for I2P browsing.
The cooler thing you can do with it is add it to an I2P distribution and somewhere in it,
add a UI element that triggers something along the lines of this:
```java
// Firefox Example
if (i2pIsRunning()) {
logger.warning("I2P is already running");
System.out.println("I2PFirefox");
I2PFirefox i2pFirefox = new I2PFirefox();
i2pFirefox.launch();
}
```
```java
// Chromium Example
if (i2pIsRunning()) {
logger.warning("I2P is already running");
System.out.println("I2PChromium");
I2PChromium i2pChromium = new I2PChromium();
i2pChromium.launch();
}
```
```java
// Auto-Select Example, chooses Firefox first, then Chromium
if (i2pIsRunning()) {
logger.warning("I2P is already running");
System.out.println("I2PBrowser");
I2PBrowser i2pBrowser = new I2PBrowser();
/*
* toggle chromium to the top of the order by doing:
I2PBrowser.chromiumFirst = true;
*
*/
i2pBrowser.launch(privateBrowsing);
}
```
to add a browser management tool to it.
## Browser Discovery Methods
This tool looks for browsers on the host system, creates a workspace to use for I2P
purposes, and launches the browser inside of that workspace. The details of the
workspace vary from browser to browser but roughly corresponds to a browser profile.
In order to be successful this tool uses 3 main types of browser discovery methods,
in this order:
1. "Local" discovery, where a browser is in a subdirectory of the directory where you
ran the launcher. This will only happen if the user unpacked a portable browser into
the same directory where they ran the launcher.
2. "Path-Based" discovery, where it scans common browser installation directories
until it finds one which it can use. On Unix, it simply scans the directories on the
`PATH` for a browser it knows about. On Windows, default paths to browser install
directories are hard-coded and included in the binary. This is what usually happens.
3. "System-Based" discovery, where it defers to the host system to make a choice
about the browser and counts on browser vendors to honor the system proxy environment
variables. This is a catch-all solution which works with most browsers, but does
not apply any customizations.
There is a little subtlety here though.
- The path to Edgium on Windows will **always** resolve during path-based discovery,
resulting in a positive test for Chromium when launching the browser in auto-select
mode. So Windows will never reach stage 3 unless expressly forced to. If Firefox or
a variant is installed, it will be chosen before Edgium unless directed otherwise.
- Even though it will launch you into Edgium if it has no other choice, I recommend
you do not use it. Edgium will in a constant, incessant way try to induce you to
share your behavior with Microsoft. If you try to resist this, it negatively affects
the performance of the browser. Google also does this with Chrome, ant this negatively
affects Chrome performance too, but less than with Edgium. TL:DR Edgium sucks and is
pointless and terrible. Literally any other browser would be better.
- Linux is unaware of a Tor Browser path because Tor Browser is rarely, if ever,
installed on-path. What is on path is virtually always a wrapper for Tor Browser
which is installed either as the main user or it's own user. Linux will only use
Tor Browser if it's discovered in "Local" mode. To set this up automatically, you
can `cd` to the `I2P` directory where you unpacked the `.tar.gz` file, and run the
`./lib/torbrowser.sh` script from there.
- I really only test Phase 3 with Dillo and Edgium. **YMMV.**
## Usability vs Strict
This is basically a profile-management tool geared toward minimizing the
differences between browser users which are passively discernible while
they are browsing I2P. It assumes that they are part of a highly fragmented
browsing environment where they are already unique, and therefore consolidation
on configuration is a goal. However, this goal sometimes also conflicts with
usability. To allow users a safe set of choices, we offer "Coarse" configuration
in 2 modes. We recommend that you do not deviate from these configurations if
you have browser application fingerprinting as a concern.
### Usability Mode
TODO: description
Pros: Allows a restricted subset of Javascript
Pros: Less likely to try and reach the clearnet
Cons: Looks very different from Tor Browser
Cons: Plugin updates can create temporary uniqueness
#### Usability Extension Set
- **I2P In Private Browsing**
- **uMatrix**
- **jsRestrictor**
- **LocalCDN**
- **Onion in Container Tabs**
- **HTTPS EveryWhere** in some configurations
### Usability user.js characteristics
TODO: Summarize differences
### Strict Mode
TODO: description
Pros: Does not allow Javascript by default
Pros: Looks a lot like Tor Browser especially if you're using Tor Browser
Cons: More work to use
Cons: Temporary uniqueness can be created by enabling Javascript for specific sites
Cons: More likely to try and reach the clearnet
#### Strict Extension Set
- **NoScript**
- **I2P In Private Browsing**
- **HTTPS EveryWhere** in some configurations
#### Strict user.js characteristics
TODO: Summarize differences

35
docs/LINUX.md Normal file
View File

@ -0,0 +1,35 @@
### Linux Support
It's possible to use this package in the following binary formats on
Linux. These packages are for the **`amd64`** architecture.
#### Linux jpackage: `.zip`
```sh
mkdir ~/tmp-i2pbrowser && cd ~/tmp-i2pbrowser
wget https://github.com/eyedeekay/i2p.plugins.firefox/releases/download/1.0.6/i2pbrowser.zip
unzip i2pbrowser.zip && cd i2pbrowser
## THIS STEP IS OPTIONAL but it will force the system to use Tor Browser from within the i2pbrowser directory.
# This probably offers better security than vanilla Firefox.
# This will also make the directory the launcher is in relocatable to a flash drive, for instance.
# This is commonly referred to as being portable.
# If tor and torsocks are on the host system, Tor Browser will be downloaded over Tor.
./lib/torbrowser.sh
# end of optional step.
./bin/i2pbrowser
```
#### Debian/Ubuntu and variants Jpackage: `.deb`
1. Start your I2P Router
2. Download the latest release `.deb` from [Github](https://github.com/eyedeekay/i2p.plugins.firefox/releases) and verify it's hash.
3. Run `sudo apt-get install ./i2pbrowser*.deb`(Only needs to be done once per update)
4. Use the applications menu shortcut to launch the pre-configured I2P browser
#### Fedora and variants Jpackage: `.rpm`
1. Start your I2P Router
2. Download the latest release `.r[m` from [Github](https://github.com/eyedeekay/i2p.plugins.firefox/releases) and verify it's hash.
3. Run `sudo rpm -i ./i2pbrowser*.rpm`(Only needs to be done the first time)
4. Run `sudo rpm -U ./i2pbrowser*.rpm`(Only needs to be done once per update)
5. Use the applications menu shortcut to launch the pre-configured I2P browser

33
docs/OSX.md Normal file
View File

@ -0,0 +1,33 @@
Using this on OSX
=================
This code will launch an I2P-Configured Browser on OSX, but at this time
there are no packages for it because it's not possible for me to sign OSX
packages. You can use the `.jar` file with any Java greater than Java 8.
```sh
mkdir ~/tmp-i2pfirefox && cd ~/tmp-i2pfirefox
wget https://github.com/eyedeekay/i2p.plugins.firefox/releases/download/1.0.6/i2pfirefox.zip
unzip i2pfirefox.zip
./cmd/i2pfirefox.cmd
#or if you want to use a Chromium
./cmd/i2pchromium.cmd
```
Building a `jpackage`
---------------------
In order to build a `jpackage`, install at least Java 17. To set up Java
17 and configure it to be the Java used by the system for the rest of the
session, use these commands:
```sh
brew install openjdk@17
sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
export JAVA_HOME=`/usr/libexec/java_home -v 17`
```
Once you're finished, run `./osx-dmg.sh` in the repository root to produce a
`.dmg` package.

33
docs/WINDOWS.md Normal file
View File

@ -0,0 +1,33 @@
### Windows Support
It's possible to use this package on Windows, but it's recommended that
you get it through the Easy-Install bundle which includes this functionality
already. Use this only if you want to test new features or if you prefer
an unbundled I2P router with an external JVM.
#### Windows Jpackage: `.zip`
**(Not Recommended! This functionality is already included in the Easy-Install Bundle for Windows)**
1. Start your I2P Router
2. Download the latest release `.zip` from [Github](https://github.com/eyedeekay/i2p.plugins.firefox/releases) and verify it's hash.
3. Unzip the `.zip` directory
4. run the `i2pbrowser.exe` file inside the unzipped directory.
#### Windows Jpackage: `.msi`
**(Not Recommended! This functionality is already included in the Easy-Install Bundle for Windows)**
1. Start your I2P Router
2. Download the latest release `.msi` from [Github](https://github.com/eyedeekay/i2p.plugins.firefox/releases) and verify it's hash.
3. Run the `.msi` installer(Only needs to be done once per update)
4. Use the start menu shortcut to launch the pre-configured I2P browser
#### Windows Jpackage: `.exe`
**(Not Recommended! This functionality is already included in the Easy-Install Bundle for Windows)**
1. Start your I2P Router
2. Download the latest release `.exe` from [Github](https://github.com/eyedeekay/i2p.plugins.firefox/releases) and verify it's hash.
3. Run the `.msi` installer(Only needs to be done once per update)
4. Use the start menu shortcut to launch the pre-configured I2P browser

2
javadoc.sh
View File

@ -1,10 +1,8 @@
#! /usr/bin/env bash
rm -rf docs
~/.cargo/bin/lojidoc src/java/net/i2p/i2pfirefox/ -s -l > report.log
~/.cargo/bin/lojidoc -c src/java/net/i2p/i2pfirefox/ -s
mkdir -p docs
mv -v generated/net/i2p/i2pfirefox/*.md ./docs/
rm -rf generated
git add ./*.md