Revert "wip TLSA"
[pdns-pipe-nmc.git] / SPEC.md
diff --git a/SPEC.md b/SPEC.md
index 138a75c99794d0258ba06223baec82518466e8a4..4a0fb4ac7fdf82a890821236345580353d9b828e 100644 (file)
--- a/SPEC.md
+++ b/SPEC.md
@@ -1,11 +1,25 @@
 % JSON Domain Format as Implemented by Pdns-Pipe-Nmc
 
+This document is based on
+[Namecoin Domain Name Specification](https://wiki.namecoin.info/index.php?title=Domain_Name_Specification).
+It tries to follow it closely, and clarify parts that are not
+specified, or specified ambiguously, in the original document.
+
+One notable deviation is the specification of `"delegate"` and `"import"`
+attributes: domain objects to which their value point are
+replacing/merging to the domain object in which they are defined.
+This seems to be in line with at least one existing "real world"
+implementation.
+
+This specification is implemented by the `pdns-pipe-nmc` program.
+
 ## Data Format
 
 ### `DomObj` Object
 
-`DomObj` either a `String` containing a dotted quad (see Note below),
-or a JSON `Map`, with the following attributes, all optional:
+`DomObj` is a data structure that is associated with an FQDN. It is
+either a `String` containing a dotted quad (see Note below), or a
+JSON `Map`, with the following attributes, all optional:
 
 | Key         | Type                                  | Comment                                    |
 |-------------|---------------------------------------|--------------------------------------------|
@@ -16,7 +30,7 @@ or a JSON `Map`, with the following attributes, all optional:
 | i2p         | I2pObj                                |                                            |
 | freenet     | String                                |                                            |
 | alias       | String                                | Nullifies other attributes                 |
-| translate   | String                                | Nullifies other attributes                 |
+| translate   | String                                | Nullifies the "map" attribute              |
 | email       | String                                | Used in `SOA`                              |
 | loc         | String                                | Format suitable for `LOC`                  |
 | info        | JsonObj                               | Currently unspecified                      |
@@ -51,7 +65,7 @@ or a JSON `Map`, with the following attributes, all optional:
 | 2 | Int    | Priority |
 | 3 | Int    | Weight   |
 | 4 | Int    | Port     |
-| 5 | String | Hostname |
+| 5 | String | FQDN     |
 
 #### Notes
 
@@ -108,8 +122,8 @@ two levels higher than the `SRV` record would. For example, a
 corresponding to the FQDN "sub.dom.bit" with the value
 
 ```
-"service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com." ],
-             ["smtp", "tcp", 0, 0,  25, "relay.host.com."] ]
+"service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com" ],
+             ["smtp", "tcp", 0, 0,  25, "relay.host.com"] ]
 ```
 
 corresponds to two `SRV` RRs at two different points in the
@@ -127,6 +141,13 @@ level:
 sub.dom.bit. IN MX 0 relay.host.com.
 ```
 
+Note: Hostname element **must** be specified as fully qualified domain
+name of the host, and **must not** terminate with a dot. 
+This requirement seems to be in line with many existing definitions in
+the blockchain; however it deviates from the BIND zone file format, in
+which names that have not terminating dot are automatically expanded
+by attaching the current origin zone to the end of the name.
+
 #### ip attribute
 
 Contains a list of strings representing IPv4 addresses in dotted
@@ -162,27 +183,58 @@ translates into one AAAA RR:
 
 Does not translate into any DNS RR. Contains Tor hidden service address.
 
+```
+"tor": "eqt5g4fuenphqinx.onion"
+```
+
 #### i2p attribute
 
-Does not translate into any DNS RR. Contains an object with three
+Does not translate into any DNS RR. It is a JSON Map with three
 optional String attributes: `"destination"`, `"name"` and `"b32"`.
 
+```
+"i2p": { "destination": "XaZscx...0jGAAAA"
+       , "name": "example.i2p"
+       , "b32" : "ukeu...nkdq.b32.i2p"
+       }
+```
+
 #### freenet attribute
 
 Does not translate into any DNS RR. Contains Freesite key.
 
+```
+"freenet": "USK@0I8g...xbZ4,AQACAAE/Example/42/"
+```
+
 #### alias attribute
 
-Translates into `CNAME` RR. Invalidates all other attributes except
-the element of the `"map"` with empty key. Such element is analysed
-and its contents merged into the base domain before the check.
+Translates into `CNAME` RR. Invalidates all other attributes.
+
+```
+"alias": "realhost.example.bit"
+```
+
+Notes:
+* Hostname **must** be specified as fully qualified domain
+  name of the host, and **must not** terminate with a dot. 
+* Element of the `"map"` with empty key, `"delegate"` and `"import"`
+  are processed before this invalidation takes place.
 
 #### translate attribute
 
 Translates into `DNAME` RR. Invalidates the contents of the `"map"`
-attribute, except the element of the `"map"` with empty key. Such
-element is analysed and its contents merged into the base domain
-before the check.
+attribute.
+
+```
+"translate": "otherhost.bit"
+```
+
+Notes:
+* Hostname **must** be specified as fully qualified domain
+  name of the host, and **must not** terminate with a dot. 
+* Element of the `"map"` with empty key, `"delegate"` and `"import"`
+  are processed before this invalidation takes place.
 
 #### email attribute
 
@@ -190,38 +242,69 @@ Translates into the `email` element of the SOA and RP RRs. The
 value `"email":"user@domain.tld"` becomes `user.domain.tld.`
 in the DNS record.
 
+```
+"email": "hostmaster@example.bit"
+```
+
 #### loc attribute
 
 Translates into `LOC` RR. Value must conform to the format defined
 by [RFC-1876](http://tools.ietf.org/html/rfc1876).
 
+```
+"loc": "46 31 18.000 N 6 34 26.000 E 401.00m 1m 10000m 10m"
+```
+
 #### info attribute
 
 Does not translate into any DNS RR. Contains a JSON object with
-format unspecified at the time of this writing.
+format unspecified at the time of this writing. Intented for
+the registrant information.
 
 #### ns attribute
 
-Translates into `NS` RR. Invalidates all other attributes, except
-the element of the `"map"` with empty key. Such element is analysed
-and its contents merged into the base domain before the check.
+Translates into `NS` RR. Because it effectively delegates all
+control over the domain to external nameservers, it also invalidates
+all other attributes.
+
+```
+"ns": ["ns.myserver.net", "192.168.3.4"]
+```
+
+Notes:
+* Hostname **must** be specified as fully qualified domain
+  name of the host, and **must not** terminate with a dot. 
+* Element of the `"map"` with empty key, `"delegate"` and `"import"`
+  are processed before this invalidation takes place.
 
 #### delegate attribute
 
 Does not translate into any DNS RR. Instead, the value is used as
 a key for namecoin lookup (i.e. the value must be specified with
 the namespace prefix), and the result of the lookup replaces all
-other attributes, except the element of the `"map"` with empty key.
-Such element is analysed and its contents merged into the base
-domain before the check.
+other attributes
+
+```
+"delegate": "s/example74845"
+```
+
+Notes:
+* Element of the `"map"` with empty key, `"delegate"` and
+  `"import"` are processed before this invalidation takes place.
+* Unlike many other attributes, this can only contain a single
+  string as the value, rather than a list.
 
 #### import attribute
 
 Does not translate into any DNS RR. Instead, the value is used as
-a key for namecoin lookup (i.e. the value must be specified with
+the key for namecoin lookup (i.e. the value must be specified with
 the namespace prefix), and the result of the lookup is merged with
 the current domain object.
 
+```
+"import": ["dd/example", "s/example6473"]
+```
+
 #### map attribute
 
 JSON Map object containing subdomain names as its keys and domain
@@ -235,6 +318,33 @@ current domain object (`import` and `delegate` lookups) start when
 the empty element of the `"map"` has been recursively merged into
 the current object.
 
+```
+"map": { "www": { "alias" : "www.example.com" }
+       , "www2": { "delegate": "d/example" }
+       }
+```
+
+Note: When a key contains dots ".", it is converted to a nested
+map.  If empty element appears as a result of split, such as when
+a dot is at the beginning or at the end of the key, or there are
+consequitive dots, such elemets are ignored. For example,
+
+```
+"map": { "www.uk": { "alias" : "www.example.co.uk" }
+       , "www..us": { "alias" : "www.example.com" }
+       , "smtp.us.": { "alias" : "smtp.example.com" }
+```
+
+is equivalent to
+
+```
+"map": { "uk": { "map": { "www": { "alias" : "www.example.co.uk" }}}
+       , "us": { "map": { "www": { "alias" : "www.example.com" }
+                        , "smtp": { "alias" : "smtp.example.com" }}
+               }
+       }
+```
+
 #### fingerprint attribute
 
 Does not translate into any DNS RR. Contains a list of TLS
@@ -244,13 +354,42 @@ certificate fingerprints. Deprecated.
 
 Intended to carry attributes as per
 [RFC-6698](http://tools.ietf.org/html/rfc6698) ("DANE").
-As of this writing, the specification is under discussion.
+
+```
+"tls": {
+  "tcp": {
+           { "443": [ [1, "660008F9...7621B787", 1] ]
+           , "25": [ [1, "660008F9...7621B787", 1] ]
+           }
+         }
+       }
+```
+
+translates into:
+
+```
+_443._tcp      TLSA  (3 0 1 660008F9...7621B787)
+_25._tcp       TLSA  (3 0 1 660008F9...7621B787)
+```
+
+The third element of the `TlsObj` heterogenous array is an extention
+to the DANE definition. Value `0` means that this rule is not enforced
+upon subdomains, value `1` means that it is enforced on subdomains.
+Rule defined inside a subdomain `DomObj` that specifies `0` on a rule
+existing in upper domain, that specifies `1` should be ignored. I.e.
+subdomain rule cannot revoke enforcement imposed by an upper domain rule.
 
 #### ds attribute
 
 Translates into `DS` RR. Carries attributes defined by
 [RFC-4034](http://tools.ietf.org/html/rfc4034).
 
+```
+"ds": [ [31381,8,1,"pA1W...ceTI="]
+      , [31381,8,2,"toHB...ndexitQ6j8E="]
+      ]
+```
+
 ### Lookup Sequence
 
 Assuming a query is performed for
@@ -290,7 +429,7 @@ recursive sequece:
    "normalized" by removal of attributes that are nullified by the
    presence of other attributes.
 
-Note that the process involves recursion nested to three levels.
+Note that the process involves recursion nested levels deep.
 
 ### Merging Procedure