commit c1926e0dcec34b4aa522c7ba4fa23ff00f37e486
parent 59b3c267ad44e1214e602517f7cccafa49bfc943
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 1 Aug 2022 13:22:35 +0200
refactor users manual
Diffstat:
7 files changed, 905 insertions(+), 900 deletions(-)
diff --git a/index.rst b/index.rst
@@ -5,7 +5,7 @@ Welcome to GNUnet’s documentation!
about
installing
- user
- man_developers/index.md
+ man_users/index
+ man_developers/index
livingstandards
gana
diff --git a/man_users/fs.rst b/man_users/fs.rst
@@ -0,0 +1,185 @@
+File-sharing
+------------
+
+This chapter documents the GNUnet file-sharing application. The original
+file-sharing implementation for GNUnet was designed to provide anonymous
+file-sharing. However, over time, we have also added support for
+non-anonymous file-sharing (which can provide better performance).
+Anonymous and non-anonymous file-sharing are quite integrated in GNUnet
+and, except for routing, share most of the concepts and implementation.
+There are three primary file-sharing operations: publishing, searching
+and downloading. For each of these operations, the user specifies an
+anonymity level. If both the publisher and the searcher/downloader
+specify “no anonymity”, non-anonymous file-sharing is used. If either
+user specifies some desired degree of anonymity, anonymous file-sharing
+will be used.
+
+After a short introduction, we will first look at the various concepts
+in GNUnet’s file-sharing implementation. Then, we will discuss specifics
+as to how they impact users that publish, search or download files.
+
+Searching
+~~~~~~~~~
+
+The command ``gnunet-search`` can be used to search for content on
+GNUnet. The format is:
+
+::
+
+ $ gnunet-search [-t TIMEOUT] KEYWORD
+
+The ``-t`` option specifies that the query should timeout after
+approximately ``TIMEOUT`` seconds. A value of zero (“0”) is interpreted
+as no timeout, which is the default. In this case, gnunet-search will
+never terminate (unless you press CTRL-C).
+
+If multiple words are passed as keywords, they will all be considered
+optional. Prefix keywords with a “+” to make them mandatory.
+
+Note that searching using:
+
+::
+
+ $ gnunet-search Das Kapital
+
+is not the same as searching for
+
+::
+
+ $ gnunet-search "Das Kapital"
+
+as the first will match files shared under the keywords “Das” or
+“Kapital” whereas the second will match files shared under the keyword
+“Das Kapital”.
+
+Search results are printed like this:
+
+::
+
+ #15:
+ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+
+The whole line is the command you would have to enter to download the
+file. The first argument passed to ``-o`` is the suggested filename (you
+may change it to whatever you like). It is followed by the key for
+decrypting the file, the query for searching the file, a checksum (in
+hexadecimal) finally the size of the file in bytes.
+
+Downloading
+~~~~~~~~~~~
+
+In order to download a file, you need the whole line returned by
+gnunet-search. You can then use the tool ``gnunet-download`` to obtain
+the file:
+
+::
+
+ $ gnunet-download -o <FILENAME> <GNUNET-URL>
+
+``FILENAME`` specifies the name of the file where GNUnet is supposed to
+write the result. Existing files are overwritten. If the existing file
+contains blocks that are identical to the desired download, those blocks
+will not be downloaded again (automatic resume).
+
+If you want to download the GPL from the previous example, you do the
+following:
+
+::
+
+ $ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+
+If you ever have to abort a download, you can continue it at any time by
+re-issuing gnunet-download with the same filename. In that case, GNUnet
+will **not** download blocks again that are already present.
+
+GNUnet’s file-encoding mechanism will ensure file integrity, even if the
+existing file was not downloaded from GNUnet in the first place.
+
+You may want to use the ``-V`` switch to turn on verbose reporting. In
+this case, gnunet-download will print the current number of bytes
+downloaded whenever new data was received.
+
+Publishing
+~~~~~~~~~~
+
+The command ``gnunet-publish`` can be used to add content to the
+network. The basic format of the command is:
+
+::
+
+ $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
+
+For example:
+
+::
+
+ $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING
+
+The option ``-k`` is used to specify keywords for the file that should
+be inserted. You can supply any number of keywords, and each of the
+keywords will be sufficient to locate and retrieve the file. Please note
+that you must use the ``-k`` option more than once – one for each
+expression you use as a keyword for the filename.
+
+The ``-m`` option is used to specify meta-data, such as descriptions.
+You can use ``-m`` multiple times. The ``TYPE`` passed must be from the
+list of meta-data types known to libextractor. You can obtain this list
+by running ``extract -L``. Use quotes around the entire meta-data
+argument if the value contains spaces. The meta-data is displayed to
+other users when they select which files to download. The meta-data and
+the keywords are optional and may be inferred using GNU libextractor.
+
+``gnunet-publish`` has a few additional options to handle namespaces and
+directories. Refer to the man-page for details.
+
+Indexing vs Inserting
+~~~~~~~~~~~~~~~~~~~~~
+
+By default, GNUnet indexes a file instead of making a full copy. This is
+much more efficient, but requires the file to stay unaltered at the
+location where it was when it was indexed. If you intend to move, delete
+or alter a file, consider using the option ``-n`` which will force
+GNUnet to make a copy of the file in the database.
+
+Since it is much less efficient, this is strongly discouraged for large
+files. When GNUnet indexes a file (default), GNUnet does **not** create
+an additional encrypted copy of the file but just computes a summary (or
+index) of the file. That summary is approximately two percent of the
+size of the original file and is stored in GNUnet’s database. Whenever a
+request for a part of an indexed file reaches GNUnet, this part is
+encrypted on-demand and send out. This way, there is no need for an
+additional encrypted copy of the file to stay anywhere on the drive.
+This is different from other systems, such as Freenet, where each file
+that is put online must be in Freenet’s database in encrypted format,
+doubling the space requirements if the user wants to preserve a directly
+accessible copy in plaintext.
+
+Thus indexing should be used for all files where the user will keep
+using this file (at the location given to gnunet-publish) and does not
+want to retrieve it back from GNUnet each time. If you want to remove a
+file that you have indexed from the local peer, use the tool
+gnunet-unindex to un-index the file.
+
+The option ``-n`` may be used if the user fears that the file might be
+found on their drive (assuming the computer comes under the control of
+an adversary). When used with the ``-n`` flag, the user has a much
+better chance of denying knowledge of the existence of the file, even if
+it is still (encrypted) on the drive and the adversary is able to crack
+the encryption (e.g. by guessing the keyword).
+
+Concepts
+~~~~~~~~
+
+For better results with filesharing it is useful to understand the
+following concepts. In addition to anonymous routing GNUnet attempts to
+give users a better experience in searching for content. GNUnet uses
+cryptography to safely break content into smaller pieces that can be
+obtained from different sources without allowing participants to corrupt
+files. GNUnet makes it difficult for an adversary to send back bogus
+search results. GNUnet enables content providers to group related
+content and to establish a reputation. Furthermore, GNUnet allows
+updates to certain content to be made available. This section is
+supposed to introduce users to the concepts that are used to achieve
+these goals.
+
+TODO concepts. Should they be here?
diff --git a/man_users/gns.rst b/man_users/gns.rst
@@ -0,0 +1,617 @@
+The GNU Name System
+-------------------
+
+The GNU Name System (GNS) is secure and decentralized naming system. It
+allows its users to register names as top-level domains (TLDs) and
+resolve other namespaces within their TLDs.
+
+GNS is designed to provide:
+
+- Censorship resistance
+- Query privacy
+- Secure name resolution
+- Compatibility with DNS
+
+For the initial configuration and population of your GNS installation,
+please follow the GNS setup instructions. The remainder of this chapter
+will provide some background on GNS and then describe how to use GNS in
+more detail.
+
+Unlike DNS, GNS does not rely on central root zones or authorities.
+Instead any user administers their own root and can can create arbitrary
+name value mappings. Furthermore users can delegate resolution to other
+users’ zones just like DNS NS records do. Zones are uniquely identified
+via public keys and resource records are signed using the corresponding
+public key. Delegation to another user’s zone is done using special PKEY
+records and petnames. A petname is a name that can be freely chosen by
+the user. This results in non-unique name-value mappings as www.bob to
+one user might be www.friend for someone else.
+
+Start Zones
+~~~~~~~~~~~
+
+In the default configuration, there are two zones defined and shipped
+with GNUnet:
+
+The first is “gnunet.org”, which points to the authoritate zone of the
+GNUnet project. It can be used to resolve, for example,
+“www.gnunet.org”.
+
+“.pin” is another default zone which points to a special zone also
+managed by gnunet.org. Users may register submodomains on a first-come
+first-served-basis at https://fcfs.gnunet.org.
+
+Use gnunet-config -s gns to view the GNS configuration, including all
+configured zones that are operated by other users. The respective
+configuration entry names start with a “.”, e.g. “.pin”.
+
+You can configure any number of top-level domains, and point them to the
+respective zones of your friends! For this, simply obtain the respective
+public key (you will learn how below) and extend the configuration:
+
+::
+
+ $ gnunet-config -s gns -o .myfriend -V PUBLIC_KEY
+
+Zones and Egos
+~~~~~~~~~~~~~~
+
+In GNUnet, identity management is about managing egos. Egos can
+correspond to pseudonyms or real-world identities. If you value your
+privacy, you are encouraged to use separate egos for separate
+activities.
+
+Technically, an ego is first of all a public-private key pair, and thus
+egos also always correspond to a GNS zone. Egos are managed by the
+IDENTITY service. Note that this service has nothing to do with the peer
+identity. The IDENTITY service essentially stores the private keys under
+human-readable names, and keeps a mapping of which private key should be
+used for particular important system functions.
+
+You probably should create at least one zone of your own. You can create
+any number of zones using the gnunet-identity tool using:
+
+::
+
+ $ gnunet-identity --create="myzone"
+
+Henceforth, on your system you control the TLD “myzone”.
+
+All of your zones can be listed (displayed) using the gnunet-identity
+command line tool as well:
+
+::
+
+ $ gnunet-identity --display
+
+Maintaining Zones
+~~~~~~~~~~~~~~~~~
+
+Now you can add (or edit, or remove) records in your GNS zone using the
+gnunet-namestore-gtk GUI or using the gnunet-namestore command-line
+tool. In either case, your records will be stored in an SQL database
+under control of the gnunet-service-namestore. Note that if multiple
+users use one peer, the namestore database will include the combined
+records of all users. However, users will not be able to see each
+other’s records if they are marked as private.
+
+To provide a short example for editing your own zone, suppose you have
+your own web server with the IP 1.2.3.4. Then you can put an A record (A
+records in DNS are for IPv4 IP addresses) into your local zone “myzone”
+using the command:
+
+::
+
+ $ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e 1d
+
+Similar commands will work for other types of DNS and GNS records, the
+syntax largely depending on the type of the record. Naturally, most
+users may find editing the zones using the gnunet-namestore-gtk GUI to
+be easier.
+
+Each zone in GNS has a public-private key. Usually, gnunet-namestore and
+gnunet-setup will access your private key as necessary, so you do not
+have to worry about those. What is important is your public key (or
+rather, the hash of your public key), as you will likely want to give it
+to others so that they can securely link to you.
+
+A central operation in GNS is the ability to securely delegate to other
+zones. Basically, by adding a delegation you make all of the names from
+the other zone available to yourself. This section describes how to
+create delegations.
+
+Suppose you have a friend who you call ’bob’ who also uses GNS. You can
+then delegate resolution of names to Bob’s zone by adding a PKEY record
+to their local zone:
+
+::
+
+ $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e 1d -z myzone
+
+Note that “XXXX” in the command above must be replaced with the hash of
+Bob’s public key (the output your friend obtained using the
+gnunet-identity command from the previous section and told you, for
+example by giving you a business card containing this information as a
+QR code).
+
+Assuming Bob has an “A” record for their website under the name of “www”
+in his zone, you can then access Bob’s website under “www.bob.myzone” —
+as well as any (public) GNS record that Bob has in their zone by
+replacing www with the respective name of the record in Bob’s zone.
+
+Furthermore, if Bob has themselves a (public) delegation to Carol’s zone
+under “carol”, you can access Carol’s records under
+“NAME.carol.bob.myzone” (where “NAME” is the name of Carol’s record you
+want to access).
+
+Resolving GNS records
+~~~~~~~~~~~~~~~~~~~~~
+
+Next, you should try resolving your own GNS records. The method we found
+to be the most uncomplicated is to do this by explicitly resolving using
+gnunet-gns. For this exercise, we will assume that you used the string
+“gnu” for the pseudonym (or label) of your GNS zone. If you used
+something else, replace “.gnu” with your real pseudonym in the examples
+below.
+
+In the shell, type:
+
+::
+
+ $ gnunet-gns -u www.gnunet.org
+ www.gnunet.org:
+ Got `A' record: ...
+
+That shows that resolution works, once GNS is integrated with the
+application.
+
+Integration with Browsers (DNS2GNS service)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most OSes allow you to either modify your ``/etc/resolv.conf`` directly
+or through ``resolvectl``. We are going to configure the dns2gns service
+in order to translate DNS name queries by applications to GNS name
+queries where applicable and else fall back to DNS.
+
+Optionally, you may want to configure your dns2gns service to run on a
+non-priviledged port like 5353. But, in case you are going to edit
+``/etc/resolv.conf`` directly, the dns2gns service MUST run on port 53
+as you cannot specify the port number. A ``$FALLBACK_DNS`` variable
+should be a DNS server you trust such as your local router:
+
+::
+
+ $ gnunet-config -s dns2gns -o OPTIONS -V "-d $FALLBACK_DNS -p 5252"
+ $ gnunet-arm -i dns2gns # Make sure the service is started
+
+If you edit your resolv.conf directly, it should contain and entry like
+this:
+
+::
+
+ nameserver 127.0.0.1
+
+In any case, it is very likely that the method of modification of your
+resolver is OS specific. Recently, the combination of NetworkManager and
+systemd-resolved is becoming increasingly popular.
+
+If you use resolvectl and systemd-resolved you can temporarily set the
+nameserver like this:
+
+::
+
+ $ resolvectl $INTERFACE 127.0.0.1:5353
+
+Where ``$INTERFACE`` is your network interface such as ``eth0``.
+
+In order to automatically set the DNS2GNS server if it is running
+already you can use NetworkManager-dispatcher. First, enable it:
+
+::
+
+ $ sudo systemctl enable NetworkManager-dispatcher.service
+ $ sudo systemctl start NetworkManager-dispatcher.service
+
+Then, create a script ``/etc/NetworkManager/dispatch.h/10-dns2-gns.sh``:
+
+::
+
+ #!/bin/sh
+ interface=$1
+ status=$2
+
+ if [ "$interface" = "eth0" ]; then
+ case $status in
+ up)
+ if nc -u -z 127.0.0.1 5353; then
+ resolvectl dns $interface 127.0.0.1:5353
+ fi
+ ;;
+ down)
+ ;;
+ esac
+ fi
+
+Make sure the script is owned by root and executable:
+
+::
+
+ $ sudo root:root /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+ $ sudo +x /etc/NetworkManager/dispatch.d/10-dns2gns.sh
+
+You can test accessing this website using your browser or curl:
+
+::
+
+ $ curl www.gnunet.org
+
+Note that “gnunet.org” is a domain that also exists in DNS and for which
+the GNUnet project webservers can provide trusted TLS certificates. When
+using non-DNS names with GNS or aliases, this may result in issues when
+accessing HTTPS websites with browsers. In order learn how to provide
+relief for this issue, read on.
+
+Integration with Browsers (SOCKS proxy)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While we recommend integrating GNS using the DNS2GNS service or the
+NSSwitch plugin, you can also integrate GNS directly with your browser
+via the gnunet-gns-proxy. This method can have the advantage that the
+proxy can validate TLS/X.509 records and thus strengthen web security;
+however, the proxy is still a bit brittle, so expect subtle failures. We
+have had reasonable success with Chromium, and various frustrations with
+Firefox in this area recently.
+
+The first step is to start the proxy. As the proxy is (usually) not
+started by default, this is done as a unprivileged user using gnunet-arm
+-i gns-proxy. Use gnunet-arm -I as a unprivileged user to check that the
+proxy was actually started. (The most common error for why the proxy may
+fail to start is that you did not run gnunet-gns-proxy-setup-ca during
+installation.) The proxy is a SOCKS5 proxy running (by default) on port
+7777. Thus, you need to now configure your browser to use this proxy.
+With Chromium, you can do this by starting the browser as a unprivileged
+user using chromium –proxy-server=“socks5://localhost:7777” For Firefox
+(or Icecat), select “Edit-Preferences” in the menu, and then select the
+“Advanced” tab in the dialog and then “Network”:
+
+Here, select “Settings…” to open the proxy settings dialog. Select
+“Manual proxy configuration” and enter localhost with port 7777 under
+SOCKS Host. Furthermore, set the checkbox “Proxy DNS when using SOCKS
+v5” at the bottom of the dialog. Finally, push “OK”.
+
+You must also go to about:config and change the
+browser.fixup.alternate.enabled option to false, otherwise the browser
+will autoblunder an address like www.gnu to www.gnu.com. If you want to
+resolve @ in your own TLDs, you must additionally set
+browser.fixup.dns_first_use_for_single_words to true.
+
+After configuring your browser, you might want to first confirm that it
+continues to work as before. (The proxy is still experimental and if you
+experience “odd” failures with some webpages, you might want to disable
+it again temporarily.) Next, test if things work by typing
+“http://test.gnu/” into the URL bar of your browser. This currently
+fails with (my version of) Firefox as Firefox is super-smart and tries
+to resolve “http://www.test.gnu/” instead of “test.gnu”. Chromium can be
+convinced to comply if you explicitly include the “http://” prefix —
+otherwise a Google search might be attempted, which is not what you
+want. If successful, you should see a simple website.
+
+Note that while you can use GNS to access ordinary websites, this is
+more an experimental feature and not really our primary goal at this
+time. Still, it is a possible use-case and we welcome help with testing
+and development.
+
+Creating a Business Card
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before we can really use GNS, you should create a business card. Note
+that this requires having LaTeX installed on your system. If you are
+using a Debian GNU/Linux based operating system, the following command
+should install the required components. Keep in mind that this requires
+3GB of downloaded data and possibly even more when unpacked. On a GNU
+Guix based system texlive 2017 has returns a DAG size of 5032.4 MiB. The
+packages which are confirmed to be required are:
+
+- texlive-units
+- texlive-labels
+- texlive-pst-barcode
+- texlive-luatex85
+- texlive-preview
+- texlive-pdfcrop
+- texlive-koma-script
+
+**We welcome any help in identifying the required components of the
+TexLive Distribution. This way we could just state the required
+components without pulling in the full distribution of TexLive.**
+
+::
+
+ apt-get install texlive-full
+
+Start creating a business card by clicking the “Copy” button in
+gnunet-namestore-gtk. Next, you should start the gnunet-bcd program (in
+the terminal, on the command-line). You do not need to pass any options,
+and please be not surprised if there is no output:
+
+::
+
+ $ gnunet-bcd # does not return
+
+Then, start a browser and point it to http://localhost:8888/ where
+gnunet-bcd is running a Web server!
+
+First, you might want to fill in the “GNS Public Key” field by
+right-clicking and selecting “Paste”, filling in the public key from the
+copy you made in gnunet-namestore-gtk. Then, fill in all of the other
+fields, including your GNS NICKname. Adding a GPG fingerprint is
+optional. Once finished, click “Submit Query”. If your LaTeX
+installation is incomplete, the result will be disappointing. Otherwise,
+you should get a PDF containing fancy 5x2 double-sided translated
+business cards with a QR code containing your public key and a GNUnet
+logo. We’ll explain how to use those a bit later. You can now go back to
+the shell running gnunet-bcd and press CTRL-C to shut down the Web
+server.
+
+Be Social
+~~~~~~~~~
+
+Next, you should print out your business card and be social. Find a
+friend, help them install GNUnet and exchange business cards with them.
+Or, if you’re a desperate loner, you might try the next step with your
+own card. Still, it’ll be hard to have a conversation with yourself
+later, so it would be better if you could find a friend. You might also
+want a camera attached to your computer, so you might need a trip to the
+store together.
+
+Before we get started, we need to tell gnunet-qr which zone it should
+import new records into. For this, run:
+
+::
+
+ $ gnunet-identity -s namestore -e NAME
+
+where NAME is the name of the zone you want to import records into. In
+our running example, this would be “gnu”.
+
+Henceforth, for every business card you collect, simply run:
+
+::
+
+ $ gnunet-qr
+
+to open a window showing whatever your camera points at. Hold up your
+friend’s business card and tilt it until the QR code is recognized. At
+that point, the window should automatically close. At that point, your
+friend’s NICKname and their public key should have been automatically
+imported into your zone.
+
+Assuming both of your peers are properly integrated in the GNUnet
+network at this time, you should thus be able to resolve your friends
+names. Suppose your friend’s nickname is “Bob”. Then, type
+
+::
+
+ $ gnunet-gns -u test.bob
+
+to check if your friend was as good at following instructions as you
+were.
+
+Backup of Identities and Egos
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One should always backup their files, especially in these SSD days (our
+team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer
+identity and zones is achieved by copying the following files:
+
+The peer identity file can be found in
+``~/.local/share/gnunet/private_key.ecc``.
+
+The private keys of your egos are stored in the directory
+``~/.local/share/gnunet/identity/egos/``. They are stored in files whose
+filenames correspond to the zones’ ego names. These are probably the
+most important files you want to backup from a GNUnet installation.
+
+Note: All these files contain cryptographic keys and they are stored
+without any encryption. So it is advisable to backup encrypted copies of
+them.
+
+Revocation
+~~~~~~~~~~
+
+Now, in the situation of an attacker gaining access to the private key
+of one of your egos, the attacker can create records in the respective
+GNS zone and publish them as if you published them. Anyone resolving
+your domain will get these new records and when they verify they seem
+authentic because the attacker has signed them with your key.
+
+To address this potential security issue, you can pre-compute a
+revocation certificate corresponding to your ego. This certificate, when
+published on the P2P network, flags your private key as invalid, and all
+further resolutions or other checks involving the key will fail.
+
+A revocation certificate is thus a useful tool when things go out of
+control, but at the same time it should be stored securely. Generation
+of the revocation certificate for a zone can be done through
+gnunet-revocation. For example, the following command (as unprivileged
+user) generates a revocation file revocation.dat for the zone zone1:
+gnunet-revocation -f revocation.dat -R zone1
+
+The above command only pre-computes a revocation certificate. It does
+not revoke the given zone. Pre-computing a revocation certificate
+involves computing a proof-of-work and hence may take up to 4 to 5 days
+on a modern processor. Note that you can abort and resume the
+calculation at any time. Also, even if you did not finish the
+calculation, the resulting file will contain the signature, which is
+sufficient to complete the revocation process even without access to the
+private key. So instead of waiting for a few days, you can just abort
+with CTRL-C, backup the revocation certificate and run the calculation
+only if your key actually was compromised. This has the disadvantage of
+revocation taking longer after the incident, but the advantage of saving
+a significant amount of energy. So unless you believe that a key
+compromise will need a rapid response, we urge you to wait with
+generating the revocation certificate. Also, the calculation is
+deliberately expensive, to deter people from doing this just for fun (as
+the actual revocation operation is expensive for the network, not for
+the peer performing the revocation).
+
+To avoid TL;DR ones from accidentally revocating their zones, we are not
+giving away the command, but it is uncomplicated: the actual revocation
+is performed by using the -p option of gnunet-revocation.
+
+What’s next?
+~~~~~~~~~~~~
+
+This may seem not like much of an application yet, but you have just
+been one of the first to perform a decentralized secure name lookup
+(where nobody could have altered the value supplied by your friend) in a
+privacy-preserving manner (your query on the network and the
+corresponding response were always encrypted). So what can you really do
+with this? Well, to start with, you can publish your GnuPG fingerprint
+in GNS as a “CERT” record and replace the public web-of-trust with its
+complicated trust model with explicit names and privacy-preserving
+resolution. Also, you should read the next chapter of the tutorial and
+learn how to use GNS to have a private conversation with your friend.
+Finally, help us with the next GNUnet release for even more applications
+using this new public key infrastructure.
+
+Resource Records
+~~~~~~~~~~~~~~~~
+
+GNS supports the majority of the DNS records as defined in `RFC
+1035 <http://www.ietf.org/rfc/rfc1035.txt>`__. Additionally, GNS defines
+some new record types the are unique to the GNS system. For example,
+GNS-specific resource records are used to give petnames for zone
+delegation, revoke zone keys and provide some compatibility features.
+
+For some DNS records, GNS does extended processing to increase their
+usefulness in GNS. In particular, GNS introduces special names referred
+to as “zone relative names”. Zone relative names are allowed in some
+resource record types (for example, in NS and CNAME records) and can
+also be used in links on webpages. Zone relative names end in “.+” which
+indicates that the name needs to be resolved relative to the current
+authoritative zone. The extended processing of those names will expand
+the “.+” with the correct delegation chain to the authoritative zone
+(replacing “.+” with the name of the location where the name was
+encountered) and hence generate a valid GNS name.
+
+The GNS currently supports the record types as defined in
+`GANA <https://git.gnunet.org/gana.git/tree/gnu-name-system-record-types/registry.rec>`__.
+In addition, GNS supports DNS record types, such as A, AAAA or TXT.
+
+For a complete description of the records, please refer to the
+specification at `LSD0001 <https://lsd.gnunet.org/lsd0001>`__.
+
+In the following, we discuss GNS records with specific behaviour or
+special handling in GNUnet.
+
+VPN
+^^^
+
+GNS allows easy access to services provided by the GNUnet Virtual Public
+Network. When the GNS resolver encounters a VPN record it will contact
+the VPN service to try and allocate an IPv4/v6 address (if the queries
+record type is an IP address) that can be used to contact the service.
+
+**Example**
+
+I want to provide access to the VPN service “web.gnu.” on port 80 on
+peer ABC012: Name: www; RRType: VPN; Value: 80 ABC012 web.gnu.
+
+The peer ABC012 is configured to provide an exit point for the service
+“web.gnu.” on port 80 to it’s server running locally on port 8080 by
+having the following lines in the gnunet.conf configuration file:
+
+::
+
+ [web.gnunet.]
+ TCP_REDIRECTS = 80:localhost4:8080
+
+Synchronizing with legacy DNS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to support GNS but the master database for a zone is only
+available and maintained in DNS, GNUnet includes the gnunet-zoneimport
+tool to monitor a DNS zone and automatically import records into GNS.
+Today, the tool does not yet support DNS AF(X)R, as we initially used it
+on the “.fr” zone which does not allow us to perform a DNS zone
+transfer. Instead, gnunet-zoneimport reads a list of DNS domain names
+from stdin, issues DNS queries for each, converts the obtained records
+(if possible) and stores the result in the namestore.
+
+The zonemaster service then takes the records from the namestore,
+publishes them into the DHT which makes the result available to the GNS
+resolver. In the GNS configuration, non-local zones can be configured to
+be intercepted by specifying “.tld = PUBLICKEY” in the configuration
+file in the “[gns]” section.
+
+Note that the namestore by default also populates the namecache. This
+pre-population is cryptographically expensive. Thus, on systems that
+only serve to import a large (millions of records) DNS zone and that do
+not have a local gns service in use, it is thus advisable to disable the
+namecache by setting the option “DISABLE” to “YES” in section
+“[namecache]”.
+
+Migrating an existing DNS zone into GNS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ascension is a tool to migrate existing DNS zones into GNS.
+
+Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR
+depending on whether or not there exists a SOA record for the zone. If
+that is the case it will take the serial as a reference point and
+request the zone. The server will either answer the IXFR request with a
+correct incremental zone or with the entire zone, which depends on the
+server configuration.
+
+Before you can migrate any zone though, you need to start a local GNUnet
+peer. To migrate the Syrian top level domain - one of the few top level
+domains that support zone transfers - into GNS use the following
+command:
+
+::
+
+ $ ascension sy. -n ns1.tld.sy. -p
+
+The -p flag will tell GNS to put these records on the DHT so that other
+users may resolve these records by using the public key of the zone.
+
+Once the zone is migrated, Ascension will output a message telling you,
+that it will refresh the zone after the time has elapsed. You can
+resolve the names in the zone directly using GNS or if you want to use
+it with your browser, check out the GNS manual section. Configuring the
+GNU Name System. To resolve the records from another system you need the
+respective zones PKEY. To get the zones public key, you can run the
+following command:
+
+::
+
+ $ gnunet-identity -dqe sy
+
+Where “sy” is the name of the zone you want to migrate.
+
+You can share the PKEY of the zone with your friends. They can then
+resolve records in the zone by doing a lookup replacing the zone label
+with your PKEY:
+
+::
+
+ $ gnunet-gns -t SOA -u "$PKEY"
+
+The program will continue to run as a daemon and update once the refresh
+time specified in the zones SOA record has elapsed.
+
+DNSCurve style records are supported in the latest release and they are
+added as a PKEY record to be referred to the respective GNS public key.
+Key distribution is still a problem but provided someone else has a
+public key under a given label it can be looked up.
+
+There is an unofficial Debian package called python3-ascension that adds
+a system user ascension and runs a GNUnet peer in the background.
+
+Ascension-bind is also an unofficial Debian package that on installation
+checks for running DNS zones and whether or not they are transferable
+using DNS zone transfer (AXFR). It asks the administrator which zones to
+migrate into GNS and installs a systemd unit file to keep the zone up to
+date. If you want to migrate different zones you might want to check the
+unit file from the package as a guide.
+
diff --git a/man_users/index.rst b/man_users/index.rst
@@ -0,0 +1,24 @@
+User Manual
+===========
+
+This tutorial is supposed to give a first introduction for users trying
+to do something real with GNUnet. Installation and configuration are
+specifically outside of the scope of this tutorial. Instead, we start by
+briefly checking that the installation works, and then dive into
+uncomplicated, concrete practical things that can be done with the
+framework provided by GNUnet.
+
+In short, this chapter of the “GNUnet Reference Documentation” will show
+you how to use the various peer-to-peer applications of the GNUnet
+system. As GNUnet evolves, we will add new sections for the various
+applications that are being created.
+
+Comments on the content of this chapter, and extensions of it are always
+welcome.
+
+.. toctree::
+
+ start
+ gns
+ reclaim
+ fs
diff --git a/man_users/reclaim.rst b/man_users/reclaim.rst
@@ -0,0 +1,3 @@
+re:claimID
+----------
+
diff --git a/man_users/start.rst b/man_users/start.rst
@@ -0,0 +1,74 @@
+Starting and stopping
+---------------------
+
+Prior to using any GNUnet-based application, one has to start a node:
+
+::
+
+ $ gnunet-arm -s
+
+To stop GNUnet:
+
+::
+
+ $ gnunet-arm -e
+
+You can usually find the logs under ``~/.cache/gnunet`` and all files
+such as databases and private keys in ``~/.local/share/gnunet``.
+
+The list of running services can be displayed using the ``-I`` option.
+It should look similar to this example:
+
+::
+
+ $ gnunet-arm -I
+ Running services:
+ topology (gnunet-daemon-topology)
+ nat (gnunet-service-nat)
+ vpn (gnunet-service-vpn)
+ gns (gnunet-service-gns)
+ cadet (gnunet-service-cadet)
+ namecache (gnunet-service-namecache)
+ hostlist (gnunet-daemon-hostlist)
+ revocation (gnunet-service-revocation)
+ ats (gnunet-service-ats)
+ peerinfo (gnunet-service-peerinfo)
+ zonemaster (gnunet-service-zonemaster)
+ zonemaster-monitor (gnunet-service-zonemaster-monitor)
+ dht (gnunet-service-dht)
+ namestore (gnunet-service-namestore)
+ set (gnunet-service-set)
+ statistics (gnunet-service-statistics)
+ nse (gnunet-service-nse)
+ fs (gnunet-service-fs)
+ peerstore (gnunet-service-peerstore)
+ core (gnunet-service-core)
+ rest (gnunet-rest-server)
+ transport (gnunet-service-transport)
+ datastore (gnunet-service-datastore)
+
+For the **multi-user** setup first the system services need to be
+started as the system user, i.e. the user gnunet needs to execute
+``gnunet-arm -s``. This should be done by the system’s init system. Then
+the user who wants to start GNUnet applications has to run
+``gnunet-arm -s``, too. It is recommended to automate this, e.g. using
+the user’s crontab.
+
+First, you should launch the peer information tool. You can do this from
+the command-line by typing:
+
+::
+
+ $ gnunet-peerinfo
+
+Once you have done this, you will see a list of known peers. If hardly
+any peers are listed, there is likely a problem with your network
+configuration. You can also check directly connected peers with:
+
+::
+
+ $ gnunet-core
+
+This should return (at least) one established connection peer.
+Otherwise, again, there is likely a problem with your network
+configuration.
diff --git a/user.rst b/user.rst
@@ -1,898 +0,0 @@
-User Manual
-===========
-
-This tutorial is supposed to give a first introduction for users trying
-to do something real with GNUnet. Installation and configuration are
-specifically outside of the scope of this tutorial. Instead, we start by
-briefly checking that the installation works, and then dive into
-uncomplicated, concrete practical things that can be done with the
-framework provided by GNUnet.
-
-In short, this chapter of the “GNUnet Reference Documentation” will show
-you how to use the various peer-to-peer applications of the GNUnet
-system. As GNUnet evolves, we will add new sections for the various
-applications that are being created.
-
-Comments on the content of this chapter, and extensions of it are always
-welcome.
-
-Starting and stopping
----------------------
-
-Prior to using any GNUnet-based application, one has to start a node:
-
-::
-
- $ gnunet-arm -s
-
-To stop GNUnet:
-
-::
-
- $ gnunet-arm -e
-
-You can usually find the logs under ``~/.cache/gnunet`` and all files
-such as databases and private keys in ``~/.local/share/gnunet``.
-
-The list of running services can be displayed using the ``-I`` option.
-It should look similar to this example:
-
-::
-
- $ gnunet-arm -I
- Running services:
- topology (gnunet-daemon-topology)
- nat (gnunet-service-nat)
- vpn (gnunet-service-vpn)
- gns (gnunet-service-gns)
- cadet (gnunet-service-cadet)
- namecache (gnunet-service-namecache)
- hostlist (gnunet-daemon-hostlist)
- revocation (gnunet-service-revocation)
- ats (gnunet-service-ats)
- peerinfo (gnunet-service-peerinfo)
- zonemaster (gnunet-service-zonemaster)
- zonemaster-monitor (gnunet-service-zonemaster-monitor)
- dht (gnunet-service-dht)
- namestore (gnunet-service-namestore)
- set (gnunet-service-set)
- statistics (gnunet-service-statistics)
- nse (gnunet-service-nse)
- fs (gnunet-service-fs)
- peerstore (gnunet-service-peerstore)
- core (gnunet-service-core)
- rest (gnunet-rest-server)
- transport (gnunet-service-transport)
- datastore (gnunet-service-datastore)
-
-For the **multi-user** setup first the system services need to be
-started as the system user, i.e. the user gnunet needs to execute
-``gnunet-arm -s``. This should be done by the system’s init system. Then
-the user who wants to start GNUnet applications has to run
-``gnunet-arm -s``, too. It is recommended to automate this, e.g. using
-the user’s crontab.
-
-First, you should launch the peer information tool. You can do this from
-the command-line by typing:
-
-::
-
- $ gnunet-peerinfo
-
-Once you have done this, you will see a list of known peers. If hardly
-any peers are listed, there is likely a problem with your network
-configuration. You can also check directly connected peers with:
-
-::
-
- $ gnunet-core
-
-This should return (at least) one established connection peer.
-Otherwise, again, there is likely a problem with your network
-configuration.
-
-The GNU Name System
--------------------
-
-The GNU Name System (GNS) is secure and decentralized naming system. It
-allows its users to register names as top-level domains (TLDs) and
-resolve other namespaces within their TLDs.
-
-GNS is designed to provide:
-
-- Censorship resistance
-- Query privacy
-- Secure name resolution
-- Compatibility with DNS
-
-For the initial configuration and population of your GNS installation,
-please follow the GNS setup instructions. The remainder of this chapter
-will provide some background on GNS and then describe how to use GNS in
-more detail.
-
-Unlike DNS, GNS does not rely on central root zones or authorities.
-Instead any user administers their own root and can can create arbitrary
-name value mappings. Furthermore users can delegate resolution to other
-users’ zones just like DNS NS records do. Zones are uniquely identified
-via public keys and resource records are signed using the corresponding
-public key. Delegation to another user’s zone is done using special PKEY
-records and petnames. A petname is a name that can be freely chosen by
-the user. This results in non-unique name-value mappings as www.bob to
-one user might be www.friend for someone else.
-
-Start Zones
-~~~~~~~~~~~
-
-In the default configuration, there are two zones defined and shipped
-with GNUnet:
-
-The first is “gnunet.org”, which points to the authoritate zone of the
-GNUnet project. It can be used to resolve, for example,
-“www.gnunet.org”.
-
-“.pin” is another default zone which points to a special zone also
-managed by gnunet.org. Users may register submodomains on a first-come
-first-served-basis at https://fcfs.gnunet.org.
-
-Use gnunet-config -s gns to view the GNS configuration, including all
-configured zones that are operated by other users. The respective
-configuration entry names start with a “.”, e.g. “.pin”.
-
-You can configure any number of top-level domains, and point them to the
-respective zones of your friends! For this, simply obtain the respective
-public key (you will learn how below) and extend the configuration:
-
-::
-
- $ gnunet-config -s gns -o .myfriend -V PUBLIC_KEY
-
-Zones and Egos
-~~~~~~~~~~~~~~
-
-In GNUnet, identity management is about managing egos. Egos can
-correspond to pseudonyms or real-world identities. If you value your
-privacy, you are encouraged to use separate egos for separate
-activities.
-
-Technically, an ego is first of all a public-private key pair, and thus
-egos also always correspond to a GNS zone. Egos are managed by the
-IDENTITY service. Note that this service has nothing to do with the peer
-identity. The IDENTITY service essentially stores the private keys under
-human-readable names, and keeps a mapping of which private key should be
-used for particular important system functions.
-
-You probably should create at least one zone of your own. You can create
-any number of zones using the gnunet-identity tool using:
-
-::
-
- $ gnunet-identity --create="myzone"
-
-Henceforth, on your system you control the TLD “myzone”.
-
-All of your zones can be listed (displayed) using the gnunet-identity
-command line tool as well:
-
-::
-
- $ gnunet-identity --display
-
-Maintaining Zones
-~~~~~~~~~~~~~~~~~
-
-Now you can add (or edit, or remove) records in your GNS zone using the
-gnunet-namestore-gtk GUI or using the gnunet-namestore command-line
-tool. In either case, your records will be stored in an SQL database
-under control of the gnunet-service-namestore. Note that if multiple
-users use one peer, the namestore database will include the combined
-records of all users. However, users will not be able to see each
-other’s records if they are marked as private.
-
-To provide a short example for editing your own zone, suppose you have
-your own web server with the IP 1.2.3.4. Then you can put an A record (A
-records in DNS are for IPv4 IP addresses) into your local zone “myzone”
-using the command:
-
-::
-
- $ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e 1d
-
-Similar commands will work for other types of DNS and GNS records, the
-syntax largely depending on the type of the record. Naturally, most
-users may find editing the zones using the gnunet-namestore-gtk GUI to
-be easier.
-
-Each zone in GNS has a public-private key. Usually, gnunet-namestore and
-gnunet-setup will access your private key as necessary, so you do not
-have to worry about those. What is important is your public key (or
-rather, the hash of your public key), as you will likely want to give it
-to others so that they can securely link to you.
-
-A central operation in GNS is the ability to securely delegate to other
-zones. Basically, by adding a delegation you make all of the names from
-the other zone available to yourself. This section describes how to
-create delegations.
-
-Suppose you have a friend who you call ’bob’ who also uses GNS. You can
-then delegate resolution of names to Bob’s zone by adding a PKEY record
-to their local zone:
-
-::
-
- $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e 1d -z myzone
-
-Note that “XXXX” in the command above must be replaced with the hash of
-Bob’s public key (the output your friend obtained using the
-gnunet-identity command from the previous section and told you, for
-example by giving you a business card containing this information as a
-QR code).
-
-Assuming Bob has an “A” record for their website under the name of “www”
-in his zone, you can then access Bob’s website under “www.bob.myzone” —
-as well as any (public) GNS record that Bob has in their zone by
-replacing www with the respective name of the record in Bob’s zone.
-
-Furthermore, if Bob has themselves a (public) delegation to Carol’s zone
-under “carol”, you can access Carol’s records under
-“NAME.carol.bob.myzone” (where “NAME” is the name of Carol’s record you
-want to access).
-
-Resolving GNS records
-~~~~~~~~~~~~~~~~~~~~~
-
-Next, you should try resolving your own GNS records. The method we found
-to be the most uncomplicated is to do this by explicitly resolving using
-gnunet-gns. For this exercise, we will assume that you used the string
-“gnu” for the pseudonym (or label) of your GNS zone. If you used
-something else, replace “.gnu” with your real pseudonym in the examples
-below.
-
-In the shell, type:
-
-::
-
- $ gnunet-gns -u www.gnunet.org
- www.gnunet.org:
- Got `A' record: ...
-
-That shows that resolution works, once GNS is integrated with the
-application.
-
-Integration with Browsers (DNS2GNS service)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Most OSes allow you to either modify your ``/etc/resolv.conf`` directly
-or through ``resolvectl``. We are going to configure the dns2gns service
-in order to translate DNS name queries by applications to GNS name
-queries where applicable and else fall back to DNS.
-
-Optionally, you may want to configure your dns2gns service to run on a
-non-priviledged port like 5353. But, in case you are going to edit
-``/etc/resolv.conf`` directly, the dns2gns service MUST run on port 53
-as you cannot specify the port number. A ``$FALLBACK_DNS`` variable
-should be a DNS server you trust such as your local router:
-
-::
-
- $ gnunet-config -s dns2gns -o OPTIONS -V "-d $FALLBACK_DNS -p 5252"
- $ gnunet-arm -i dns2gns # Make sure the service is started
-
-If you edit your resolv.conf directly, it should contain and entry like
-this:
-
-::
-
- nameserver 127.0.0.1
-
-In any case, it is very likely that the method of modification of your
-resolver is OS specific. Recently, the combination of NetworkManager and
-systemd-resolved is becoming increasingly popular.
-
-If you use resolvectl and systemd-resolved you can temporarily set the
-nameserver like this:
-
-::
-
- $ resolvectl $INTERFACE 127.0.0.1:5353
-
-Where ``$INTERFACE`` is your network interface such as ``eth0``.
-
-In order to automatically set the DNS2GNS server if it is running
-already you can use NetworkManager-dispatcher. First, enable it:
-
-::
-
- $ sudo systemctl enable NetworkManager-dispatcher.service
- $ sudo systemctl start NetworkManager-dispatcher.service
-
-Then, create a script ``/etc/NetworkManager/dispatch.h/10-dns2-gns.sh``:
-
-::
-
- #!/bin/sh
- interface=$1
- status=$2
-
- if [ "$interface" = "eth0" ]; then
- case $status in
- up)
- if nc -u -z 127.0.0.1 5353; then
- resolvectl dns $interface 127.0.0.1:5353
- fi
- ;;
- down)
- ;;
- esac
- fi
-
-Make sure the script is owned by root and executable:
-
-::
-
- $ sudo root:root /etc/NetworkManager/dispatch.d/10-dns2gns.sh
- $ sudo +x /etc/NetworkManager/dispatch.d/10-dns2gns.sh
-
-You can test accessing this website using your browser or curl:
-
-::
-
- $ curl www.gnunet.org
-
-Note that “gnunet.org” is a domain that also exists in DNS and for which
-the GNUnet project webservers can provide trusted TLS certificates. When
-using non-DNS names with GNS or aliases, this may result in issues when
-accessing HTTPS websites with browsers. In order learn how to provide
-relief for this issue, read on.
-
-Integration with Browsers (SOCKS proxy)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-While we recommend integrating GNS using the DNS2GNS service or the
-NSSwitch plugin, you can also integrate GNS directly with your browser
-via the gnunet-gns-proxy. This method can have the advantage that the
-proxy can validate TLS/X.509 records and thus strengthen web security;
-however, the proxy is still a bit brittle, so expect subtle failures. We
-have had reasonable success with Chromium, and various frustrations with
-Firefox in this area recently.
-
-The first step is to start the proxy. As the proxy is (usually) not
-started by default, this is done as a unprivileged user using gnunet-arm
--i gns-proxy. Use gnunet-arm -I as a unprivileged user to check that the
-proxy was actually started. (The most common error for why the proxy may
-fail to start is that you did not run gnunet-gns-proxy-setup-ca during
-installation.) The proxy is a SOCKS5 proxy running (by default) on port
-7777. Thus, you need to now configure your browser to use this proxy.
-With Chromium, you can do this by starting the browser as a unprivileged
-user using chromium –proxy-server=“socks5://localhost:7777” For Firefox
-(or Icecat), select “Edit-Preferences” in the menu, and then select the
-“Advanced” tab in the dialog and then “Network”:
-
-Here, select “Settings…” to open the proxy settings dialog. Select
-“Manual proxy configuration” and enter localhost with port 7777 under
-SOCKS Host. Furthermore, set the checkbox “Proxy DNS when using SOCKS
-v5” at the bottom of the dialog. Finally, push “OK”.
-
-You must also go to about:config and change the
-browser.fixup.alternate.enabled option to false, otherwise the browser
-will autoblunder an address like www.gnu to www.gnu.com. If you want to
-resolve @ in your own TLDs, you must additionally set
-browser.fixup.dns_first_use_for_single_words to true.
-
-After configuring your browser, you might want to first confirm that it
-continues to work as before. (The proxy is still experimental and if you
-experience “odd” failures with some webpages, you might want to disable
-it again temporarily.) Next, test if things work by typing
-“http://test.gnu/” into the URL bar of your browser. This currently
-fails with (my version of) Firefox as Firefox is super-smart and tries
-to resolve “http://www.test.gnu/” instead of “test.gnu”. Chromium can be
-convinced to comply if you explicitly include the “http://” prefix —
-otherwise a Google search might be attempted, which is not what you
-want. If successful, you should see a simple website.
-
-Note that while you can use GNS to access ordinary websites, this is
-more an experimental feature and not really our primary goal at this
-time. Still, it is a possible use-case and we welcome help with testing
-and development.
-
-Creating a Business Card
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Before we can really use GNS, you should create a business card. Note
-that this requires having LaTeX installed on your system. If you are
-using a Debian GNU/Linux based operating system, the following command
-should install the required components. Keep in mind that this requires
-3GB of downloaded data and possibly even more when unpacked. On a GNU
-Guix based system texlive 2017 has returns a DAG size of 5032.4 MiB. The
-packages which are confirmed to be required are:
-
-- texlive-units
-- texlive-labels
-- texlive-pst-barcode
-- texlive-luatex85
-- texlive-preview
-- texlive-pdfcrop
-- texlive-koma-script
-
-**We welcome any help in identifying the required components of the
-TexLive Distribution. This way we could just state the required
-components without pulling in the full distribution of TexLive.**
-
-::
-
- apt-get install texlive-full
-
-Start creating a business card by clicking the “Copy” button in
-gnunet-namestore-gtk. Next, you should start the gnunet-bcd program (in
-the terminal, on the command-line). You do not need to pass any options,
-and please be not surprised if there is no output:
-
-::
-
- $ gnunet-bcd # does not return
-
-Then, start a browser and point it to http://localhost:8888/ where
-gnunet-bcd is running a Web server!
-
-First, you might want to fill in the “GNS Public Key” field by
-right-clicking and selecting “Paste”, filling in the public key from the
-copy you made in gnunet-namestore-gtk. Then, fill in all of the other
-fields, including your GNS NICKname. Adding a GPG fingerprint is
-optional. Once finished, click “Submit Query”. If your LaTeX
-installation is incomplete, the result will be disappointing. Otherwise,
-you should get a PDF containing fancy 5x2 double-sided translated
-business cards with a QR code containing your public key and a GNUnet
-logo. We’ll explain how to use those a bit later. You can now go back to
-the shell running gnunet-bcd and press CTRL-C to shut down the Web
-server.
-
-Be Social
-~~~~~~~~~
-
-Next, you should print out your business card and be social. Find a
-friend, help them install GNUnet and exchange business cards with them.
-Or, if you’re a desperate loner, you might try the next step with your
-own card. Still, it’ll be hard to have a conversation with yourself
-later, so it would be better if you could find a friend. You might also
-want a camera attached to your computer, so you might need a trip to the
-store together.
-
-Before we get started, we need to tell gnunet-qr which zone it should
-import new records into. For this, run:
-
-::
-
- $ gnunet-identity -s namestore -e NAME
-
-where NAME is the name of the zone you want to import records into. In
-our running example, this would be “gnu”.
-
-Henceforth, for every business card you collect, simply run:
-
-::
-
- $ gnunet-qr
-
-to open a window showing whatever your camera points at. Hold up your
-friend’s business card and tilt it until the QR code is recognized. At
-that point, the window should automatically close. At that point, your
-friend’s NICKname and their public key should have been automatically
-imported into your zone.
-
-Assuming both of your peers are properly integrated in the GNUnet
-network at this time, you should thus be able to resolve your friends
-names. Suppose your friend’s nickname is “Bob”. Then, type
-
-::
-
- $ gnunet-gns -u test.bob
-
-to check if your friend was as good at following instructions as you
-were.
-
-Backup of Identities and Egos
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-One should always backup their files, especially in these SSD days (our
-team has suffered 3 SSD crashes over a span of 2 weeks). Backing up peer
-identity and zones is achieved by copying the following files:
-
-The peer identity file can be found in
-``~/.local/share/gnunet/private_key.ecc``.
-
-The private keys of your egos are stored in the directory
-``~/.local/share/gnunet/identity/egos/``. They are stored in files whose
-filenames correspond to the zones’ ego names. These are probably the
-most important files you want to backup from a GNUnet installation.
-
-Note: All these files contain cryptographic keys and they are stored
-without any encryption. So it is advisable to backup encrypted copies of
-them.
-
-Revocation
-~~~~~~~~~~
-
-Now, in the situation of an attacker gaining access to the private key
-of one of your egos, the attacker can create records in the respective
-GNS zone and publish them as if you published them. Anyone resolving
-your domain will get these new records and when they verify they seem
-authentic because the attacker has signed them with your key.
-
-To address this potential security issue, you can pre-compute a
-revocation certificate corresponding to your ego. This certificate, when
-published on the P2P network, flags your private key as invalid, and all
-further resolutions or other checks involving the key will fail.
-
-A revocation certificate is thus a useful tool when things go out of
-control, but at the same time it should be stored securely. Generation
-of the revocation certificate for a zone can be done through
-gnunet-revocation. For example, the following command (as unprivileged
-user) generates a revocation file revocation.dat for the zone zone1:
-gnunet-revocation -f revocation.dat -R zone1
-
-The above command only pre-computes a revocation certificate. It does
-not revoke the given zone. Pre-computing a revocation certificate
-involves computing a proof-of-work and hence may take up to 4 to 5 days
-on a modern processor. Note that you can abort and resume the
-calculation at any time. Also, even if you did not finish the
-calculation, the resulting file will contain the signature, which is
-sufficient to complete the revocation process even without access to the
-private key. So instead of waiting for a few days, you can just abort
-with CTRL-C, backup the revocation certificate and run the calculation
-only if your key actually was compromised. This has the disadvantage of
-revocation taking longer after the incident, but the advantage of saving
-a significant amount of energy. So unless you believe that a key
-compromise will need a rapid response, we urge you to wait with
-generating the revocation certificate. Also, the calculation is
-deliberately expensive, to deter people from doing this just for fun (as
-the actual revocation operation is expensive for the network, not for
-the peer performing the revocation).
-
-To avoid TL;DR ones from accidentally revocating their zones, we are not
-giving away the command, but it is uncomplicated: the actual revocation
-is performed by using the -p option of gnunet-revocation.
-
-What’s next?
-~~~~~~~~~~~~
-
-This may seem not like much of an application yet, but you have just
-been one of the first to perform a decentralized secure name lookup
-(where nobody could have altered the value supplied by your friend) in a
-privacy-preserving manner (your query on the network and the
-corresponding response were always encrypted). So what can you really do
-with this? Well, to start with, you can publish your GnuPG fingerprint
-in GNS as a “CERT” record and replace the public web-of-trust with its
-complicated trust model with explicit names and privacy-preserving
-resolution. Also, you should read the next chapter of the tutorial and
-learn how to use GNS to have a private conversation with your friend.
-Finally, help us with the next GNUnet release for even more applications
-using this new public key infrastructure.
-
-Resource Records
-~~~~~~~~~~~~~~~~
-
-GNS supports the majority of the DNS records as defined in `RFC
-1035 <http://www.ietf.org/rfc/rfc1035.txt>`__. Additionally, GNS defines
-some new record types the are unique to the GNS system. For example,
-GNS-specific resource records are used to give petnames for zone
-delegation, revoke zone keys and provide some compatibility features.
-
-For some DNS records, GNS does extended processing to increase their
-usefulness in GNS. In particular, GNS introduces special names referred
-to as “zone relative names”. Zone relative names are allowed in some
-resource record types (for example, in NS and CNAME records) and can
-also be used in links on webpages. Zone relative names end in “.+” which
-indicates that the name needs to be resolved relative to the current
-authoritative zone. The extended processing of those names will expand
-the “.+” with the correct delegation chain to the authoritative zone
-(replacing “.+” with the name of the location where the name was
-encountered) and hence generate a valid GNS name.
-
-The GNS currently supports the record types as defined in
-`GANA <https://git.gnunet.org/gana.git/tree/gnu-name-system-record-types/registry.rec>`__.
-In addition, GNS supports DNS record types, such as A, AAAA or TXT.
-
-For a complete description of the records, please refer to the
-specification at `LSD0001 <https://lsd.gnunet.org/lsd0001>`__.
-
-In the following, we discuss GNS records with specific behaviour or
-special handling in GNUnet.
-
-VPN
-^^^
-
-GNS allows easy access to services provided by the GNUnet Virtual Public
-Network. When the GNS resolver encounters a VPN record it will contact
-the VPN service to try and allocate an IPv4/v6 address (if the queries
-record type is an IP address) that can be used to contact the service.
-
-**Example**
-
-I want to provide access to the VPN service “web.gnu.” on port 80 on
-peer ABC012: Name: www; RRType: VPN; Value: 80 ABC012 web.gnu.
-
-The peer ABC012 is configured to provide an exit point for the service
-“web.gnu.” on port 80 to it’s server running locally on port 8080 by
-having the following lines in the gnunet.conf configuration file:
-
-::
-
- [web.gnunet.]
- TCP_REDIRECTS = 80:localhost4:8080
-
-Synchronizing with legacy DNS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you want to support GNS but the master database for a zone is only
-available and maintained in DNS, GNUnet includes the gnunet-zoneimport
-tool to monitor a DNS zone and automatically import records into GNS.
-Today, the tool does not yet support DNS AF(X)R, as we initially used it
-on the “.fr” zone which does not allow us to perform a DNS zone
-transfer. Instead, gnunet-zoneimport reads a list of DNS domain names
-from stdin, issues DNS queries for each, converts the obtained records
-(if possible) and stores the result in the namestore.
-
-The zonemaster service then takes the records from the namestore,
-publishes them into the DHT which makes the result available to the GNS
-resolver. In the GNS configuration, non-local zones can be configured to
-be intercepted by specifying “.tld = PUBLICKEY” in the configuration
-file in the “[gns]” section.
-
-Note that the namestore by default also populates the namecache. This
-pre-population is cryptographically expensive. Thus, on systems that
-only serve to import a large (millions of records) DNS zone and that do
-not have a local gns service in use, it is thus advisable to disable the
-namecache by setting the option “DISABLE” to “YES” in section
-“[namecache]”.
-
-Migrating an existing DNS zone into GNS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Ascension is a tool to migrate existing DNS zones into GNS.
-
-Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR
-depending on whether or not there exists a SOA record for the zone. If
-that is the case it will take the serial as a reference point and
-request the zone. The server will either answer the IXFR request with a
-correct incremental zone or with the entire zone, which depends on the
-server configuration.
-
-Before you can migrate any zone though, you need to start a local GNUnet
-peer. To migrate the Syrian top level domain - one of the few top level
-domains that support zone transfers - into GNS use the following
-command:
-
-::
-
- $ ascension sy. -n ns1.tld.sy. -p
-
-The -p flag will tell GNS to put these records on the DHT so that other
-users may resolve these records by using the public key of the zone.
-
-Once the zone is migrated, Ascension will output a message telling you,
-that it will refresh the zone after the time has elapsed. You can
-resolve the names in the zone directly using GNS or if you want to use
-it with your browser, check out the GNS manual section. Configuring the
-GNU Name System. To resolve the records from another system you need the
-respective zones PKEY. To get the zones public key, you can run the
-following command:
-
-::
-
- $ gnunet-identity -dqe sy
-
-Where “sy” is the name of the zone you want to migrate.
-
-You can share the PKEY of the zone with your friends. They can then
-resolve records in the zone by doing a lookup replacing the zone label
-with your PKEY:
-
-::
-
- $ gnunet-gns -t SOA -u "$PKEY"
-
-The program will continue to run as a daemon and update once the refresh
-time specified in the zones SOA record has elapsed.
-
-DNSCurve style records are supported in the latest release and they are
-added as a PKEY record to be referred to the respective GNS public key.
-Key distribution is still a problem but provided someone else has a
-public key under a given label it can be looked up.
-
-There is an unofficial Debian package called python3-ascension that adds
-a system user ascension and runs a GNUnet peer in the background.
-
-Ascension-bind is also an unofficial Debian package that on installation
-checks for running DNS zones and whether or not they are transferable
-using DNS zone transfer (AXFR). It asks the administrator which zones to
-migrate into GNS and installs a systemd unit file to keep the zone up to
-date. If you want to migrate different zones you might want to check the
-unit file from the package as a guide.
-
-re:claimID
-----------
-
-File-sharing
-------------
-
-This chapter documents the GNUnet file-sharing application. The original
-file-sharing implementation for GNUnet was designed to provide anonymous
-file-sharing. However, over time, we have also added support for
-non-anonymous file-sharing (which can provide better performance).
-Anonymous and non-anonymous file-sharing are quite integrated in GNUnet
-and, except for routing, share most of the concepts and implementation.
-There are three primary file-sharing operations: publishing, searching
-and downloading. For each of these operations, the user specifies an
-anonymity level. If both the publisher and the searcher/downloader
-specify “no anonymity”, non-anonymous file-sharing is used. If either
-user specifies some desired degree of anonymity, anonymous file-sharing
-will be used.
-
-After a short introduction, we will first look at the various concepts
-in GNUnet’s file-sharing implementation. Then, we will discuss specifics
-as to how they impact users that publish, search or download files.
-
-Searching
-~~~~~~~~~
-
-The command ``gnunet-search`` can be used to search for content on
-GNUnet. The format is:
-
-::
-
- $ gnunet-search [-t TIMEOUT] KEYWORD
-
-The ``-t`` option specifies that the query should timeout after
-approximately ``TIMEOUT`` seconds. A value of zero (“0”) is interpreted
-as no timeout, which is the default. In this case, gnunet-search will
-never terminate (unless you press CTRL-C).
-
-If multiple words are passed as keywords, they will all be considered
-optional. Prefix keywords with a “+” to make them mandatory.
-
-Note that searching using:
-
-::
-
- $ gnunet-search Das Kapital
-
-is not the same as searching for
-
-::
-
- $ gnunet-search "Das Kapital"
-
-as the first will match files shared under the keywords “Das” or
-“Kapital” whereas the second will match files shared under the keyword
-“Das Kapital”.
-
-Search results are printed like this:
-
-::
-
- #15:
- gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
-
-The whole line is the command you would have to enter to download the
-file. The first argument passed to ``-o`` is the suggested filename (you
-may change it to whatever you like). It is followed by the key for
-decrypting the file, the query for searching the file, a checksum (in
-hexadecimal) finally the size of the file in bytes.
-
-Downloading
-~~~~~~~~~~~
-
-In order to download a file, you need the whole line returned by
-gnunet-search. You can then use the tool ``gnunet-download`` to obtain
-the file:
-
-::
-
- $ gnunet-download -o <FILENAME> <GNUNET-URL>
-
-``FILENAME`` specifies the name of the file where GNUnet is supposed to
-write the result. Existing files are overwritten. If the existing file
-contains blocks that are identical to the desired download, those blocks
-will not be downloaded again (automatic resume).
-
-If you want to download the GPL from the previous example, you do the
-following:
-
-::
-
- $ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
-
-If you ever have to abort a download, you can continue it at any time by
-re-issuing gnunet-download with the same filename. In that case, GNUnet
-will **not** download blocks again that are already present.
-
-GNUnet’s file-encoding mechanism will ensure file integrity, even if the
-existing file was not downloaded from GNUnet in the first place.
-
-You may want to use the ``-V`` switch to turn on verbose reporting. In
-this case, gnunet-download will print the current number of bytes
-downloaded whenever new data was received.
-
-Publishing
-~~~~~~~~~~
-
-The command ``gnunet-publish`` can be used to add content to the
-network. The basic format of the command is:
-
-::
-
- $ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
-
-For example:
-
-::
-
- $ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING
-
-The option ``-k`` is used to specify keywords for the file that should
-be inserted. You can supply any number of keywords, and each of the
-keywords will be sufficient to locate and retrieve the file. Please note
-that you must use the ``-k`` option more than once – one for each
-expression you use as a keyword for the filename.
-
-The ``-m`` option is used to specify meta-data, such as descriptions.
-You can use ``-m`` multiple times. The ``TYPE`` passed must be from the
-list of meta-data types known to libextractor. You can obtain this list
-by running ``extract -L``. Use quotes around the entire meta-data
-argument if the value contains spaces. The meta-data is displayed to
-other users when they select which files to download. The meta-data and
-the keywords are optional and may be inferred using GNU libextractor.
-
-``gnunet-publish`` has a few additional options to handle namespaces and
-directories. Refer to the man-page for details.
-
-Indexing vs Inserting
-~~~~~~~~~~~~~~~~~~~~~
-
-By default, GNUnet indexes a file instead of making a full copy. This is
-much more efficient, but requires the file to stay unaltered at the
-location where it was when it was indexed. If you intend to move, delete
-or alter a file, consider using the option ``-n`` which will force
-GNUnet to make a copy of the file in the database.
-
-Since it is much less efficient, this is strongly discouraged for large
-files. When GNUnet indexes a file (default), GNUnet does **not** create
-an additional encrypted copy of the file but just computes a summary (or
-index) of the file. That summary is approximately two percent of the
-size of the original file and is stored in GNUnet’s database. Whenever a
-request for a part of an indexed file reaches GNUnet, this part is
-encrypted on-demand and send out. This way, there is no need for an
-additional encrypted copy of the file to stay anywhere on the drive.
-This is different from other systems, such as Freenet, where each file
-that is put online must be in Freenet’s database in encrypted format,
-doubling the space requirements if the user wants to preserve a directly
-accessible copy in plaintext.
-
-Thus indexing should be used for all files where the user will keep
-using this file (at the location given to gnunet-publish) and does not
-want to retrieve it back from GNUnet each time. If you want to remove a
-file that you have indexed from the local peer, use the tool
-gnunet-unindex to un-index the file.
-
-The option ``-n`` may be used if the user fears that the file might be
-found on their drive (assuming the computer comes under the control of
-an adversary). When used with the ``-n`` flag, the user has a much
-better chance of denying knowledge of the existence of the file, even if
-it is still (encrypted) on the drive and the adversary is able to crack
-the encryption (e.g. by guessing the keyword).
-
-Concepts
-~~~~~~~~
-
-For better results with filesharing it is useful to understand the
-following concepts. In addition to anonymous routing GNUnet attempts to
-give users a better experience in searching for content. GNUnet uses
-cryptography to safely break content into smaller pieces that can be
-obtained from different sources without allowing participants to corrupt
-files. GNUnet makes it difficult for an adversary to send back bogus
-search results. GNUnet enables content providers to group related
-content and to establish a reputation. Furthermore, GNUnet allows
-updates to certain content to be made available. This section is
-supposed to introduce users to the concepts that are used to achieve
-these goals.
-
-TODO concepts. Should they be here?
