Update documentation to note that ClientAuth is used in place of basic auth, and that legacy mode (v2 onions) no longer is possible

This commit is contained in:
Miguel Jacq 2021-08-28 10:34:51 +10:00
parent 5f16be8bf3
commit 061e8da422
4 changed files with 100 additions and 108 deletions

View file

@ -16,23 +16,23 @@ When a tab is saved a purple pin icon appears to the left of its server status.
.. image:: _static/screenshots/advanced-save-tabs.png
When you quit OnionShare and then open it again, your saved tabs will start opened.
You'll have to manually start each service, but when you do they will start with the same OnionShare address and password.
You'll have to manually start each service, but when you do they will start with the same OnionShare address and private key.
If you save a tab, a copy of that tab's onion service secret key will be stored on your computer with your OnionShare settings.
.. _turn_off_passwords:
.. _turn_off_private_key:
Turn Off Passwords
------------------
Turn Off Private Key
--------------------
By default, all OnionShare services are protected with the username ``onionshare`` and a randomly-generated password.
If someone takes 20 wrong guesses at the password, your onion service is automatically stopped to prevent a brute force attack against the OnionShare service.
By default, all OnionShare services are protected with a private key, which Tor calls Client Authentication.
When browsing to an OnionShare service in Tor Browser, Tor Browser will prompt for the private key to be entered.
Sometimes you might want your OnionShare service to be accessible to the public, like if you want to set up an OnionShare receive service so the public can securely and anonymously send you files.
In this case, it's better to disable the password altogether.
If you don't do this, someone can force your server to stop just by making 20 wrong guesses of your password, even if they know the correct password.
In this case, it's better to disable the private key altogether.
To turn off the password for any tab, just check the "Don't use a password" box before starting the server. Then the server will be public and won't have a password.
To turn off the private key for any tab, check the "This is a public OnionShare service (disables private key)" box before starting the server. Then the server will be public and won't need a private key to view in Tor Browser.
.. _custom_titles:
@ -106,11 +106,14 @@ You can browse the command-line documentation by running ``onionshare --help``::
│ https://onionshare.org/ │
╰───────────────────────────────────────────╯
usage: onionshare-cli [-h] [--receive] [--website] [--chat] [--local-only] [--connect-timeout SECONDS] [--config FILENAME]
[--persistent FILENAME] [--title TITLE] [--public] [--auto-start-timer SECONDS]
[--auto-stop-timer SECONDS] [--legacy] [--client-auth] [--no-autostop-sharing] [--data-dir data_dir]
[--webhook-url webhook_url] [--disable-text] [--disable-files] [--disable_csp] [-v]
[filename ...]
usage: onionshare-cli [-h] [--receive] [--website] [--chat] [--local-only]
[--connect-timeout SECONDS] [--config FILENAME]
[--persistent FILENAME] [--title TITLE] [--public]
[--auto-start-timer SECONDS] [--auto-stop-timer SECONDS]
[--no-autostop-sharing] [--data-dir data_dir]
[--webhook-url webhook_url] [--disable-text]
[--disable-files] [--disable_csp] [-v]
[filename [filename ...]]
positional arguments:
filename List of files or folders to share
@ -122,44 +125,29 @@ You can browse the command-line documentation by running ``onionshare --help``::
--chat Start chat server
--local-only Don't use Tor (only for development)
--connect-timeout SECONDS
Give up connecting to Tor after a given amount of seconds (default: 120)
Give up connecting to Tor after a given amount of
seconds (default: 120)
--config FILENAME Filename of custom global settings
--persistent FILENAME Filename of persistent session
--title TITLE Set a title
--public Don't use a password
--public Don't use a private key
--auto-start-timer SECONDS
Start onion service at scheduled time (N seconds from now)
Start onion service at scheduled time (N seconds
from now)
--auto-stop-timer SECONDS
Stop onion service at schedule time (N seconds from now)
--legacy Use legacy address (v2 onion service, not recommended)
--client-auth Use client authorization (requires --legacy)
--no-autostop-sharing Share files: Continue sharing after files have been sent (default is to stop sharing)
--data-dir data_dir Receive files: Save files received to this directory
Stop onion service at schedule time (N seconds
from now)
--no-autostop-sharing Share files: Continue sharing after files have
been sent (default is to stop sharing)
--data-dir data_dir Receive files: Save files received to this
directory
--webhook-url webhook_url
Receive files: URL to receive webhook notifications
Receive files: URL to receive webhook
notifications
--disable-text Receive files: Disable receiving text messages
--disable-files Receive files: Disable receiving files
--disable_csp Publish website: Disable Content Security Policy header (allows your website to use third-party
--disable_csp Publish website: Disable Content Security Policy
header (allows your website to use third-party
resources)
-v, --verbose Log OnionShare errors to stdout, and web errors to disk
Legacy Addresses
----------------
OnionShare uses v3 Tor onion services by default.
These are modern onion addresses that have 56 characters, for example::
uf3wmtpbstcupvrrsetrtct7qcmnqvdcsxqzxthxbx2y7tidatxye7id.onion
OnionShare still has support for v2 onion addresses, the old type of onion addresses that have 16 characters, for example::
lc7j6u55vhrh45eq.onion
OnionShare calls v2 onion addresses "legacy addresses", and they are not recommended, as v3 onion addresses are more secure.
To use legacy addresses, before starting a server click "Show advanced settings" from its tab and check the "Use a legacy address (v2 onion service, not recommended)" box.
In legacy mode you can optionally turn on Tor client authentication.
Once you start a server in legacy mode you cannot remove legacy mode in that tab.
Instead you must start a separate service in a separate tab.
Tor Project plans to `completely deprecate v2 onion services <https://blog.torproject.org/v2-deprecation-timeline>`_ on October 15, 2021, and legacy onion services will be removed from OnionShare before then.
-v, --verbose Log OnionShare errors to stdout, and web errors to
disk