idnits 2.17.1 draft-mcd-identifier-access-http-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (December 25, 2019) is 1556 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-security-00 == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-query-00 == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-responce-00 == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-authority-00 Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Engineering Task Force C. Ma 2 Internet Draft J. Chen 3 Intended status: Experimental X. Fan 4 Expires: June 25, 2020 M. Chen 5 Z. Li 6 China Academy of Information and Communications Technology 7 December 25, 2019 9 HTTP Usage in the Industrial Internet Identifier Data Access 10 Protocol (IIIDAP) 11 draft-mcd-identifier-access-http-00 13 Status of this Memo 15 This Internet-Draft is submitted in full conformance with the 16 provisions of BCP 78 and BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other documents 25 at any time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html 34 This Internet-Draft will expire on February 5, 2020. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with 46 respect to this document. Code Components extracted from this 47 document must include Simplified BSD License text as described in 48 Section 4.e of the Trust Legal Provisions and are provided without 49 warranty as described in the Simplified BSD License. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with 56 respect to this document. 58 Abstract 60 This document describes an Extensible Provisioning Protocol (EPP) 61 for the provisioning and management of enterprises and identifiers 62 between the server which is called Business Management System (BMS) 63 and is entitled to manage the identifier top-level node and the 64 client which is also referred to as Second Node Management System 65 (SNMS). Specified in XML, the mapping defines EPP command syntax and 66 semantics as applied to enterprise and identifier management. 68 Table of Contents 70 1. Introduction ................................................ 3 71 2. Conventions used in this document............................ 4 72 2.1. Acronyms and Abbreviations.............................. 4 73 3. Design Intents .............................................. 5 74 4. Queries ..................................................... 5 75 4.1. HTTP Methods ........................................... 5 76 4.2. Accept Header .......................................... 6 77 4.3. Query Parameters........................................ 6 78 5. Types of HTTP Response....................................... 6 79 5.1. Positive Answers........................................ 6 80 5.2. Redirects .............................................. 6 81 5.3. Negative Answers........................................ 7 82 5.4. Malformed Queries....................................... 7 83 5.5. Rate Limits ............................................ 8 84 5.6. Cross-Origin Resource Sharing (CORS).................... 8 85 6. Security Considerations...................................... 8 86 7. Internationalization Considerations.......................... 9 87 7.1. URIs and IRIs .......................................... 9 88 7.2. Language Identifiers in Queries and Responses........... 9 89 7.3. Language Identifiers in HTTP Headers.................... 9 91 8. References .................................................. 9 92 8.1. Normative References.................................... 9 93 8.2. Informative References................................. 10 94 Appendix A. Protocol Example................................... 12 95 Appendix B. Cache Busting...................................... 13 96 Appendix C. Bootstrapping and Redirection...................... 14 98 1. Introduction 100 This document describes the usage of the Hypertext Transfer Protocol 101 (HTTP) [RFC7230] for the Industrial Internet Identifier Data Access 102 Protocol (IIIDAP). The goal of this document is to tie together 103 usage patterns of HTTP into a common profile applicable to the 104 various types of directory services serving identifier data using 105 practices informed by the Representational State Transfer (REST) 106 [REST] architectural style. By giving the various directory services 107 common behavior, a single client is better able to retrieve data 108 from directory services adhering to this behavior. 110 Identifier data expected to be presented by this service is 111 Industrial Internet Identifier data -- some of the information that 112 identifiers of Second-Level Nodes (SLN) and Enterprise-Level Nodes 113 (ELN) contain (see [ RFC]). This protocol is expected to provide a 114 specification for queries and responses, redirection to 115 authoritative sources, and support for localized identifier data 116 such as addresses and organization or person names. This function is 117 expected to be provided by SLN. 119 In designing these common usage patterns, this document introduces 120 considerations for a simple use of HTTP. Where complexity may 121 reside, it is the goal of this document to place it upon the server 122 and to keep the client as simple as possible. A client 123 implementation should be possible using common operating system 124 scripting tools (e.g., bash and wget). 126 This is the basic usage pattern for this protocol: 128 1. A client determines an appropriate server to query along with the 129 appropriate base Uniform Resource Locator (URL) to use in such 130 queries. [IDENTIFIER-AUTHORIZATION] describes one method to 131 determine the server and the base URL. See Appendix C for more 132 information. 134 2. A client issues an HTTP (or HTTPS) query using GET [RFC7231]. As 135 an example, a query URL for the enterprise identifier 86.100.1 136 might be 137 http://example.com/iiidap/identifier/86.100.1 139 [IDENTIFIER-QUERY] details the various queries used in IIIDAP. 141 3. If the receiving server has the information for the query, it 142 examines the Accept header field of the query and returns a 200 143 response with a response entity appropriate for the requested 144 format. [IDENTIFIER-RESPONSES] details a response in JavaScript 145 Object Notation (JSON). 147 4. If the receiving server does not have the information for the 148 query but does have knowledge of where the information can be 149 found, it will return a redirection response (3xx) with the 150 Location header field containing an HTTP(S) URL pointing to the 151 information or another server known to have knowledge of the 152 location of the information. The client is expected to require 153 using that HTTP URL. 155 5. If the receiving server does not have the information being 156 requested and does not have knowledge of where the information 157 can be found, it returns a 404 response. 159 6. If the receiving server will not answer a request for policy 160 reasons, it will return an error response (4xx) indicating the 161 reason for giving no answer. 163 It is not the intent of this document to redefine the meaning and 164 semantics of HTTP. The purpose of this document is to clarify the 165 use of standard HTTP mechanisms for this application. 167 2. Conventions used in this document 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 171 document are to be interpreted as described in RFC 2119 [RFC2119]. 173 In this document, an IIIDAP client is an HTTP user agent performing 174 an IIIDAP query, and an IIIDAP server is an HTTP server providing an 175 IIIDAP response. IIIDAP query and response formats are described in 176 [IDENTIFIER-QUERY] and [IDENTIFIER-RESPONSES], while this document 177 describes how IIIDAP clients and servers use HTTP to exchange 178 queries and responses. [IDENTIFIER-SECURITY] describes security 179 considerations for IIIDAP. 181 2.1. Acronyms and Abbreviations 183 IIIDAP: Industrial Internet Identifier Data Access Protocol 184 SLN: Second-Level Nodes 186 ELN: Enterprise-Level Nodes 188 3. Design Intents 190 There are a few design criteria this document attempts to meet. 192 First, each query is meant to require only one path of execution to 193 obtain an answer. A response may contain an answer, no answer, or a 194 redirect, and clients are not expected to fork multiple paths of 195 execution to make a query. 197 Second, the semantics of the request/response allow for future 198 and/or non-standard response formats. In this document, only a JSON 199 [RFC7159] response media type is noted, with the response contents 200 to be described separately (see [IDENTIFIER-RESPONSES]). This 201 document only describes how IIIDAP is transported using HTTP with 202 this format. 204 Third, this protocol is intended to be able to make use of the range 205 of mechanisms available for use with HTTP. HTTP offers a number of 206 mechanisms not described further in this document. Operators are 207 able to make use of these mechanisms according to their local 208 policy, including cache control, authorization, compression, and 209 redirection. HTTP also benefits from widespread investment in 210 scalability, reliability, and performance, as well as widespread 211 programmer understanding of client behaviors for web services styled 212 after REST [REST], reducing the cost to deploy Registration Data 213 Directory Services and clients. This protocol is forward compatible 214 with HTTP 2.0. 216 4. Queries 218 4.1. HTTP Methods 220 Clients use the GET method to retrieve a response body and use the 221 HEAD method to determine existence of data on the server. Clients 222 SHOULD use either the HTTP GET or HEAD methods (see [RFC7231]). 223 Servers are under no obligation to support other HTTP methods; 224 therefore, clients using other methods will likely not interoperate 225 properly. 227 Clients and servers MUST support HTTPS to support security services. 229 4.2. Accept Header 231 To indicate to servers that an IIIDAP response is desired, clients 232 include an Accept header field with an IIIDAP-specific JSON media 233 type, the generic JSON media type, or both. Servers receiving an 234 IIIDAP request return an entity with a Content-Type header 235 containing the IIIDAP-specific JSON media type. 237 This specification does not define the responses a server returns to 238 a request with any other media types in the Accept header field, or 239 with no Accept header field. One possibility would be to return a 240 response in a media type suitable for rendering in a web browser. 242 4.3. Query Parameters 244 Servers MUST ignore unknown query parameters. Use of unknown query 245 parameters for cache busting is described in Appendix B. 247 5. Types of HTTP Response 249 This section describes the various types of responses a server may 250 send to a client. While no standard HTTP response code is forbidden 251 in usage, this section defines the minimal set of response codes in 252 common use by servers that a client will need to understand. While 253 some clients may be constructed with simple tooling that does not 254 account for all of these response codes, a more robust client 255 accounting for these codes will likely provide a better user 256 experience. It is expected that usage of response codes and types 257 for this application not defined here will be described in 258 subsequent documents. 260 5.1. Positive Answers 262 If a server has the information requested by the client and wishes 263 to respond to the client with the information according to its 264 policies, it returns that answer in the body of a 200 (OK) response 265 (see [RFC7231]). 267 5.2. Redirects 269 If a server wishes to inform a client that the answer to a given 270 query can be found elsewhere, it returns either a 301 (Moved 271 Permanently) response code to indicate a permanent move or a 302 272 (Found), 303 (See Other), or 307 (Temporary Redirect) response code 273 to indicate a non-permanent redirection, and it includes an HTTP(S) 274 URL in the Location header field (see [RFC7231]). The client is 275 expected to issue a subsequent request to satisfy the original query 276 using the given URL without any processing of the URL. In other 277 words, the server is to hand back a complete URL, and the client 278 should not have to transform the URL to follow it. Servers are under 279 no obligation to return a URL conformant to [IDENTIFIER-QUERY]. 281 For this application, such an example of a permanent move might be a 282 SLN operator informing a client the information being sought can be 283 found with another SLN operator (i.e., a query for the identifier 284 86.100.1 in foo.example is found at 285 http://foo.example/identifier/86.100.1). 287 For example, if the client uses 289 http://serv1.example.com/weirds/identifier/86.100.1 291 the server redirecting to 293 https://serv2.example.net/weirds2/ 295 would set the Location: field to the value 297 https://serv2.example.net/weirds2/identifier/86.100.1 299 5.3. Negative Answers 301 If a server wishes to respond that it has an empty result set (that 302 is, no data appropriately satisfying the query), it returns a 404 303 (Not Found) response code. Optionally, it MAY include additional 304 information regarding the negative answer in the HTTP entity body. 306 If a server wishes to inform the client that information about the 307 query is available, but cannot include the information in the 308 response to the client for policy reasons, the server MUST respond 309 with an appropriate response code out of HTTP's 4xx range. A client 310 MAY retry the query if that is appropriate for the respective 311 response code. 313 5.4. Malformed Queries 315 If a server receives a query that it cannot interpret as an IIIDAP 316 query, it returns a 400 (Bad Request) response code. Optionally, it 317 MAY include additional information regarding this negative answer in 318 the HTTP entity body. 320 5.5. Rate Limits 322 Some servers apply rate limits to deter address scraping and other 323 abuses. When a server declines to answer a query due to rate limits, 324 it returns a 429 (Too Many Requests) response code as described in 325 [RFC6585]. A client that receives a 429 response SHOULD decrease its 326 query rate and honor the Retry-After header field if one is present. 327 Servers may place stricter limits upon clients that do not honor the 328 Retry-After header. Optionally, the server MAY include additional 329 information regarding the rate limiting in the HTTP entity body. 331 Note that this is not a defense against denial-of-service (DoS) 332 attacks, since a malicious client could ignore the code and continue 333 to send queries at a high rate. A server might use another response 334 code if it did not wish to reveal to a client that rate limiting is 335 the reason for the denial of a reply. 337 5.6. Cross-Origin Resource Sharing (CORS) 339 When responding to queries, it is RECOMMENDED that servers use the 340 Access-Control-Allow-Origin header field, as specified by [W3C.REC- 341 cors-20140116]. A value of "*" is suitable when IIIDAP is used for 342 public resources. 344 This header (often called the CORS header) helps in-browser web 345 applications by lifting the "same-origin" restriction (i.e., a 346 browser may load IIIDAP client code from one web server but query 347 others for IIIDAP data). 349 By default, browsers do not send cookies when cross origin requests 350 are allowed. Setting the Access-Control-Allow-Credentials header 351 field to "true" will send cookies. Use of the Access-Control-Allow- 352 Credentials header field is NOT RECOMMENDED. 354 6. Security Considerations 356 This document does not pose strong security requirements to the 357 IIIDAP protocol. However, it does not restrict against the use of 358 security mechanisms offered by the HTTP protocol. It does require 359 that IIIDAP clients and servers MUST support HTTPS. 361 This document makes recommendations for server implementations 362 against DoS (Section 5.5) and interoperability with existing 363 security mechanisms in HTTP clients (Section 5.6). 365 Additional security considerations to the IIIDAP protocol are 366 covered in [IDENTIFIER-SECURITY]. 368 7. Internationalization Considerations 370 7.1. URIs and IRIs 372 Clients can use Internationalized Resource Identifiers (IRIs) 373 [RFC3987] for internal use as they see fit but MUST transform them 374 to URIs [RFC3986] for interaction with IIIDAP servers. IIIDAP 375 servers MUST use URIs in all responses, and again clients can 376 transform these URIs to IRIs for internal use as they see fit. 378 7.2. Language Identifiers in Queries and Responses 380 Under most scenarios, clients requesting data will not signal that 381 the data be returned in a particular language or script. On the 382 other hand, when servers return data and have knowledge that the 383 data is in a language or script, the data SHOULD be annotated with 384 language identifiers whenever they are available, thus allowing 385 clients to process and display the data accordingly. 387 [IDENTIFIER-RESPONSES] provides such a mechanism. 389 7.3. Language Identifiers in HTTP Headers 391 Given the description of the use of language identifiers in Section 392 9.2, unless otherwise specified, servers SHOULD ignore the HTTP 393 [RFC7231] Accept-Language header field when formulating HTTP entity 394 responses, so that clients do not conflate the Accept-Language 395 header with the 'lang' values in the entity body. 397 However, servers MAY return language identifiers in the Content- 398 Language header field so as to inform clients of the intended 399 language of HTTP layer messages. 401 8. References 403 8.1. Normative References 405 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 406 Requirement Levels", BCP 14, RFC 2119, March 1997, 407 . 409 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 410 Resource Identifier (URI): Generic Syntax", STD 66, RFC 411 3986, January 2005, 412 . 414 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 415 Identifiers (IRIs)", RFC 3987, January 2005, 416 . 418 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 419 Codes", RFC 6585, April 2012, 420 . 422 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 423 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 424 7230, June 2014, 425 . 427 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 428 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 429 June 2014, 430 . 432 [W3C.REC-cors-20140116] 433 Kesteren, A., "Cross-Origin Resource Sharing", W3C 434 Recommendation, REC-cors-20140116, January 2014, 435 . 437 8.2. Informative References 439 [REST] Fielding, R. and R. Taylor, "Principled Design of the 440 Modern Web Architecture", ACM Transactions on Internet 441 Technology, Vol. 2, No. 2, May 2002. 443 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 444 Interchange Format", RFC 7159, March 2014, 445 . 447 [IDENTIFIER-SECURITY] 448 Ma, C., "Security Services for the Industrial Internet 449 Identifier Data Access Protocol (IIIDAP)", Work in 450 Progress, draft-mcd-identifier-access-security-00, 451 December 2019. 453 [IDENTIFIER-QUERY] 454 Ma, C., "Industrial Internet Identifier Data Access 455 Protocol (IIIDAP) Query Format", Work in Progress, draft- 456 mcd-identifier-access-query-00, December 2019. 458 [IDENTIFIER-RESPONSES] 459 Ma, C., "JSON Responses for the Industrial Internet 460 Identifier Data Access Protocol (IIIDAP)", Work in 461 Progress, draft-mcd-identifier-access-responce-00, 462 December 2019. 464 [IDENTIFIER-AUTHORIZATION] 465 Ma, C., "Finding the Authoritative Registration Data 466 (IIIDAP) Service", Work in Progress, draft-mcd-identifier- 467 access-authority-00, December 2019. 469 Appendix A. Protocol Example 471 To demonstrate typical behavior of an IIIDAP client and server, the 472 following is an example of an exchange, including a redirect. The 473 data in the response has been elided for brevity, as the data format 474 is not described in this document. The media type used here is 475 described in [IDENTIFIER-RESPONSES]. 477 An example of an IIIDAP client and server exchange: 479 Client: 480 481 GET /iiidap/identifier/86.100.1 HTTP/1.1 482 Host: iiidap.example.com 483 Accept: application/iiidap+json 485 iiidap.example.com: 486 HTTP/1.1 301 Moved Permanently 487 Location: http://iiidap- 488 identifier.example.com/iiidap/identifier/86.100.1 489 Content-Length: 0 490 Content-Type: application/iiidap+json 491 493 Client: 494 495 GET /iiidap/identifier/86.100.1 HTTP/1.1 496 Host: iiidap-identifier.example.com 497 Accept: application/iiidap+json 499 iiidap-identifier.example.com: 500 HTTP/1.1 200 OK 501 Content-Type: application/iiidap+json 502 Content-Length: 9001 504 { ... } 505 507 Appendix B. Cache Busting 509 Some HTTP [RFC7230] cache infrastructures do not adhere to caching 510 standards adequately and could cache responses longer than is 511 intended by the server. To overcome these issues, clients can use an 512 ad hoc and improbably used query parameter with a random value of 513 their choosing. As Section 4.3 instructs servers to ignore unknown 514 parameters, this is compatible with the IIIDAP definition. 516 An example of using an unknown query parameter to bust caches: 518 http://example.com/identifier/86.100.1?__fuhgetaboutit=xyz123 520 Use of an unknown parameter to overcome misbehaving caches is not 521 part of any specification and is offered here for informational 522 purposes. 524 Appendix C. Bootstrapping and Redirection 526 These issues are solved in IIIDAP using HTTP redirects and 527 bootstrapping. Bootstrapping is discussed in [IDENTIFIER- 528 AUTHORIZATION]. In constrained environments, the processes outlined 529 in [IDENTIFIER-AUTHORIZATION] may not be viable, and there may be 530 the need for servers acting as a "redirector". 532 Redirector servers issue HTTP redirects to clients using a 533 redirection table informed by [IDENTIFIER-AUTHORIZATION]. Figure 1 534 diagrams a client using a redirector for bootstrapping. 536 REDIRECTOR ARIN 537 IIIDAP IIIDAP 538 . . 539 | | 540 Q: 86.100.1? -----------------> | | 541 | | 542 <---------- HTTP 301 --------| | 543 ('Try ARIN IIIDAP') | | 544 | | 545 | 546 Q: 86.100.1? -------------------------------> | 547 | 548 <---------- HTTP 200 --------------------- | 549 (JSON response is returned) | 550 | 551 | 552 . 554 Figure 1: Querying IIIDAP Data for 86.100.1 556 In some cases, multiple HTTP redirects will be issued. Figure 2 557 shows such a scenario. 559 REDIRECTOR LACNIC ARIN 560 IIIDAP IIIDAP IIIDAP 561 . . . 562 Q: 86.100.1? ----> | | | 563 | | | 564 <-- HTTP 301 --- | | | 565 ('Try LACNIC') | | | 566 | | | 567 | | | 568 Q: 86.100.1? -----------------> | | 569 | | 570 <---------- HTTP 301 --------| | 571 ('Try ARIN IIIDAP') | | 572 | | 573 | 574 Q: 86.100.1? -------------------------------> | 575 | 576 <---------- HTTP 200 --------------------- | 577 (JSON response is returned) | 578 | 579 | 580 . 582 Figure 2: Querying IIIDAP Data for Data That Has Been Transferred 584 Authors' Addresses 586 Chendi Ma 587 CAICT 588 No.52 Huayuan North Road, Haidian District 589 Beijing, Beijing, 100191 590 China 592 Phone: +86 177 1090 9864 593 Email: machendi@caict.ac.cn 595 Chen Jian 596 CAICT 597 No.52 Huayuan North Road, Haidian District 598 Beijing, Beijing, 100191 599 China 601 Phone: +86 138 1103 3332 602 Email: chenjian3@caict.ac.cn 604 Xiaotian Fan 605 CAICT 606 No.52 Huayuan North Road, Haidian District 607 Beijing, Beijing, 100191 608 China 610 Phone: +86 134 0108 6945 611 Email: fanxiaotian@caict.ac.cn 613 Meilan Chen 614 CAICT 615 No.52 Huayuan North Road, Haidian District 616 Beijing, Beijing, 100191 617 China 619 Phone: +86 139 1143 7301 620 Email: chenmeilan@caict.ac.cn 621 Zhiping Li 622 CAICT 623 No.52 Huayuan North Road, Haidian District 624 Beijing, Beijing, 100191 625 China 627 Phone: +86 185 1107 1386 628 Email: lizhiping@caict.ac.cn