wip move 'synthetic' parsing into NmcDom

[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
 
 % 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
 
 ## 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                                    |
 |-------------|---------------------------------------|--------------------------------------------|
 
 | 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                 |
 | 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                      |
 | 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     |
 | 2 | Int    | Priority |
 | 3 | Int    | Weight   |
 | 4 | Int    | Port     |

-| 5 | String | Hostname |
+| 5 | String | FQDN     |

 
 #### Notes
 
 
 #### 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
 
 ```
 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
 ```
 
 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.
 ```
 
 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
 #### 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.
 
 
 Does not translate into any DNS RR. Contains Tor hidden service address.
 

+```
+"tor": "eqt5g4fuenphqinx.onion"
+```
+

 #### i2p attribute
 
 #### 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"`.
 
 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 attribute
 
 Does not translate into any DNS RR. Contains Freesite key.
 

+```
+"freenet": "USK@0I8g...xbZ4,AQACAAE/Example/42/"
+```
+

 #### alias attribute
 
 #### 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"`
 
 #### 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
 
 
 #### 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.
 
 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 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
 #### 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
 
 
 #### 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
 
 #### 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
 
 #### 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.
 
 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
 #### 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.
 
 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
 #### 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").
 
 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 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
 ### 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.
 
    "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
 
 
 ### Merging Procedure