Revert "wip TLSA"

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

diff --git a/SPEC.md b/SPEC.md
index c00fdc396f800e06c1b4fee902036a91347b41d8..4a0fb4ac7fdf82a890821236345580353d9b828e 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                                    |
 |-------------|---------------------------------------|--------------------------------------------|


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

 
 

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


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


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


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