Gitiles
Code Review Sign In
gerrit.named-data.net / NDN-TLV / 08f39ceda8166540b22b592b2769a61a5a1f1964 / . / face-registration.rst
blob: 86ff6b9f6899a1ff74c97b25d0da9d23c4a018db [file] [log] [blame]
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]1.. _Face Registration:
2
3Face Management and Registration Protocol
4-----------------------------------------
5
6Face Management Protocol
7^^^^^^^^^^^^^^^^^^^^^^^^
8
9The Face Management Protocol provides a method for an entity such as ndndc to control
10the faces maintained by ndnd, which are subsequently used in the Registration Protocol.
11
12The FMP supports ``newface``, ``destroyface``, and ``queryface`` operations.
13
14A request operation is represented as a NDN Interest with
15a NDN Data in NDN-TLV encoding, while the majority of the request parameters embedded
16as a component of the Interest name.
17A response is represented as a Data for which the name matches the Interest,
18and the content encodes any necessary response data.
19
20For the Face Management Protocol, the content of the Data packet is FaceInstance object
21as defined below.
22
23For example, the following steps necessary to create a new face:
24
25- Create NDN-TLV encoded FaceInstance object, containing action ``newface`` and other
26 necessary fields to set up the face (e.g., ``IPProto``, ``Host``, ``Port``).
27
28- Create NDN-TLV encoded Data packet (``<NFBLOB>``), whose content is the encoded
29 FaceInstance object
30
31- Express an Interest ``/ndnx/<NDNDID>/newface/<NFBLOB>``, where
32
33 * ``<NDNDID>`` is the SHA256 of the public key of the forwarding daemon.
34
35 * ``<NFBLOB>`` is encoded Data packet with encoded FaceInstance object as content.
36
37The verb, ``newface`` occurs redundantly in both the Interest prefix and in the ``NFBLOB``.
38Its presence in the prefix is for dispatching the request.
39It is also in the ``NFBLOB``, so that it is signed.
40
41The forwarding daemon creates the new face and answers with a FaceInstance containing
42at least the ``FaceID``.
43
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]44.. note::
45 When face registration succeeds, the returning Data packet's content is encoded ``FaceInstance`` with
46 parameters of the created/destroyed/queried face.
47
48 When registration fails, the Interest either times out or there will be a returned Data packet
49 with encoded :ref:`StatusResponse`.
50
51
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]52FaceInstance
53^^^^^^^^^^^^
54
55::
56
57 FaceInstance ::= FACE-INSTANCE-TYPE TLV-LENGTH
58 Action?
59 FaceID?
60 IPProto?
61 Host?
62 Port?
63 MulticastInterface?
64 MulticastTTL?
65 FreshnessPeriod?
66
67 Action ::= ACTION-TYPE TLV-LENGTH
68 ("newface" | "destroyface" | "queryface")
69
70 FaceID ::= FACEID-TYPE TLV-LENGTH
71 nonNegativeInteger
72
73 IPProto ::= FACEID-TYPE TLV-LENGTH
74 nonNegativeInteger
75 (*IANA protocol number; 6=TCP, 17=UDP*)
76
77 Host ::= HOST-TYPE TLV-LENGTH
78 <textual representation of numeric IPv4 or IPv6 address>
79
80 Port ::= PORT-TYPE TLV-LENGTH
81 nonNegativeInteger
82 (* from the range [1..65535] *)
83
84 MulticastInterface ::= MULTICAST-INTERFACE-TYPE TLV-LENGTH
85 <textual representation of numeric IPv4 or IPv6 address>
86
87 MulticastTTL ::= MULTICAST-TTL-TYPE TLV-LENGTH
88 nonNegativeInteger
89 (* from the range [1..255] *)
90
91See :ref:`Data packet's meta info description <MetaInfo>` for definition of ``FreshnessPeriod``.
92
93Action
94++++++
95
96When FaceInstance is used as a request, the Action must be specified.
97It will not be present in a response.
98
99+-----------------+----------------------------------------------------------------------+
100| Action | Description |
101+=================+======================================================================+
102| ``newface`` | If a face matching the parameters does not already exist, an attempt |
103| | is made to create it. |
104| | |
105| | Then if the face exists (whether new or old) the full description is |
106| | returned as a FaceInstance. |
107+-----------------+----------------------------------------------------------------------+
108| ``destroyface`` | At least the FaceID must be present. |
109| | If permitted, the face is destroyed. |
110+-----------------+----------------------------------------------------------------------+
111| ``queryface`` | TBD |
112+-----------------+----------------------------------------------------------------------+
113
114FaceID
115++++++
116
117FaceID is not present in a `newface` request, but must be specified in
118a `destroyface` or `queryface` request.
119FaceID is always present in a response.
120
121Host
122++++
123
124Identifies the IPv4 or IPv6 numeric address of the remote ndnd for this
125FaceInstance.
126
127Port
128++++
129
130Port identifies the port on the remote ndnd, or the port for the multicast group.
131
132MulticastInterface
133++++++++++++++++++
134
135If the Host is a multicast address, and there are multiple
136interfaces present, MulticastInterface will identify the unicast
137numeric address of the interface to which the multicast address will be
138attached.
139
140MulticastTTL
141++++++++++++
142
143Specifies the TTL to be used for multicast operations. The default value is 1.
144
145FreshnessPeriod
146++++++++++++++++
147
148FreshnessPeriod is optional in a request, but is treated as a hint by the forwarding daemon.
149In a response, FreshnessPeriod specifies the remaining lifetime in milliseconds of the
150face.
151
152Prefix Registration Protocol
153^^^^^^^^^^^^^^^^^^^^^^^^^^^^
154
155The prefix registration protocol uses the ForwardingEntry element type
156to represent both requests and responses.
157
158::
159
160 ForwardingEntry ::= FORWARDING-ENTRY TLV-LENGTH
161 Action?
162 Name?
163 FaceID?
164 ForwardingFlags?
165 FreshnessPeriod?
166
167 Action ::= ACTION-TYPE TLV-LENGTH
168 ("prefixreg" | "selfreg" | "unreg")
169
170 FaceID ::= FACEID-TYPE TLV-LENGTH
171 nonNegativeInteger
172
173 ForwardingFlags ::= FORWARDING-FLAGS TLV-LENGTH
174 nonNegativeInteger
175
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]176See :ref:`Name section <Name>` for definition of ``Name`` and
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]177:ref:`Data packet's meta info description <MetaInfo>` for definition of ``FreshnessPeriod``.
178
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]179.. note::
180 When prefix registration succeeds, the returning Data packet's content is encoded ``ForwardingEntry`` with
181 parameters of the prefix.
182
183 When registration fails, the Interest either times out or there will be a returned Data packet
184 with encoded :ref:`StatusResponse`.
185
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]186
187Action
188++++++
189
190When ForwardingEntry is used as a request, the Action must be specified.
191It will not be present in a response.
192
193- `prefixreg` - Register (or re-register) the prefix on the specified face.
194- `selfreg` - Register (or re-register) the prefix on the current face; the
195 FaceID need not be present in the request, but if present it must match
196 the current face.
197- `unreg` - Remove the prefix registration for the specified face.
198
199FaceID
200++++++
201
202FaceID is required in `prefixreg` and `unreg` requests.
203FaceID is always present in a response.
204
205Name
206++++
207
208This is the name prefix to be acted on.
209
210ForwardingFlags
211+++++++++++++++
212
213This integer holds the inclusive OR of the following bit fields:
214
215+----------------------------+---------------+-----------------------------------------------------------------------------+
216| Flag mnemonic | Bit (decimal) | Description |
217+============================+===============+=============================================================================+
218| ``NDN_FORW_ACTIVE`` | 1 | Indicates that the entry is active; |
219| | | interests will not be sent for inactive entries (but see note below). |
220+----------------------------+---------------+-----------------------------------------------------------------------------+
221| ``NDN_FORW_CHILD_INHERIT`` | 2 | Denotes that this entry may be used even if there is a longer match |
222| | | available. In the absence of this bit, the presence of a longer matching |
223| | | prefix that has an active entry will prevent this entry from being used. |
224+----------------------------+---------------+-----------------------------------------------------------------------------+
225| ``NDN_FORW_ADVERTISE`` | 4 | Indicates that the prefix may be advertised to other nodes. |
226+----------------------------+---------------+-----------------------------------------------------------------------------+
227| ``NDN_FORW_LAST`` | 8 | Indicates that this entry should be used last, if nothing else worked. |
228| | | This is intended to be used by ndndc and similar programs to monitor |
229| | | unanswered interests. |
230| | | |
231| | | The presence of this flag on any entry causes the associated face to be |
232| | | considered non-local, as far as interest forwarding is concerned. |
233| | | Thus it will not receive interests with Scope=1, nor will it receive |
234| | | interests in namespaces that are marked local. However, the ability of |
235| | | the face to change prefix registrations is not affected. |
236+----------------------------+---------------+-----------------------------------------------------------------------------+
237| ``NDN_FORW_CAPTURE`` | 16 | Says that no shorter prefix may be used, overriding child-inherit bits that |
238| | | would otherwise make the shorter entries usable. |
239| | | |
240| | | For a child-inherit bit to be overridden, the ``NDN_FORW_CAPTURE_OK`` must |
241| | | be set in the same forwarding entry that has ``NDN_FORW_CHILD_INHERIT`` |
242| | | set. Note that this means that using ``NDN_FORW_CAPTURE`` will have no |
243| | | effect if the ``NDN_FORW_CAPTURE_OK`` flag is not used. |
244+----------------------------+---------------+-----------------------------------------------------------------------------+
245| ``NDN_FORW_LOCAL`` | 32 | Restricts the namespace to use by applications on the local machine. |
246| | | |
247+----------------------------+---------------+-----------------------------------------------------------------------------+
248| ``NDN_FORW_TAP`` | 64 | Causes the entry to be used right away. This is intended for debugging |
249| | | and monitoring purposes. It is likely that there will be no response as |
250| | | a result, so no intentional delay is added before any further forwarding |
251| | | of this interest. |
252+----------------------------+---------------+-----------------------------------------------------------------------------+
253| ``NDN_FORW_CAPTURE_OK`` | 128 | used in conjunction with ``NDN_FORW_CHILD_INHERIT`` allows a |
254| | | ``NDN_FORW_CAPTURE`` flag on a longer prefix to override the effect of |
255| | | the child-inherit bit. |
256+----------------------------+---------------+-----------------------------------------------------------------------------+
257
258The flags ``NDN_FORW_ADVERTISE``, ``NDN_FORW_CAPTURE`` and ``NDN_FORW_LOCAL`` affect
259the prefix as a whole, rather than the individual registrations.
260Their effects take place whether or not the ``NDN_FORW_ACTIVE`` bit is set.
261
262FreshnessPeriod
263+++++++++++++++
264
265FreshnessPeriod is optional in a request, but is treated as a hint by the forwarding daemon.
266In a response, FreshnessPeriod specifies the remaining lifetime in milliseconds of the registration.
267
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]268.. _StatusResponse:
269
270StatusResponse
271^^^^^^^^^^^^^^
272
273The StatusResponse is used to indicate an exceptional condition or
274additional information in response to a request.
275Protocol descriptions should indicate the circumstances under which a
276StatusResponse may be returned instead of a normal response.
277
278::
279
280 StatusResponse ::= STATUS-RESPONSE-TYPE TLV-LENGTH
281 StatusCode
282 StatusText?
283
284 StatusCode ::= STATUS-CODE-TYPE TLV-LENGTH
285 nonNegativeInteger
286
287 StatusText ::= STATUS-TEXT TLV-LENGTH
288 <status text>
289
290StatusCode
291++++++++++
292
293This is a three-digit decimal number, in the style of numeric codes
294used in various internet protocols such as HTTP, FTP, and SMTP.
295
296StatusText
297++++++++++
298
299A short textual description of the status.
300Programs should rely on the StatusCode, not the StatusText, for making decisions about haw to proceed.
301
302Status Code Values
303++++++++++++++++++
304
305This table is informational, summarizing status codes that are currently is use.
306
307+--------+--------------------------------------------------------+
308| Code | Description |
309+========+========================================================+
310| 404 | Not found |
311+--------+--------------------------------------------------------+
312| 430 | Not authorized |
313+--------+--------------------------------------------------------+
314| 450 | Temporarily unable to complete operation |
315+--------+--------------------------------------------------------+
316| 453 | Could not setup multicast |
317+--------+--------------------------------------------------------+
318| 501 | Syntax error in address |
319+--------+--------------------------------------------------------+
320| 504 | Parameter error |
321+--------+--------------------------------------------------------+
322| 531 | Missing or incorrect ccndid |
323+--------+--------------------------------------------------------+
324
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]325
326Type code assignment
327^^^^^^^^^^^^^^^^^^^^
328
329Face management and registration protocol uses the following type codes, which are assigned
330from the :ref:`application range (128-252) <type reservations>`.
331
332Some codes (e.g., `Name`, `FreshnessPeriod`), re-use code assignment from the NDN-TLV specification.
333
334+---------------------------------------------+-------------------+----------------+
335| Type | Assigned value | Assigned value |
336| | (decimal) | (hexadecimal) |
337+=============================================+===================+================+
338| **Application-specific definitions** |
339+---------------------------------------------+-------------------+----------------+
340| FaceInstance | 128 | 0x80 |
341+---------------------------------------------+-------------------+----------------+
342| ForwardingEntry | 129 | 0x81 |
343+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]344| StatusResponse | 130 | 0x82 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]345+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]346| Action | 131 | 0x83 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]347+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]348| FaceID | 132 | 0x84 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]349+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]350| IPProto | 133 | 0x85 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]351+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]352| Host | 134 | 0x86 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]353+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]354| Port | 135 | 0x87 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]355+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]356| MulticastInterface | 136 | 0x88 |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]357+---------------------------------------------+-------------------+----------------+
Alexander Afanasyevb6936f92013-12-29 00:13:12 +0000[diff] [blame]358| MulticastTTL | 137 | 0x89 |
359+---------------------------------------------+-------------------+----------------+
360| ForwardingFlags | 138 | 0x8a |
361+---------------------------------------------+-------------------+----------------+
362| StatusCode | 139 | 0x8b |
363+---------------------------------------------+-------------------+----------------+
364| StatusText | 140 | 0x8c |
Alexander Afanasyevca58dc22013-12-28 21:04:59 +0000[diff] [blame]365+---------------------------------------------+-------------------+----------------+
366| **Re-used definitions** |
367+---------------------------------------------+-------------------+----------------+
368| FreshnessPeriod | 20 | 0x14 |
369+---------------------------------------------+-------------------+----------------+
370| Name | 2 | 0x02 |
371+---------------------------------------------+-------------------+----------------+