reminder to describe subdomain keys with dots

[pdns-pipe-nmc.git] / SPEC.md

diff --git a/SPEC.md b/SPEC.md
index f464e11c69c4a67a85dd17c959f0aad56c483235..1c1292ce803bf65d6558f3bd641045cdbd72768c 100644 (file)
--- a/SPEC.md
+++ b/SPEC.md
@@ -17,8 +17,9 @@ This specification is implemented by the `pdns-pipe-nmc` program.
 
 ### `DomObj` Object
 
 
 ### `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                                    |
 |-------------|---------------------------------------|--------------------------------------------|


@@ -29,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                      |


@@ -182,30 +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.

 
 

-Note: Hostname element **must** be specified as fully qualified domain
-name of the host, and **must not** terminate with a dot. 
+```
+"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
 


@@ -213,44 +242,74 @@ 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"]
+```

 
 

-Note: the value of the attribute  **must** be specified as fully
-qualified domain name of the host, and **must not** terminate
-with a dot.
+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
 
 #### map attribute
 

+FIXME - explain handling of the keys with dots.
+Also, add checks to the code to disallow empty elements.
+

 JSON Map object containing subdomain names as its keys and domain
 objects as values. Element of the map with empty key "" has special
 meaning: the value of this map element is merged into the current
 JSON Map object containing subdomain names as its keys and domain
 objects as values. Element of the map with empty key "" has special
 meaning: the value of this map element is merged into the current


@@ -262,6 +321,12 @@ 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" }
+       }
+```
+

 #### 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


@@ -271,13 +336,28 @@ 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] ]
+           }
+         }
+       }
+```

 
 #### 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


@@ -317,7 +397,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