commit d86773638e15598d51559ab2cbaf8883f86caab3
parent a47ea0eb76677b0171a2bb65bb43fae1e4e3df75
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Tue, 18 Oct 2022 13:25:13 +0900
more GNS handbook updates
Diffstat:
3 files changed, 325 insertions(+), 231 deletions(-)
diff --git a/gana/index.rst b/gana/index.rst
@@ -1,3 +1,5 @@
+.. _GANA:
+
GANA
====
diff --git a/installing.rst b/installing.rst
@@ -54,13 +54,13 @@ The mandatory libraries and applications are
Glibc is required for certain NSS features:
-::
+.. code-block:: text
- One mechanism of integrating GNS with legacy applications via NSS is
- not available if this is disabled. But applications that don't use the
- glibc for NS resolution won't work anyway with this, so little is lost
- on *BSD systems.
- GNS via direct use or via the HTTP or DNS proxies is unaffected.
+ One mechanism of integrating GNS with legacy applications via NSS is
+ not available if this is disabled. But applications that don't use the
+ glibc for NS resolution won't work anyway with this, so little is lost
+ on *BSD systems.
+ GNS via direct use or via the HTTP or DNS proxies is unaffected.
Other libcs should work, the resulting builds just don’t include the
glibc NSS specific code. One example is the build against NetBSD’s libc
@@ -89,7 +89,7 @@ These are the dependencies only required for certain features
About libextractor being optional:
-::
+.. code-block:: text
While libextractor ("LE") is optional, it is recommended to build gnunet
against it. If you install it later, you won't benefit from libextractor.
@@ -238,20 +238,6 @@ Copy the GNS NSS plugin to that directory:
cp ~/gnunet/src/gns/nss/.libs/libnss_gns.so.2 /lib
-Now, to activate the plugin, you need to edit your
-``/etc/nsswitch.conf`` where you should find a line like this:
-
-::
-
- hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
-
-The exact details may differ a bit, which is fine. Add the text
-``gns [NOTFOUND=return]`` after ``files``:
-
-::
-
- hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
-
Installing the GNS Certificate Authority (Optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/users/gns.rst b/users/gns.rst
@@ -12,40 +12,59 @@ GNS is designed to provide:
- 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
+public key. Delegation to another user’s zone is done using special delegation
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.
+For a complete specification of the protocl, we refer to `LSD0001 <https://lsd.gnunet.org/lsd0001>`__.
+
Start Zones
~~~~~~~~~~~
-In the default configuration, there are two zones defined and shipped
-with GNUnet:
+In GNS you are the master of your own Root.
+This means that you are able (and encouraged!) to manage your own *Start Zones*.
+A *Start Zone* is a mapping from a name suffix (e.g. ``.gnunet.org``) to
+a GNS zone key.
+A user's configuration of *Start Zones* is the equivalent of DNS's `Root Zone <https://en.wikipedia.org/wiki/DNS_root_zone>`_.
+In other words, in GNS you can be your very own `ICANN <https://en.wikipedia.org/wiki/ICANN>`_.
+
+There are three types of *Start Zones*:
+
+ 1. Mappings to *remote* GNS zones.
+ 2. Mappings to your own *local* GNS zones.
+ 3. Explicit zone Top-Level-Domains (zTLDs)
+
+External
+""""""""
+
+Your GNUnet installation ships with a default configuration of *Start Zones*.
+The first is ``.gnunet.org``, which points to the authoritate zone of the
+GNUnet project.
+This *Start Zone* allows you to resolve names ending with ``.gnunet.org``.
+It can be used to resolve, for example, ``www.gnunet.org``.
+
+You can try it out for yourself (if you are connected to the peer-to-peer network):
-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”.
+::
+
+ $ gnunet-gns --lookup=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”.
+Another *Start Zone* configured by default is ``.pin``.
+It points to a special zone also managed by the GNUnet project.
+Users may register submodomains on a first-come first-served-basis at https://fcfs.gnunet.org.
-You can configure any number of top-level domains, and point them to the
+Use ``gnunet-config -s gns`` to view the GNS configuration, including all
+configured external zones that are operated by other users.
+The respective configuration entry names start with a ``.``, e.g. ``.pin``.
+
+You can change this default configuration at any time and add *Start Zone* to the
respective zones of your friends! For this, simply obtain the respective
public key (you will learn how below) and extend the configuration:
@@ -53,32 +72,33 @@ public key (you will learn how below) and extend the configuration:
$ gnunet-config -s gns -o .myfriend -V PUBLIC_KEY
+Local
+"""""
-Maintaining Zones
-~~~~~~~~~~~~~~~~~
-
-Creation and deletion
-"""""""""""""""""""""
-
-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.
+In order to create a local GNS zone you have to create a so-called ``ego`` in GNUnet.
+Egos may correspond to pseudonyms or real-world identities.
+It is recommended to use separate egos for separate activities.
+All egos can potentially serve as a GNS zone, but you do not have to use
+all egos as GNS zones.
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.
+egos also always correspond to a GNS zone. Egos are managed through the
+IDENTITY service and its tooling.
+The IDENTITY service is used to create and stores private keys with associated
+human-readable nicknames.
+Those mappings serve as local *Start Zones*.
-You can create any number of zones using the gnunet-identity tool using:
+For example, you can create a new ego (or zone) with name *myzone* using the
+``gnunet-identity`` tool using:
::
$ gnunet-identity --create="myzone"
Henceforth, on your system you control the TLD ``myzone``.
+You are able to resolve GNS names ending with ``.myzone``.
+However, the zone is still empty.
+We will look at local zone maintenance in the next section.
Note that by default, this will create ECDSA key pairs.
GNS also supports the use of EdDSA keys.
In order to create a EdDSA zone, execute:
@@ -94,11 +114,35 @@ command line tool as well:
$ gnunet-identity --display
-One you have created an identity, you can configure and initialize your NAMESTORE
-database.
+
+
+Zone Top-Level-Domains
+""""""""""""""""""""""
+
+If you know the public key of a GNS zone, you can resolve records in that zone
+without a *Start Zone* mapping.
+To do so, you must provide the string-representation of the zone key
+as Top-Level Domain. Consider the zone key of ``.gnunet.org`` in the default
+configuration. In order to resolve the same record as above using its respective
+zTLD, you can do so as follows:
+
+::
+
+ $ gnunet-gns --lookup=www.000G0047M3HN599H57MPXZK4VB59SWK4M9NRD68E1JQFY3RWAHDMKAPN30
+
+The use of zTLDs is mostly useful in the absence of a *Start Zone* configuration
+for that zone or when querying names programatically.
+
+Local zone maintenance
+~~~~~~~~~~~~~~~~~~~~~~
+
+So you are ready to maintain your own GNS zone? Great.
+First you should review and optionally configure your NAMESTORE database which
+will hold your zone's resource records.
You have the choice between ``sqlite`` and ``postgres`` as databases.
-Most users will be served well with the ``sqlite`` default.
-To set the database backend of your NAMESTORE to ``postgres`` execute:
+Most users will be served well with the ``sqlite`` backend and with its default
+configuration.
+To change the database backend of your NAMESTORE to ``postgres`` execute:
::
@@ -111,16 +155,12 @@ See the ``namestore-postgres`` configuration section on possible options:
$ gnunet-config -s namestore-postgres
-If you ever need to reset your zone database, you can use ``gnunet-namestore-dbtool``.
+If you ever need to reset your zone database, you can use ``gnunet-namestore-dbtool``
+with the ``--reset`` option.
**DANGER: This command will delete ALL of your records in all zones!**
-::
-
- $ gnunet-namestore-dbtool --plugin=postgres --reset
-
-
-Record management
-"""""""""""""""""
+Records
+"""""""
At this point you can add (or edit, or remove) records in your GNS zone using the
using the gnunet-namestore command-line tool.
@@ -131,19 +171,43 @@ 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”
+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
+ $ gnunet-namestore --zone=myzone \
+ --add \
+ --name=www \
+ --type=A \
+ --value=1.2.3.4 \
+ --expiration=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.
+Note that by default, records are **private**. This means that they are not
+published and cannot be resolved by other users that may have configured your
+zone as one of their ``Start Zones``.
+In order to create a public record, provide the ``--public`` switch to the
+``gnunet-namestore`` command above.
+
+You can now try to resolve your own GNS record. The method we found
+to be the most uncomplicated is to do this by explicitly resolving using
+``gnunet-gns``.
+In the shell, type:
+
+::
+
+ $ gnunet-gns -u www.myzone
+
+You should receive the record as configured above.
+At this point, you can try addition additional records to ``www`` or add other
+names to your zone.
+
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
@@ -161,24 +225,97 @@ to their local zone:
::
- $ gnunet-namestore -a -n bob --type PKEY -V XXXX -e 1d -z myzone
+ $ gnunet-namestore -a -n bob --type PKEY -V $BOBKEY -e 1d -z myzone
-Note that “XXXX” in the command above must be replaced with the hash of
+Note that ``$BOBKEY`` 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” —
+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
+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).
+You can find more detailed information in available record types in the
+`Resource Records`_ section.
+
+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 ``myzone``:
+
+::
+
+ $ gnunet-revocation -f revocation.dat -R myzone
+
+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``.
+
+Backup
+""""""
+
+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.
+
+This does **NOT** backup your record data.
+Your record data is stored in the respective database backend, and hence
+you may want to backup the respective databases as well.
+
+
Large Zones
"""""""""""
@@ -199,24 +336,21 @@ use of the bulk import functionality of the NAMESTORE API.
There is a :ref:`C API for bulk imports <NAMESTORE-Subsystem>`.
There is also a :ref:`REST API endpoint <namestore_rest_api>` which calls this API.
-Name resolution
-~~~~~~~~~~~~~~~
+Application integration
+~~~~~~~~~~~~~~~~~~~~~~~
-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.
+Once you have verified that resolution of names using ``gnunet-gns`` works,
+we can start integrating GNS with applications.
+We can distinguish between two types of applications:
-In the shell, type:
+ 1. **GNS-aware applications**: Such applications know what GNS is and how it
+ can be used to resolve names. Examples are some of GNUnet's services such
+ as `re:claimID <reclaimID-Identity-Provider>`_ or `Messenger <Using-the-GNUnet-Messenger>`_.
+ 2. **GNS-unaware applications**: Applications that implicity assume the names
+ are resolved through DNS. Such applications use OS-specific APIs or query
+ configured DNS servers directly.
-::
-
- $ gnunet-gns -u www.gnunet.org
-
-That shows that resolution works, once GNS is integrated with the
-application.
+In the following, we will discuss integration paths of GNS-unaware applications.
Integration with Browsers (DNS2GNS service)
"""""""""""""""""""""""""""""""""""""""""""
@@ -298,7 +432,7 @@ 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
+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
@@ -323,14 +457,14 @@ 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”:
+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”.
+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
@@ -340,12 +474,12 @@ 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
+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
+*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 —
+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.
@@ -354,59 +488,47 @@ 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
-~~~~~~~~~~~~~~~~~~~~~~~~
+NSS plugin
+""""""""""
-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:
+To activate the plugin, you need to edit your
+``/etc/nsswitch.conf`` where you should find a line like this:
-- 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.**
+ hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
+
+The exact details may differ a bit, which is fine. Add the text
+``gns [NOTFOUND=return]`` after ``files``:
::
- apt-get install texlive-full
+ hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
-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:
+Note that some systems, in particular those running systemd-resolvd, manual modification of ``/etc/nsswitch.conf`` is not possible as it is autogenerated.
+In such cases it is better to use the *DNS2GNS* service approach in combination with ``resolvectl`` as explained above.
-::
+Zone dissemination
+~~~~~~~~~~~~~~~~~~
- $ gnunet-bcd
+So you have decided to maintain and publish one or more GNS zones.
+You are probably asking yourself how your zone finds its way into the
+*Start Zone* configuration of other users.
-Then, start a browser and point it to http://localhost:8888/ where
-gnunet-bcd is running a Web server!
+Below are pointers on how to make your zone known.
-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.
+The .pin zone
+"""""""""""""
+
+First, you may want to visit https://fcfs.gnunet.org and register your zone(s)
+with the ``.pin`` top-level domain shipped by default with GNUnet.
+This will allow other GNUnet users to resolve your zone under the name you
+managed to aquire for yourself.
+
+The registration policy of PIN is "first-come, first-served".
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.
@@ -424,7 +546,7 @@ 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”.
+our running example, this would be *gnu*.
Henceforth, for every business card you collect, simply run:
@@ -440,7 +562,7 @@ 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
+names. Suppose your friend’s nickname is *Bob*. Then, type
::
@@ -449,107 +571,87 @@ names. Suppose your friend’s nickname is “Bob”. Then, type
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:
+Creating a business card
+""""""""""""""""""""""""
-The peer identity file can be found in
-``~/.local/share/gnunet/private_key.ecc``.
+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:
-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.
+- texlive-units
+- texlive-labels
+- texlive-pst-barcode
+- texlive-luatex85
+- texlive-preview
+- texlive-pdfcrop
+- texlive-koma-script
-Note: All these files contain cryptographic keys and they are stored
-without any encryption. So it is advisable to backup encrypted copies of
-them.
+**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.**
-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.
+ apt-get install texlive-full
-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.
+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:
-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).
+ $ gnunet-bcd
-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.
+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.
+
+The GNUnet default Start Zones
+""""""""""""""""""""""""""""""
+
+The GNUnet default *Start Zones* are managed through :ref:`GANA <GANA>` and
+follows a `restrictive registration policy <https://git.gnunet.org/gana.git/tree/gnu-name-system-default-tlds/POLICY>`_.
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
+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
+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
+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
+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.
+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>`__.
@@ -557,8 +659,9 @@ 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
@@ -567,11 +670,11 @@ 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
+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
+*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:
::
@@ -579,14 +682,17 @@ having the following lines in the gnunet.conf configuration file:
[web.gnunet.]
TCP_REDIRECTS = 80:localhost4:8080
-Synchronizing with legacy DNS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+DNS Migration
+~~~~~~~~~~~~~
+
+Zoneimport
+""""""""""
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
+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.
@@ -594,18 +700,18 @@ from stdin, issues DNS queries for each, converts the obtained records
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.
+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]”.
+namecache by setting the option *DISABLE* to *YES* in section
+*[namecache]*.
-Migrating an existing DNS zone into GNS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Ascension
+"""""""""
Ascension is a tool to migrate existing DNS zones into GNS.
@@ -640,7 +746,7 @@ following command:
$ gnunet-identity -dqe sy
-Where “sy” is the name of the zone you want to migrate.
+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
