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 position          |
  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      | Array(String)                         | "Deep" merges into current object          |
  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 ### Semantics of the Attributes
  89
  90 #### service attribute
  91
  92 Translates to DNS `SRV` RR, only it is located in the subdomain tree
  93 two levels higher than the `SRV` record would. For example, a
  94 `"service"` attribute in the `"map"` hieararchy at the point
  95 corresponding to the FQDN "sub.dom.bit" with the value
  96
  97 ```
  98 "service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com." ],
  99              ["smtp", "tcp", 0, 0,  25, "relay.host.com."] ]
 100 ```
 101
 102 corresponds to two `SRV` RRs at two different points in the
 103 subdomain tree:
 104
 105 ```
 106 _imap._tcp.sub.dom.bit. IN SRV 0 0 143 mail.host.com.
 107 _smtp._tcp.sub.dom.bit. IN SRV 0 0  25 relay.host.com.
 108 ```
 109
 110 In addition to these, an `MX` RR is syntesized at the "sub.dom.bit"
 111 level:
 112
 113 ```
 114 sub.dom.bit. IN MX 0 relay.host.com.
 115 ```
 116
 117 #### ip attribute
 118
 119 Contains a list of strings representing IPv4 addresses in dotted
 120 quad notation. For example,
 121
 122 ```
 123 "ip": ["1.2.3.4", "5.6.7.8"]
 124 ```
 125
 126 translates into a series of `A` RRs:
 127
 128 ```
 129         IN A 1.2.3.4
 130         IN A 5.6.7.8
 131 ```
 132
 133 #### ip6 attribute
 134
 135
 136 #### tor attribute
 137
 138
 139 #### i2p attribute
 140
 141
 142 #### freenet attribute
 143
 144
 145 #### alias attribute
 146
 147
 148 #### translate attribute
 149
 150
 151 #### email attribute
 152
 153
 154 #### loc attribute
 155
 156
 157 #### info attribute
 158
 159
 160 #### ns attribute
 161
 162
 163 #### delegate attribute
 164
 165
 166 #### import attribute
 167
 168
 169 #### map attribute
 170
 171
 172 #### fingerprint attribute
 173
 174
 175 #### tls attribute
 176
 177
 178 #### ds attribute
 179
 180
 181 ### Lookup Sequence
 182
 183 Assuming a query is performed for
 184 `sdN`++"."++{...}++"."++`sd2`++"."++`sd1`++"."++`dom`++".bit"
 185 (`sdX` list possibly being empty), the lookup process starts by
 186 querying the database for the object corresponding to `dom`.
 187 Technically, it is easiest to populate a "seed" DomObj with a
 188 single attribute `"import"` the value of which corresponds to the
 189 `dom` name in the Namecoin namespace, which is `"d/" ++ dom`.
 190 This domain object is then transformed by the following
 191 recursive sequece:
 192
 193 1. Value of the element of the `"map"` attribute with the key `""`
 194    (empty string) is recursively merged into the base domain. The
 195    `""` element of the `"map"` is removed from the result.
 196 2. If attribute `"import"` does not exist in the resulting object,
 197    recursion stops, and step 3 is performed on the result
 198    If attribute `"import"` exists in the resulting object, lookup is
 199    is performed for the values of this attribute, and fetched objects
 200    are recursively merged into the base domain. The `"import"` attribute
 201    is removed from the result. Then the result is passed as base
 202    domain to step 1.
 203 3. If subdomain chain is empty, recursion stops, and step 4 is
 204    performed on the result. If subdomain chain is not empty, next
 205    element is taken out of the chain, and the `"map"` is looked
 206    up for the element with the name matching the subdomain element.
 207    The value of this element of the `"map"` is passed as base domain
 208    to step 1. If matching element does not exist, lookup is considered
 209    failed.
 210 4. Domain object with all `""` map elements and all `"import"` data
 211    merged is "normalized" by removal of attributes that are nullified
 212    by the presence of other attributes.
 213
 214 Note that the process involves recursion nested to three levels.
 215
 216 ### Merging Procedure
 217
 218 When a domain object `sub` needs merging into a domain object `base`,
 219 the following rules are applied:
 220
 221 * Of `String` and other "scalar" attributes, one is chosen, the value
 222   from the `base` taking precedence.
 223 * On `Array` attribtes, `union` operation is performed. (Of equal
 224   elements, only one copy is left.)
 225 * On `Map` attributes, recursive merge is performed. On the top level,
 226   elemens with keys that are only present in either `base` or `sub`
 227   object are all put into result. The values of the elements that are
 228   present in both `base` and `sub` are merged according to the rules
 229   applicable to their type.
 230