gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

index.rst (4713B)


      1 .. _gns:
      2 
      3 ###################
      4 The GNU Name System
      5 ###################
      6 
      7 The GNU Name System (GNS) is a decentralized, censorship-resistant and
      8 privacy-preserving alternative to the Domain Name System (DNS).  It is the
      9 most mature part of GNUnet, its protocol is published as :rfc:`9498`, and it
     10 is the best place to start if you are new to GNUnet.
     11 
     12 .. tip::
     13 
     14    Want to try it right away?  The :doc:`/quickstart` gets you a working
     15    zone in five commands.
     16 
     17 What GNS gives you
     18 ==================
     19 
     20 **Names that nobody can take away from you.**
     21    In DNS, names are rented from a registrar under rules set by registries
     22    and ICANN, and they can be seized, blocked or redirected.  In GNS, a
     23    *zone* is a key pair that you generate yourself.  Only the holder of the
     24    private key can change the records in a zone.
     25 
     26 **No central root.**
     27    Each user is the root of their own namespace: the names that resolve on
     28    your system are determined by your own configuration.  You link to other
     29    people's zones (*delegation*) under names that you choose (*petnames*).
     30    GNUnet ships with a small default set of zones so that common names work
     31    out of the box.
     32 
     33 **Private lookups.**
     34    Records are encrypted and stored in GNUnet's distributed hash table
     35    (DHT).  The peers that store and route a query learn neither the name
     36    being looked up nor the answer, unless they already know both the zone
     37    and the name.
     38 
     39 **Authentic answers.**
     40    Every record is signed with the zone key, so a resolver can verify an
     41    answer without trusting the network that delivered it.
     42 
     43 **DNS compatibility.**
     44    GNS supports the usual DNS record types (``A``, ``AAAA``, ``MX``,
     45    ``TXT``, ...), can serve unmodified applications through a DNS bridge,
     46    and comes with tools to import existing DNS zones.
     47 
     48 How it works, in one paragraph
     49 ==============================
     50 
     51 Your zone is identified by its public key, for example
     52 ``000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC``.  You add
     53 records to it with ``gnunet-namestore``; your peer signs and encrypts the
     54 records you mark as public and stores them in the DHT.  To resolve
     55 ``www.alice.myzone``, your resolver starts in your own zone ``myzone``,
     56 finds that the label ``alice`` delegates to Alice's zone key, and then
     57 fetches and decrypts the record set for ``www`` in Alice's zone.  Each step
     58 is verified with the respective zone key.  :doc:`concepts` explains this in
     59 detail.
     60 
     61 GNS compared with DNS
     62 =====================
     63 
     64 .. list-table::
     65    :header-rows: 1
     66    :widths: 30 35 35
     67 
     68    * -
     69      - DNS
     70      - GNS
     71    * - Who controls a name
     72      - registrar, registry and ultimately ICANN
     73      - whoever holds the zone's private key
     74    * - Root of trust
     75      - one global root zone
     76      - each user's own start zones
     77    * - Globally unique names
     78      - yes
     79      - no: names are relative to the user (petnames)
     80    * - Query privacy
     81      - queries are visible to resolvers and name servers
     82      - queries and answers are hidden from the peers storing and routing
     83        them
     84    * - Record authenticity
     85      - optional (DNSSEC)
     86      - always (every record set is signed)
     87    * - Censorship
     88      - names can be seized or blocked centrally
     89      - there is no central point at which to seize a name
     90 
     91 The price for this is that names are not globally unique: ``www.alice``
     92 means whatever *you* decided ``alice`` refers to.  The :doc:`faq` discusses
     93 this trade-off.
     94 
     95 Current status
     96 ==============
     97 
     98 GNS is the most mature component of GNUnet.  The protocol is specified in
     99 :rfc:`9498`, its C API is marked stable (see :ref:`Subsystem-stability`),
    100 and managing your own zones and resolving names in them works well.  What
    101 is still rough:
    102 
    103 - Resolving names *in other people's zones* goes through the GNUnet
    104   peer-to-peer network, which is still small and has known connectivity
    105   issues.  Such lookups can be slow or fail; names in your own zones always
    106   resolve locally.
    107 - Using GNS names in browsers and other ordinary applications requires
    108   some manual configuration (see :doc:`integration`).
    109 - Exchanging zone keys via printed business cards and QR codes does not
    110   currently work (see :doc:`sharing`).
    111 
    112 See :doc:`/status` for the state of all GNUnet components.
    113 
    114 In this section
    115 ===============
    116 
    117 .. toctree::
    118    :maxdepth: 1
    119 
    120    concepts
    121    zones
    122    integration
    123    sharing
    124    migration
    125    faq
    126 
    127 Further reading
    128 ===============
    129 
    130 - :rfc:`9498`, the normative specification, maintained as
    131   `LSD 0001 <https://lsd.gnunet.org/lsd0001>`__
    132 - `Talks and videos <https://www.gnunet.org/en/video.html>`__ about GNS
    133 - Research papers in the `GNUnet bibliography <https://bib.gnunet.org>`__
    134 - The :ref:`developer documentation of the GNS subsystem
    135   <GNU-Name-System-_0028GNS_0029>`