X-Git-Url: http://www.average.org/gitweb/?p=pdns-pipe-nmc.git;a=blobdiff_plain;f=SPEC.md;h=4a0fb4ac7fdf82a890821236345580353d9b828e;hp=f464e11c69c4a67a85dd17c959f0aad56c483235;hb=f5e9870ed6d3307c08e583a7874d8c35e0ea6978;hpb=9cdf03ec80c88e51fbcf0625b4f642fb8c6c4e1a diff --git a/SPEC.md b/SPEC.md index f464e11..4a0fb4a 100644 --- a/SPEC.md +++ b/SPEC.md @@ -17,8 +17,9 @@ This specification is implemented by the `pdns-pipe-nmc` program. ### `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 | |-------------|---------------------------------------|--------------------------------------------| @@ -29,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 | @@ -182,30 +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. -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"` -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 @@ -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. +``` +"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. -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 -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 @@ -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. +``` +"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 @@ -271,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 @@ -317,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