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.