SPEC.md

   1 % JSON Domain Format as Implemented by Pdns-Pipe-Nmc
   2
   3 ## Data Format
   4
   5 ### `DomObj` Object
   6
   7 `DomObj` either a `String` containing a dotted quad (see Note below),
   8 or a JSON `Map`, with the following attributes, all optional:
   9
  10 | Key         | Type                                  | Comment                                    |
  11 |-------------|---------------------------------------|--------------------------------------------|
  12 | service     | Array(SrvObj)                         | Located two levels above pos.              |
  13 | ip          | Array(String)                         | Dotted quad format "1.2.3.4"               |
  14 | ip6         | Array(String)                         | Semicolon format "DEAD::BEEF"              |
  15 | tor         | String                                | Onion name                                 |
  16 | i2p         | I2pObj                                |                                            |
  17 | freenet     | String                                |                                            |
  18 | alias       | String                                | Nullifies other attributes                 |
  19 | translate   | String                                | Nullifies other attributes                 |
  20 | email       | String                                | Used in `SOA`                              |
  21 | loc         | String                                | Format suitable for `LOC`                  |
  22 | info        | JsonObj                               | Currently unspecified                      |
  23 | ns          | Array(String)                         | Domain names as in `NS`                    |
  24 | delegate    | String                                | Replaces current object                    |
  25 | import      | String                                | "Deep" merges into current obj.            |
  26 | map         | Map(String:DomObj)                    | Tree of subdomain objects                  |
  27 | fingerprint | Array(String)                         |                                            |
  28 | tls         | Map(String:Map(String:Array(TlsObj))) | Outer `Map` by `Protocol`, inner by `Port` |
  29 | ds          | Array(DsObj)                          |                                            |
  30
  31 #### Notes:
  32
  33 * Any attribute specified as `Array(String)` may be present in the
  34   JSON document as a plain `String`, which is interpreted the same way
  35   as an `Array` containing a single `String` element.
  36 * If `DomObj` is a `String`, it is interpreted as an IPv4 address.
  37   In other words, string `"1.2.3.4"` is the same as the Map
  38   `"{\"ip\":\"1.2.3.4\"}"`. Such "shorthand" DomObj can be present at
  39   the top level or as a value in the `"map"` attribute.
  40
  41 ### `SrvObj` Object
  42
  43 `SrvObj` is a heterogenous Array of fixed size containing 6 elements:
  44
  45 | N | Type   | Meaning  |
  46 |---|--------|----------|
  47 | 0 | String | Service  |
  48 | 1 | String | Protocol |
  49 | 2 | Int    | Priority |
  50 | 3 | Int    | Weight   |
  51 | 4 | Int    | Port     |
  52 | 5 | String | Hostname |
  53
  54 #### Notes
  55
  56 * `Service` and `Protocol` are two elements of the domain name, without
  57   the undescore '_'.
  58 * `SrvObj` with Service `"smtp"`, Protocol `"tcp"` and Port `25` is also
  59   interpteted as an `MX` DNS resource.
  60 * When lookup is performed for `SRV` records at fqdn
  61   `"_serv._proto.sub.dom.bit"`, domain object for `"sub.dom.bit"` must be
  62   fetched, and in this object, `SrvObj`s for the Service `"serv"` and
  63   Protocol `"proto"` selected from its `"service"` attribute.
  64
  65 ### `TlsObj` Object
  66
  67 `TlsObj` is a heterogenous Array of fixed size containing 3 elements:
  68
  69 | N | Type   | Meaning                                               |
  70 |---|--------|-------------------------------------------------------|
  71 | 0 | Int    | Match type - 0:Exact, 1:SHA-256, 2:SHA-512            |
  72 | 1 | String | Match value - certificate or hash of it as hex string |
  73 | 2 | Int    | Include subdomains - 0:No, 1:Yes                      |
  74
  75 ### `DsObj` Object
  76
  77 `DsObj` is a heterogenous Array of fixed size containing 4 elements:
  78
  79 | N | Type   | Meaning                  |
  80 |---|--------|--------------------------|
  81 | 0 | Int    | Key Tag                  |
  82 | 1 | Int    | Key Algorithm            |
  83 | 2 | Int    | Hash Type                |
  84 | 3 | String | Hash Value as hex string |
  85
  86 ## Data Interpretation
  87
  88 Assuming a query is performed for
  89 `sdN`++"."++{...}++"."++`sd2`++"."++`sd1`++"."++`dom`++".bit"
  90 (`sdX` list possibly being empty), the lookup process starts by
  91 populating a "seed" DomObj with a single attribute `"import"`
  92 the value of which corresponds to the `dom` name in the
  93 Namecoin namespace, currently `"d/" ++ dom`.
  94 This domain object is then transformed by the following
  95 recursive sequece:
  96
  97 1. Value of the element of the `"map"` attribute with the key `""`
  98    (empty string) is recursively merged into the base domain. The
  99    `""` element of the `"map"` is removed from the result.
 100 2. If attribute `"import"` does not exist in the resulting object,
 101    recursion stops, and step 3 is performed on the result
 102    If attribute `"import"` exists in the resulting object, lookup is
 103    is performed for the value of this attribute, and fetched object
 104    is recursively merged into the base domain. The `"import"` attribute
 105    is removed from the result. Then the result is passed as base
 106    domain to step 1.
 107 3. If subdomain chain is empty, recursion stops, and step 4 is
 108    performed on the result. If subdomain chain is not empty, next
 109    element is taken out of the chain, and the `"map"` is looked
 110    up for the element with the name matching the subdomain element.
 111    The value of this element of the `"map"` is passed as base domain
 112    to step 1. If matching element does not exist, lookup is considered
 113    failed.
 114 4. Domain object with all `""` map elements and all `"import"` data
 115    merged is "normalized" by removal of attributes that are nullified
 116    by the presence of other attributes.
 117
 118 Note that the process involves recursion nested to three levels.
 119
 120 ## Merging
 121
 122 When a domain object `sub` needs merging into a domain object `base`,
 123 the following rules are applied:
 124
 125 * Of `String` and other "scalar" attributes, one is chosen, the value
 126   from the `base` taking precedence.
 127 * On `Array` attribtes, `union` operation is performed. (Of equal
 128   elements, only one copy is left.)
 129 * On `Map` attributes, recursive merge is performed. On the top level,
 130   elemens with keys that are only present in either `base` or `sub`
 131   object are all put into result. The values of the elements that are
 132   present in both `base` and `sub` are merged according to the rules
 133   applicable to their type.
 134