.. _gns-concepts: Concepts ======== This page explains the handful of ideas you need to use GNS: zones, records, start zones, delegation and the record types GNS adds to those of DNS. For the complete, normative description see :rfc:`9498`. Zones and egos -------------- A GNS *zone* is a set of records controlled by a key pair. Whoever holds the private key can add, change and delete records; everybody else identifies the zone by its public key. There is no registry: creating a zone is as simple as creating a key pair. In GNUnet, key pairs that you own are called **egos** and are managed with ``gnunet-identity``. Every ego can serve as a GNS zone. Egos may stand for pseudonyms, organizations or your real-world identity; it is a good idea to use separate egos for separate activities. .. code-block:: console $ gnunet-identity -C myzone $ gnunet-identity -d myzone - 000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC - EdDSA The name ``myzone`` is only a local nickname for the ego, visible to you alone. The long string is the zone's public key: that is what identifies the zone to everybody else. New zones use EdDSA keys. Zones created with older versions may use ECDSA keys; these remain supported, but creating new ones is deprecated. The key type matters in one place: delegation records to EdDSA zones have the type ``EDKEY``, and those to ECDSA zones the type ``PKEY``. Records ------- A zone maps *labels* (such as ``www``) to *record sets*. Each record has - a **type**, such as ``A`` (IPv4 address) or ``EDKEY`` (delegation), - a **value**, - an **expiration time**, after which resolvers discard it, and - **flags**, most importantly whether the record is *public* or *private*. Records are **private by default**. Private records only resolve on your own peer; they are never published. Records marked *public* are signed, encrypted and published in the DHT so that others can resolve them. The special label ``@`` denotes the zone apex, the equivalent of the bare domain name in DNS. How names are resolved ---------------------- GNS names look like DNS names and are read from right to left: 1. The rightmost part of the name selects a **start zone** (see below). In ``www.alice.myzone``, that is your own zone ``myzone``. 2. Each remaining label, right to left, is looked up in the current zone. If the label holds a **delegation record**, resolution continues in the zone it points to. Here ``alice`` in ``myzone`` delegates to Alice's zone. 3. The last label (``www``) is looked up in the final zone, and its records are returned. Every record set is verified against the key of the zone that is supposed to have published it, so a peer that delivers a forged answer is detected. Start zones ----------- In GNS you are the master of your own root: the mapping from name suffixes to zones that DNS delegates to ICANN is, in GNS, your own configuration. There are three kinds of start zones. Your own zones Every ego is a start zone. Names ending in ``.myzone`` are resolved in your zone ``myzone``. Configured suffixes The ``[gns]`` configuration section maps name suffixes to zone keys. GNUnet ships with a small default set, currently - ``.pin.gns.alt``: a first-come, first-served registry run by GNUnet e.V., where anyone can register a name (see :doc:`sharing`), and - ``.gnunet.gns.alt``: the zone of the GNUnet project. The default set is maintained in `GANA `__ under a `restrictive registration policy `__. You can list the configured suffixes, and add your own, with ``gnunet-config``: .. code-block:: console $ gnunet-config -s gns | grep '^\.' $ gnunet-config -s gns -o .myfriend -V 000G0...ZONEKEY Zone keys (zTLDs) A zone's public key can itself be used as the top-level domain. This works without any configuration and is mostly useful in programs and when exchanging names with people whose zone you have not (yet) added: .. code-block:: console $ gnunet-gns -u www.000G0507HZ8M09QWA93N2YX9Y9357777C0HTPK7PA0HTKJS5GCXXPGKBWC Delegation and petnames ----------------------- Delegation is what makes GNS a *system* of names rather than a collection of private address books. If your friend Alice gives you her zone key, you store it under a label of your choice, say ``alice``, as an ``EDKEY`` record: .. code-block:: console $ gnunet-namestore -z myzone -a -n alice -t EDKEY -V 000G0...ALICEKEY -e 1d From then on, every public record in Alice's zone is reachable below ``alice.myzone``: her ``www`` record as ``www.alice.myzone``. If Alice in turn has a public delegation to Carol under ``carol``, then Carol's ``www`` is ``www.carol.alice.myzone`` for you. The label you chose, ``alice``, is a **petname**: a name that is meaningful to you. Somebody else may know Alice's zone as ``ally`` or ``work``. Names in GNS are therefore not globally unique; they are relative to whoever resolves them. A zone can suggest a preferred name for itself with a ``NICK`` record (``gnunet-namestore -z myzone -i alice``), but nobody is obliged to use it. Relative names -------------- Some record types, for example ``CNAME``, ``MX`` and ``REDIRECT``, contain names. A name ending in ``.+`` is *relative to the zone it was found in*: the resolver replaces the ``+`` with that zone's key. If Alice's zone contains an ``MX`` record pointing to ``mail.+``, the answer you get is ``mail.000G0...ALICEKEY``, which resolves correctly no matter what petname you use for Alice's zone. Relative names can also be used in links on web pages served under a GNS name. Record types ------------ GNS supports the common DNS record types, including ``A``, ``AAAA``, ``CNAME``, ``MX``, ``TXT``, ``SRV`` and ``TLSA``. In addition it defines record types of its own, registered in `GANA `__. The ones you are most likely to meet are: .. list-table:: :header-rows: 1 :widths: 20 80 * - Type - Purpose * - ``EDKEY``, ``PKEY`` - Delegation to another GNS zone (EdDSA or ECDSA key). * - ``GNS2DNS`` - Delegation to a zone in DNS: the rest of the name is resolved via the given DNS name servers. * - ``NICK`` - The zone's preferred name for itself. * - ``LEHO`` - The legacy (DNS) host name of a service, used for HTTP virtual hosting and for validating TLS certificates. * - ``BOX`` - Wraps ``SRV`` and ``TLSA`` records with their service and protocol, so that names like ``_443._tcp.www`` work. * - ``REDIRECT`` - Redirects resolution of a name to another name. * - ``VPN`` - Points to a service offered by a GNUnet peer through the GNUnet VPN; the resolver allocates a local IP address for it (see :doc:`/users/vpn`). Several other types are used internally by re:claimID and the messenger. For the exact format and processing rules of all records see :rfc:`9498`. Security and privacy properties ------------------------------- What GNS protects: - **Integrity and authenticity.** Record sets are signed with the zone key; forged or modified answers are rejected. - **Query privacy.** Records are stored in the DHT under a key derived from the zone key and the label, and encrypted with a key derived from the same pair. Peers that store or forward them cannot tell which name they belong to or what it resolves to, unless they already know both the zone key and the label. - **Censorship resistance.** There is no registrar or root operator that could be compelled to change or remove a name. Only the holder of the private key can change a zone. What GNS does *not* protect against: - Someone who knows a zone's key can check whether a label they guess exists in that zone. Do not rely on a label being secret. - If the private key of a zone is stolen, the thief can publish records in your name. Prepare a revocation certificate in advance (see :ref:`gns-revocation`). - A delegation is only as trustworthy as the way you obtained the key. A name like ``www.carol.alice.myzone`` makes the chain of trust explicit: you rely on Alice to have Carol's correct key. - GNS does not hide that your peer participates in GNUnet, and it does not anonymize the connections you make *after* resolving a name.