X-Git-Url: http://www.average.org/gitweb/?p=pdns-pipe-nmc.git;a=blobdiff_plain;f=SPEC.md;h=76ba56bf8479764eaf8968bd0ea7080469591412;hp=22b236eb75301fa7b85d29fcc284d8bf62714aff;hb=61a1067b335cf064a99ec1c4d36042fe8a685738;hpb=355038bc44ff6a9dbbc5a09739fba3fe4b073b32 diff --git a/SPEC.md b/SPEC.md index 22b236e..76ba56b 100644 --- a/SPEC.md +++ b/SPEC.md @@ -2,44 +2,41 @@ ## Data Format -`DomObj` is a JSON object, specifically a `Map` (not an `Array`), or a -`String` containing a dotted quad (see Note below). - ### `DomObj` Object -`DomObj` is a JSON `Map`, with the following attributes, all optional: - -| Key | Type | Comment | -|-------------|---------------------------------------|---------------------------------| -| service | Array(SrvObj) | Located two levels above pos. | -| ip | Array(String) | Dotted quad "1.2.3.4" | -| ip6 | Array(String) | Semicolon format "DEAD::BEEF" | -| tor | String | Onion name | -| i2p | I2pObj | | -| freenet | String | | -| alias | String | Nullifies other attributes | -| translate | String | Nullifies other attributes | -| email | String | Used in `SOA` | -| loc | String | Format suitable for `LOC` | -| info | JsonObj | Currently unspecified | -| ns | Array(String) | Domain names as in `NS` | -| delegate | String | Replaces current object | -| import | String | "Deep" merges into current obj. | -| map | Map(String:DomObj) | Tree of subdomain objects | -| fingerprint | Array(String) | | -| tls | Map(String:Map(String:Array(TlsObj))) | | -| ds | Array(DsObj) | | +`DomObj` either a `String` containing a dotted quad (see Note below), +or a JSON `Map`, with the following attributes, all optional: + +| Key | Type | Comment | +|-------------|---------------------------------------|--------------------------------------------| +| service | Array(SrvObj) | Located two levels above position | +| ip | Array(String) | Dotted quad format "1.2.3.4" | +| ip6 | Array(String) | Semicolon format "DEAD::BEEF" | +| tor | String | Onion name | +| i2p | I2pObj | | +| freenet | String | | +| alias | String | Nullifies other attributes | +| translate | String | Nullifies other attributes | +| email | String | Used in `SOA` | +| loc | String | Format suitable for `LOC` | +| info | JsonObj | Currently unspecified | +| ns | Array(String) | Domain names as in `NS` | +| delegate | String | Replaces current object | +| import | Array(String) | "Deep" merges into current object | +| map | Map(String:DomObj) | Tree of subdomain objects | +| fingerprint | Array(String) | | +| tls | Map(String:Map(String:Array(TlsObj))) | Outer `Map` by `Protocol`, inner by `Port` | +| ds | Array(DsObj) | | #### Notes: * Any attribute specified as `Array(String)` may be present in the - JSON document as `String`, which is interpreted the same way as - an `Array` containing a single `String` element. -* In any place where `DomObj` is expected there may be a `String`, which - is interpreted as an IPv4 address. In other words, a string `"1.2.3.4"` - is interpreted the same way as the object `"{\"ip\":\"1.2.3.4\"}"` - Such "shorthand" DomObj can be present at the top level or as a value - in the `"map"` attribute. + JSON document as a plain `String`, which is interpreted the same way + as an `Array` containing a single `String` element. +* If `DomObj` is a `String`, it is interpreted as an IPv4 address. + In other words, string `"1.2.3.4"` is the same as the Map + `"{\"ip\":\"1.2.3.4\"}"`. Such "shorthand" DomObj can be present at + the top level or as a value in the `"map"` attribute. ### `SrvObj` Object @@ -59,11 +56,11 @@ * `Service` and `Protocol` are two elements of the domain name, without the undescore '_'. * `SrvObj` with Service `"smtp"`, Protocol `"tcp"` and Port `25` is also - interpteted as an `MX` DNS respource. + interpteted as an `MX` DNS resource. * When lookup is performed for `SRV` records at fqdn `"_serv._proto.sub.dom.bit"`, domain object for `"sub.dom.bit"` must be fetched, and in this object, `SrvObj`s for the Service `"serv"` and - Protocol `"proto"` selected from it. + Protocol `"proto"` selected from its `"service"` attribute. ### `TlsObj` Object @@ -88,10 +85,110 @@ ## Data Interpretation -Assuming a query for a subdomain of a basedomain in the `.bit` TLD -(subdomain possibly being empty), lookup starts by fetching the -"base" object for basedomain. The domain object is then transformed -by the following sequece applied recursively: +### Semantics of the Attributes + +#### service attribute + +Translates to DNS `SRV` RR, only it is located in the subdomain tree +two levels higher than the `SRV` record would. For example, a +`"service"` attribute in the `"map"` hieararchy at the point +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."] ] +``` + +corresponds to two `SRV` RRs at two different points in the +subdomain tree: + +``` +_imap._tcp.sub.dom.bit. IN SRV 0 0 143 mail.host.com. +_smtp._tcp.sub.dom.bit. IN SRV 0 0 25 relay.host.com. +``` + +In addition to these, an `MX` RR is syntesized at the "sub.dom.bit" +level: + +``` +sub.dom.bit. IN MX 0 relay.host.com. +``` + +#### ip attribute + +Contains a list of strings representing IPv4 addresses in dotted +quad notation. For example, + +``` +"ip": ["1.2.3.4", "5.6.7.8"] +``` + +translates into a series of `A` RRs: + +``` + IN A 1.2.3.4 + IN A 5.6.7.8 +``` + +#### ip6 attribute + + +#### tor attribute + + +#### i2p attribute + + +#### freenet attribute + + +#### alias attribute + + +#### translate attribute + + +#### email attribute + + +#### loc attribute + + +#### info attribute + + +#### ns attribute + + +#### delegate attribute + + +#### import attribute + + +#### map attribute + + +#### fingerprint attribute + + +#### tls attribute + + +#### ds attribute + + +### Lookup Sequence + +Assuming a query is performed for +`sdN`++"."++{...}++"."++`sd2`++"."++`sd1`++"."++`dom`++".bit" +(`sdX` list possibly being empty), the lookup process starts by +querying the database for the object corresponding to `dom`. +Technically, it is easiest to populate a "seed" DomObj with a +single attribute `"import"` the value of which corresponds to the +`dom` name in the Namecoin namespace, which is `"d/" ++ dom`. +This domain object is then transformed by the following +recursive sequece: 1. Value of the element of the `"map"` attribute with the key `""` (empty string) is recursively merged into the base domain. The @@ -99,8 +196,8 @@ by the following sequece applied recursively: 2. If attribute `"import"` does not exist in the resulting object, recursion stops, and step 3 is performed on the result If attribute `"import"` exists in the resulting object, lookup is - is performed for the value of this attribute, and fetched object - is recursively merged into the base domain. The `"import"` attribute + is performed for the values of this attribute, and fetched objects + are recursively merged into the base domain. The `"import"` attribute is removed from the result. Then the result is passed as base domain to step 1. 3. If subdomain chain is empty, recursion stops, and step 4 is @@ -116,7 +213,7 @@ by the following sequece applied recursively: Note that the process involves recursion nested to three levels. -## Merging +### Merging Procedure When a domain object `sub` needs merging into a domain object `base`, the following rules are applied: