idnits 2.17.1 draft-hartke-t2trg-data-hub-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2019) is 1753 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-08 == Outdated reference: A later version (-28) exists of draft-ietf-core-resource-directory-22 == Outdated reference: A later version (-16) exists of draft-ietf-suit-architecture-05 == Outdated reference: A later version (-13) exists of draft-ietf-suit-information-model-02 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Experimental July 8, 2019 5 Expires: January 9, 2020 7 Thing-to-Thing Data Hub 8 draft-hartke-t2trg-data-hub-04 10 Abstract 12 The "Thing-to-Thing Data Hub" is a RESTful, hypermedia-driven Web 13 application that can be used in Thing-to-Thing communications to 14 share data items such as thing descriptions, configurations, resource 15 descriptions, or firmware updates at a central location. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 9, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 53 2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Interaction Model . . . . . . . . . . . . . . . . . . . . . . 5 55 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 56 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 57 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 58 6.1. Normative References . . . . . . . . . . . . . . . . . . 8 59 6.2. Informative References . . . . . . . . . . . . . . . . . 8 60 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 61 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 63 1. Introduction 65 In Thing-to-Thing communication, there is often a need to share data 66 items of common interest through a central location. For example, 67 the Resource Directory [I-D.ietf-core-resource-directory] aggregates 68 descriptions of Web resources held on constrained nodes, which 69 enables other nodes to easily discover these resources; a Thing 70 Directory [W3C.CR-wot-architecture-20190516] stores metadata of IoT 71 devices, allowing clients to discover interaction affordances and 72 supported protocol bindings of Things; and a Firmware Server 73 [I-D.ietf-suit-architecture] stores firmware images and manifests, 74 making this data available to deployed devices, commissioning tools, 75 and other services. 77 As more and more Thing-to-Thing applications are implemented, it 78 becomes increasingly important being able to not only share resource 79 descriptions and firmware updates but also many other kinds of data, 80 such as default configurations for new devices, service locations, or 81 certificate revocation lists. Resource directories and firmware 82 servers are not a good fit for these kinds of data, as they're 83 specialized to their use cases and generally not accepting any other 84 kinds of data. And creating new, specialized applications for every 85 type of data is not practical in the long term. 87 This document defines a simple "data hub" application, a RESTful Web 88 application with a machine-understandable hypermedia API. A "data 89 hub" generalizes the concept of a central repository for different 90 applications and is suitable for constrained environments [RFC7228]. 91 Specifically, it enables clients to share data items in any format 92 and provides means for creating, reading, observing, updating, 93 deleting, and finding data items at a data hub server. 95 Data hubs are intended to be used primarily with Constrained 96 Application Protocol (CoAP) [RFC7252]. 98 Features: 100 o General 102 The data hub generalizes the concept of a directory or repository 103 to data items of any Internet media type. This means that 104 applications using the data hub aren't stuck forever with the same 105 media types or limited to just resource descriptions or firmware 106 updates. 108 o Searchable 110 Clients can retrieve a subset of data items from a data hub based 111 on item metadata. 113 o Observable 115 Data items published to a data hub are exposed as resources. As 116 such, they can be observed for changes [RFC7641] over CoAP. This 117 allows clients to stay informed of information that other clients 118 update over time. As a result, the data hub functions similar to 119 a Publish-Subscribe Broker [I-D.ietf-core-coap-pubsub]. 121 o Evolvable 123 The key differentiator of the data hub compared to Resource 124 Directory [I-D.ietf-core-resource-directory] and CoAP Publish- 125 Subscribe Broker [I-D.ietf-core-coap-pubsub] lies in the 126 evolvability of the application -- the ability to respond 127 effectively to the need for changes without negatively impacting 128 existing and new clients. 130 Data hubs enable fine-grained evolvability by driving all 131 interactions by machine-understandable hypermedia elements. 132 Features can be added, changed or removed in a safe, backwards- 133 compatible way simply by updating the data hub representation to 134 expose appropriate links and forms. 136 1.1. Notational Conventions 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in 141 [RFC2119]. 143 Terms defined in this document appear in _cursive_ where they are 144 introduced. 146 2. Data Model 148 The data model of the "Thing-to-Thing Data Hub" application consists 149 of three elements: the _data hub_ itself, a _data collection_, and a 150 number of _data items_ that have been shared (Figure 1). 152 Data Hub 153 +----------------------------------------------------------+ 154 | | 155 | ___ | 156 | Data / \ | 157 | Collection \___/ | 158 | \ | 159 | \____________________ | 160 | \___ \___ \___ | 161 | / \ / \ ... / \ Data | 162 | \___/ \___/ \___/ Items | 163 | | 164 | | 165 +----------------------------------------------------------+ 167 Figure 1: A Data Collection with a Number of Shared Data Items Hosted 168 at a Data Hub 170 Data Hub 172 A data hub is a Web application running on a Web server that hosts 173 the data collection and the data items. 175 Data Collection 177 A data collection is a collection resource that contains the data 178 items. 180 Representations of data collections MUST have the "application/ 181 coral+cbor" media type [I-D.hartke-t2trg-coral]. The 182 representations consist primarily of links to the data items. 183 These links have the link relation type [RFC6573]. To reduce the number of 185 round-trips, the representations MAY also embed (complete or 186 partial) representations of the data items. Forms contained in 187 the representation enable interactions with the data collection 188 and the data items, as detailed in the following sections. The 189 representations MAY additionally contain other links and forms 190 that are not described in this document, such as a link with the 191 link relation 192 type [W3C.REC-html52-20171214] that references an alternate 193 representation of the data collection resource. 195 In this version of this document, a data hub is defined to have a 196 depth of only one level. That is, all data item resources are 197 organized directly under the top-level data collection resource. 198 This could be extended to multiple levels in a future version. 200 Data Item 202 A data item is a resource that is a member of the data collection 203 resource. 205 Data item representations can have any media type. However, a 206 data collection MAY restrict the media types it accepts for 207 publication. In this case, the form in the representation of the 208 data collection for creating data items MUST list the acceptable 209 media types using form fields of type . 212 The representations of data items MAY link back to the data 213 collection resource using the 214 link 215 relation type [RFC6573]. 217 3. Interaction Model 219 The interaction model consists of eight potential interactions with a 220 data hub: discovering and reading the data collection, and creating, 221 reading, observing, updating, deleting, and finding shared data items 222 in the data collection. 224 Discovering a Data Hub 226 In this version of this document, clients are assumed to be pre- 227 configured with an entry-point IRI for a data collection at a data 228 hub. 230 Reading a Collection 232 A client can retrieve a representation of a data collection by 233 dereferencing the entry-point IRI. As described above, the 234 representation of the data collection includes links to (and, 235 optionally, representations of) the data items in the data 236 collection. The representation of the data collection also 237 includes forms for creating, updating, deleting, and finding data 238 items. 240 Creating an Item 241 The representation of a data collection MAY contain a form with 242 the operation type. 243 Submitting this form with a representation in one of the 244 acceptable media types creates a new data item in the data 245 collection. The acceptable media types are indicated by form 246 fields of type . 248 Implementations of this version of this document MUST use the 249 method implied by the 250 operation type, i.e., the POST method [RFC7252]. A form 251 indicating different a method MUST be ignored. 253 On success, the location of the created data item MUST be conveyed 254 in a 2.01 (Created) response using the Location-Path and Location- 255 Query options [RFC7252]. 257 Reading an Item 259 A client can retrieve a representation of a data item by following 260 a link with the 261 link relation type in the representation of the data collection. 263 Observing an Item 265 A client can observe a data item by following a link with the 266 link relation type 267 in the representation of the data collection and observing the 268 target resource as specified in RFC 7641 [RFC7641]. 270 Updating an Item 272 For each data item in a data collection, the representation of the 273 data collection MAY include a form with the operation type nested within the link to the data 275 item. Submitting this form updates the data item to the submitted 276 representation. 278 Implementations of this version of this document MUST use the 279 method implied by the operation 280 type, i.e., the PUT method [RFC7252]. A form indicating different 281 a method MUST be ignored. 283 On success, a 2.04 (Changed) response is returned. 285 Deleting an Item 287 For each data item in a data collection, the representation of the 288 data collection MAY include a form with the operation type nested within the link to the 290 data item. Submitting this form deletes the data item from the 291 data collection. 293 Implementations of this version of this document MUST use the 294 method implied by the 295 operation type, i.e., the DELETE method [RFC7252]. A form 296 indicating different a method MUST be ignored. 298 On success, a 2.02 (Deleted) response is returned. 300 Searching for Items 302 The representation of a data collection MAY contain a form with 303 the operation type. This form 304 can be used to find data items in the data collection. Submitting 305 this form with a search query returns the subset of data items 306 that match the query. 308 (TODO: Specify the representation format for search queries.) 310 Implementations of this version of this document MUST use the 311 method implied by the operation 312 type, i.e., the FETCH method [RFC8132]. A form indicating 313 different a method MUST be ignored. 315 On success, a 2.05 (Content) response is returned. 317 (TODO: Specify the representation format for the response.) 319 4. Security Considerations 321 The data hub application relies on a Web transfer protocol like CoAP 322 to exchange representations in a CoRAL serialization format. See 323 Section 11 of RFC 7252 [RFC7252] and Section 7 of RFC 7641 [RFC7641] 324 for security considerations relating to CoAP. See Section 7 of RFC 325 XXXX [I-D.hartke-t2trg-coral] for security considerations relating to 326 CoRAL. 328 The data hub application does not define any specific mechanisms for 329 protecting the confidentiality and integrity of messages exchanged 330 between a data hub and a client. It is recommended that 331 implementations employ application layer or transport layer 332 mechanisms for interactions with a data hub. 334 The data hub application does not define any specific mechanisms for 335 protecting the confidentiality and integrity of representations of 336 data items shared through a data hub. For scenarios where end-to-end 337 security matters, such as for firmware updates 338 [I-D.ietf-suit-information-model], implementations should employ an 339 object security mechanism. 341 5. IANA Considerations 343 This document has no IANA actions. 345 6. References 347 6.1. Normative References 349 [I-D.hartke-t2trg-coral] 350 Hartke, K., "The Constrained RESTful Application Language 351 (CoRAL)", draft-hartke-t2trg-coral-09 (work in progress), 352 July 2019. 354 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 355 Requirement Levels", BCP 14, RFC 2119, 356 DOI 10.17487/RFC2119, March 1997, 357 . 359 [RFC6573] Amundsen, M., "The Item and Collection Link Relations", 360 RFC 6573, DOI 10.17487/RFC6573, April 2012, 361 . 363 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 364 Application Protocol (CoAP)", RFC 7252, 365 DOI 10.17487/RFC7252, June 2014, 366 . 368 [RFC7641] Hartke, K., "Observing Resources in the Constrained 369 Application Protocol (CoAP)", RFC 7641, 370 DOI 10.17487/RFC7641, September 2015, 371 . 373 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 374 FETCH Methods for the Constrained Application Protocol 375 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 376 . 378 6.2. Informative References 380 [I-D.ietf-core-coap-pubsub] 381 Koster, M., Keranen, A., and J. Jimenez, "Publish- 382 Subscribe Broker for the Constrained Application Protocol 383 (CoAP)", draft-ietf-core-coap-pubsub-08 (work in 384 progress), March 2019. 386 [I-D.ietf-core-resource-directory] 387 Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. 388 Amsuess, "CoRE Resource Directory", draft-ietf-core- 389 resource-directory-22 (work in progress), July 2019. 391 [I-D.ietf-suit-architecture] 392 Moran, B., Meriac, M., Tschofenig, H., and D. Brown, "A 393 Firmware Update Architecture for Internet of Things 394 Devices", draft-ietf-suit-architecture-05 (work in 395 progress), April 2019. 397 [I-D.ietf-suit-information-model] 398 Moran, B., Tschofenig, H., and H. Birkholz, "Firmware 399 Updates for Internet of Things Devices - An Information 400 Model for Manifests", draft-ietf-suit-information-model-02 401 (work in progress), January 2019. 403 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 404 Constrained-Node Networks", RFC 7228, 405 DOI 10.17487/RFC7228, May 2014, 406 . 408 [W3C.CR-wot-architecture-20190516] 409 Kovatsch, M., Matsukura, R., Lagally, M., Kawaguchi, T., 410 Toumura, K., and K. Kajimoto, "Web of Things (WoT) 411 Architecture", World Wide Web Consortium Candidate 412 Recommendation CR-wot-architecture-20190516, May 2019, 413 . 415 [W3C.REC-html52-20171214] 416 Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and 417 S. Moon, "HTML 5.2", World Wide Web Consortium 418 Recommendation REC-html52-20171214, December 2017, 419 . 421 Acknowledgements 423 Thanks to Christian Amsuess and Jaime Jimenez for helpful comments 424 and discussions that have shaped the document. 426 Author's Address 427 Klaus Hartke 428 Ericsson 429 Torshamnsgatan 23 430 Stockholm SE-16483 431 Sweden 433 Email: klaus.hartke@ericsson.com