gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

concepts.rst (8504B)


      1 .. _gns-concepts:
      2 
      3 Concepts
      4 ========
      5 
      6 This page explains the handful of ideas you need to use GNS: zones, records,
      7 start zones, delegation and the record types GNS adds to those of DNS.  For
      8 the complete, normative description see :rfc:`9498`.
      9 
     10 Zones and egos
     11 --------------
     12 
     13 A GNS *zone* is a set of records controlled by a key pair.  Whoever holds
     14 the private key can add, change and delete records; everybody else
     15 identifies the zone by its public key.  There is no registry: creating a
     16 zone is as simple as creating a key pair.
     17 
     18 In GNUnet, key pairs that you own are called **egos** and are managed with
     19 ``gnunet-identity``.  Every ego can serve as a GNS zone.  Egos may stand for
     20 pseudonyms, organizations or your real-world identity; it is a good idea to
     21 use separate egos for separate activities.
     22 
     23 .. code-block:: console
     24 
     25    $ gnunet-identity -C myzone
     26    $ gnunet-identity -d
     27    myzone - 000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC - EdDSA
     28 
     29 The name ``myzone`` is only a local nickname for the ego, visible to you
     30 alone.  The long string is the zone's public key: that is what identifies
     31 the zone to everybody else.
     32 
     33 New zones use EdDSA keys.  Zones created with older versions may use ECDSA
     34 keys; these remain supported, but creating new ones is deprecated.  The key
     35 type matters in one place: delegation records to EdDSA zones have the type
     36 ``EDKEY``, and those to ECDSA zones the type ``PKEY``.
     37 
     38 Records
     39 -------
     40 
     41 A zone maps *labels* (such as ``www``) to *record sets*.  Each record has
     42 
     43 - a **type**, such as ``A`` (IPv4 address) or ``EDKEY`` (delegation),
     44 - a **value**,
     45 - an **expiration time**, after which resolvers discard it, and
     46 - **flags**, most importantly whether the record is *public* or *private*.
     47 
     48 Records are **private by default**.  Private records only resolve on your
     49 own peer; they are never published.  Records marked *public* are signed,
     50 encrypted and published in the DHT so that others can resolve them.  The
     51 special label ``@`` denotes the zone apex, the equivalent of the bare domain
     52 name in DNS.
     53 
     54 How names are resolved
     55 ----------------------
     56 
     57 GNS names look like DNS names and are read from right to left:
     58 
     59 1. The rightmost part of the name selects a **start zone** (see below).
     60    In ``www.alice.myzone``, that is your own zone ``myzone``.
     61 2. Each remaining label, right to left, is looked up in the current zone.
     62    If the label holds a **delegation record**, resolution continues in the
     63    zone it points to.  Here ``alice`` in ``myzone`` delegates to Alice's
     64    zone.
     65 3. The last label (``www``) is looked up in the final zone, and its records
     66    are returned.
     67 
     68 Every record set is verified against the key of the zone that is supposed
     69 to have published it, so a peer that delivers a forged answer is detected.
     70 
     71 Start zones
     72 -----------
     73 
     74 In GNS you are the master of your own root: the mapping from name suffixes
     75 to zones that DNS delegates to ICANN is, in GNS, your own configuration.
     76 There are three kinds of start zones.
     77 
     78 Your own zones
     79    Every ego is a start zone.  Names ending in ``.myzone`` are resolved in
     80    your zone ``myzone``.
     81 
     82 Configured suffixes
     83    The ``[gns]`` configuration section maps name suffixes to zone keys.
     84    GNUnet ships with a small default set, currently
     85 
     86    - ``.pin.gns.alt``: a first-come, first-served registry run by GNUnet
     87      e.V., where anyone can register a name (see :doc:`sharing`), and
     88    - ``.gnunet.gns.alt``: the zone of the GNUnet project.
     89 
     90    The default set is maintained in `GANA <https://gana.gnunet.org>`__ under
     91    a `restrictive registration policy
     92    <https://git.gnunet.org/gana.git/tree/gnu-name-system-default-tlds/POLICY>`__.
     93    You can list the configured suffixes, and add your own, with
     94    ``gnunet-config``:
     95 
     96    .. code-block:: console
     97 
     98       $ gnunet-config -s gns | grep '^\.'
     99       $ gnunet-config -s gns -o .myfriend -V 000G0...ZONEKEY
    100 
    101 Zone keys (zTLDs)
    102    A zone's public key can itself be used as the top-level domain.  This
    103    works without any configuration and is mostly useful in programs and
    104    when exchanging names with people whose zone you have not (yet) added:
    105 
    106    .. code-block:: console
    107 
    108       $ gnunet-gns -u www.000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC
    109 
    110 Delegation and petnames
    111 -----------------------
    112 
    113 Delegation is what makes GNS a *system* of names rather than a collection of
    114 private address books.  If your friend Alice gives you her zone key, you
    115 store it under a label of your choice, say ``alice``, as an ``EDKEY`` record:
    116 
    117 .. code-block:: console
    118 
    119    $ gnunet-namestore -z myzone -a -n alice -t EDKEY -V 000G0...ALICEKEY -e 1d
    120 
    121 From then on, every public record in Alice's zone is reachable below
    122 ``alice.myzone``: her ``www`` record as ``www.alice.myzone``.  If Alice in
    123 turn has a public delegation to Carol under ``carol``, then Carol's ``www``
    124 is ``www.carol.alice.myzone`` for you.
    125 
    126 The label you chose, ``alice``, is a **petname**: a name that is meaningful
    127 to you.  Somebody else may know Alice's zone as ``ally`` or ``work``.  Names
    128 in GNS are therefore not globally unique; they are relative to whoever
    129 resolves them.  A zone can suggest a preferred name for itself with a
    130 ``NICK`` record (``gnunet-namestore -z myzone -i alice``), but nobody is
    131 obliged to use it.
    132 
    133 Relative names
    134 --------------
    135 
    136 Some record types, for example ``CNAME``, ``MX`` and ``REDIRECT``, contain
    137 names.  A name ending in ``.+`` is *relative to the zone it was found in*:
    138 the resolver replaces the ``+`` with that zone's key.  If Alice's zone
    139 contains an ``MX`` record pointing to ``mail.+``, the answer you get is
    140 ``mail.000G0...ALICEKEY``, which resolves correctly no matter what petname
    141 you use for Alice's zone.  Relative names can also be used in links on web
    142 pages served under a GNS name.
    143 
    144 Record types
    145 ------------
    146 
    147 GNS supports the common DNS record types, including ``A``, ``AAAA``,
    148 ``CNAME``, ``MX``, ``TXT``, ``SRV`` and ``TLSA``.  In addition it defines
    149 record types of its own, registered in `GANA
    150 <https://git.gnunet.org/gana.git/tree/gnu-name-system-record-types/registry.rec>`__.
    151 The ones you are most likely to meet are:
    152 
    153 .. list-table::
    154    :header-rows: 1
    155    :widths: 20 80
    156 
    157    * - Type
    158      - Purpose
    159    * - ``EDKEY``, ``PKEY``
    160      - Delegation to another GNS zone (EdDSA or ECDSA key).
    161    * - ``GNS2DNS``
    162      - Delegation to a zone in DNS: the rest of the name is resolved via
    163        the given DNS name servers.
    164    * - ``NICK``
    165      - The zone's preferred name for itself.
    166    * - ``LEHO``
    167      - The legacy (DNS) host name of a service, used for HTTP virtual
    168        hosting and for validating TLS certificates.
    169    * - ``BOX``
    170      - Wraps ``SRV`` and ``TLSA`` records with their service and protocol,
    171        so that names like ``_443._tcp.www`` work.
    172    * - ``REDIRECT``
    173      - Redirects resolution of a name to another name.
    174    * - ``VPN``
    175      - Points to a service offered by a GNUnet peer through the GNUnet VPN;
    176        the resolver allocates a local IP address for it (see
    177        :doc:`/users/vpn`).
    178 
    179 Several other types are used internally by re:claimID and the messenger.
    180 For the exact format and processing rules of all records see
    181 :rfc:`9498`.
    182 
    183 Security and privacy properties
    184 -------------------------------
    185 
    186 What GNS protects:
    187 
    188 - **Integrity and authenticity.**  Record sets are signed with the zone key;
    189   forged or modified answers are rejected.
    190 - **Query privacy.**  Records are stored in the DHT under a key derived from
    191   the zone key and the label, and encrypted with a key derived from the same
    192   pair.  Peers that store or forward them cannot tell which name they belong
    193   to or what it resolves to, unless they already know both the zone key and
    194   the label.
    195 - **Censorship resistance.**  There is no registrar or root operator that
    196   could be compelled to change or remove a name.  Only the holder of the
    197   private key can change a zone.
    198 
    199 What GNS does *not* protect against:
    200 
    201 - Someone who knows a zone's key can check whether a label they guess exists
    202   in that zone.  Do not rely on a label being secret.
    203 - If the private key of a zone is stolen, the thief can publish records in
    204   your name.  Prepare a revocation certificate in advance (see
    205   :ref:`gns-revocation`).
    206 - A delegation is only as trustworthy as the way you obtained the key.  A
    207   name like ``www.carol.alice.myzone`` makes the chain of trust explicit:
    208   you rely on Alice to have Carol's correct key.
    209 - GNS does not hide that your peer participates in GNUnet, and it does not
    210   anonymize the connections you make *after* resolving a name.