idnits 2.17.1 draft-ma-identifier-access-http-02.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 (June 22, 2020) is 1404 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** 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-01 == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-query-01 == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-responce-01 == Outdated reference: A later version (-08) exists of draft-mcd-identifier-access-authority-01 Summary: 2 errors (**), 0 flaws (~~), 5 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: Informational X. Fan 4 Expires: December 22, 2020 M. Chen 5 Z. Li 6 China Academy of Information and Communications Technology 7 June 22, 2020 9 HTTP Usage in the Industrial Internet Identifier Data Access 10 Protocol (IIIDAP) 11 draft-ma-identifier-access-http-02 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 December 22, 2020. 36 Copyright Notice 38 Copyright (c) 2020 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. IANA Considerations ......................................... 9 92 9. References .................................................. 9 93 9.1. Normative References.................................... 9 94 9.2. Informative References................................. 10 95 Appendix A. Protocol Example................................... 12 96 Appendix B. Cache Busting...................................... 13 97 Appendix C. Bootstrapping and Redirection...................... 14 99 1. Introduction 101 This document describes the usage of the Hypertext Transfer Protocol 102 (HTTP) [RFC7230] for the Industrial Internet Identifier Data Access 103 Protocol (IIIDAP). The goal of this document is to tie together 104 usage patterns of HTTP into a common profile applicable to the 105 various types of directory services serving identifier data using 106 practices informed by the Representational State Transfer (REST) 107 [REST] architectural style. By giving the various directory services 108 common behavior, a single client is better able to retrieve data 109 from directory services adhering to this behavior. 111 Identifier data expected to be presented by this service is 112 Industrial Internet Identifier data -- some of the information that 113 identifiers of Second-Level Nodes (SLN) and Enterprise-Level Nodes 114 (ELN) contain (see [IDENTIFIER-RESPONSES]). This protocol is 115 expected to provide a specification for queries and responses, 116 redirection to authoritative sources, and support for localized 117 identifier data such as addresses and organization or person names. 118 This function is expected to be provided by SLN. 120 In designing these common usage patterns, this document introduces 121 considerations for a simple use of HTTP. Where complexity may 122 reside, it is the goal of this document to place it upon the server 123 and to keep the client as simple as possible. A client 124 implementation should be possible using common operating system 125 scripting tools (e.g., bash and wget). 127 This is the basic usage pattern for this protocol: 129 1. A client determines an appropriate server to query along with the 130 appropriate base Uniform Resource Locator (URL) to use in such 131 queries. [IDENTIFIER-AUTHORIZATION] describes one method to 132 determine the server and the base URL. See Appendix C for more 133 information. 135 2. A client issues an HTTP (or HTTPS) query using GET [RFC7231]. As 136 an example, a query URL for the enterprise identifier 86.100.1 137 might be 138 http://example.com/iiidap/identifier/86.100.1 140 [IDENTIFIER-QUERY] details the various queries used in IIIDAP. 142 3. If the receiving server has the information for the query, it 143 examines the Accept header field of the query and returns a 200 144 response with a response entity appropriate for the requested 145 format. [IDENTIFIER-RESPONSES] details a response in JavaScript 146 Object Notation (JSON). 148 4. If the receiving server does not have the information for the 149 query but does have knowledge of where the information can be 150 found, it will return a redirection response (3xx) with the 151 Location header field containing an HTTP(S) URL pointing to the 152 information or another server known to have knowledge of the 153 location of the information. The client is expected to require 154 using that HTTP URL. 156 5. If the receiving server does not have the information being 157 requested and does not have knowledge of where the information 158 can be found, it returns a 404 response. 160 6. If the receiving server will not answer a request for policy 161 reasons, it will return an error response (4xx) indicating the 162 reason for giving no answer. 164 It is not the intent of this document to redefine the meaning and 165 semantics of HTTP. The purpose of this document is to clarify the 166 use of standard HTTP mechanisms for this application. 168 2. Conventions used in this document 170 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 172 document are to be interpreted as described in RFC 2119 [RFC2119]. 174 In this document, an IIIDAP client is an HTTP user agent performing 175 an IIIDAP query, and an IIIDAP server is an HTTP server providing an 176 IIIDAP response. IIIDAP query and response formats are described in 177 [IDENTIFIER-QUERY] and [IDENTIFIER-RESPONSES], while this document 178 describes how IIIDAP clients and servers use HTTP to exchange 179 queries and responses. [IDENTIFIER-SECURITY] describes security 180 considerations for IIIDAP. 182 2.1. Acronyms and Abbreviations 184 IIIDAP: Industrial Internet Identifier Data Access Protocol 185 SLN: Second-Level Nodes 187 ELN: Enterprise-Level Nodes 189 3. Design Intents 191 There are a few design criteria this document attempts to meet. 193 First, each query is meant to require only one path of execution to 194 obtain an answer. A response may contain an answer, no answer, or a 195 redirect, and clients are not expected to fork multiple paths of 196 execution to make a query. 198 Second, the semantics of the request/response allow for future 199 and/or non-standard response formats. In this document, only a JSON 200 [RFC7159] response media type is noted, with the response contents 201 to be described separately (see [IDENTIFIER-RESPONSES]). This 202 document only describes how IIIDAP is transported using HTTP with 203 this format. 205 Third, this protocol is intended to be able to make use of the range 206 of mechanisms available for use with HTTP. HTTP offers a number of 207 mechanisms not described further in this document. Operators are 208 able to make use of these mechanisms according to their local 209 policy, including cache control, authorization, compression, and 210 redirection. HTTP also benefits from widespread investment in 211 scalability, reliability, and performance, as well as widespread 212 programmer understanding of client behaviors for web services styled 213 after REST [REST], reducing the cost to deploy Registration Data 214 Directory Services and clients. This protocol is forward compatible 215 with HTTP 2.0. 217 4. Queries 219 4.1. HTTP Methods 221 Clients use the GET method to retrieve a response body and use the 222 HEAD method to determine existence of data on the server. Clients 223 SHOULD use either the HTTP GET or HEAD methods (see [RFC7231]). 224 Servers are under no obligation to support other HTTP methods; 225 therefore, clients using other methods will likely not interoperate 226 properly. 228 Clients and servers MUST support HTTPS to support security services. 230 4.2. Accept Header 232 To indicate to servers that an IIIDAP response is desired, clients 233 include an Accept header field with an IIIDAP-specific JSON media 234 type, the generic JSON media type, or both. Servers receiving an 235 IIIDAP request return an entity with a Content-Type header 236 containing the IIIDAP-specific JSON media type. 238 This specification does not define the responses a server returns to 239 a request with any other media types in the Accept header field, or 240 with no Accept header field. One possibility would be to return a 241 response in a media type suitable for rendering in a web browser. 243 4.3. Query Parameters 245 Servers MUST ignore unknown query parameters. Use of unknown query 246 parameters for cache busting is described in Appendix B. 248 5. Types of HTTP Response 250 This section describes the various types of responses a server may 251 send to a client. While no standard HTTP response code is forbidden 252 in usage, this section defines the minimal set of response codes in 253 common use by servers that a client will need to understand. While 254 some clients may be constructed with simple tooling that does not 255 account for all of these response codes, a more robust client 256 accounting for these codes will likely provide a better user 257 experience. It is expected that usage of response codes and types 258 for this application not defined here will be described in 259 subsequent documents. 261 5.1. Positive Answers 263 If a server has the information requested by the client and wishes 264 to respond to the client with the information according to its 265 policies, it returns that answer in the body of a 200 (OK) response 266 (see [RFC7231]). 268 5.2. Redirects 270 If a server wishes to inform a client that the answer to a given 271 query can be found elsewhere, it returns either a 301 (Moved 272 Permanently) response code to indicate a permanent move or a 302 273 (Found), 303 (See Other), or 307 (Temporary Redirect) response code 274 to indicate a non-permanent redirection, and it includes an HTTP(S) 275 URL in the Location header field (see [RFC7231]). The client is 276 expected to issue a subsequent request to satisfy the original query 277 using the given URL without any processing of the URL. In other 278 words, the server is to hand back a complete URL, and the client 279 should not have to transform the URL to follow it. Servers are under 280 no obligation to return a URL conformant to [IDENTIFIER-QUERY]. 282 For this application, such an example of a permanent move might be a 283 SLN operator informing a client the information being sought can be 284 found with another SLN operator (i.e., a query for the identifier 285 86.100.1 in foo.example is found at 286 http://foo.example/identifier/86.100.1). 288 For example, if the client uses 290 http://serv1.example.com/weirds/identifier/86.100.1 292 the server redirecting to 294 https://serv2.example.net/weirds2/ 296 would set the Location: field to the value 298 https://serv2.example.net/weirds2/identifier/86.100.1 300 5.3. Negative Answers 302 If a server wishes to respond that it has an empty result set (that 303 is, no data appropriately satisfying the query), it returns a 404 304 (Not Found) response code. Optionally, it MAY include additional 305 information regarding the negative answer in the HTTP entity body. 307 If a server wishes to inform the client that information about the 308 query is available, but cannot include the information in the 309 response to the client for policy reasons, the server MUST respond 310 with an appropriate response code out of HTTP's 4xx range. A client 311 MAY retry the query if that is appropriate for the respective 312 response code. 314 5.4. Malformed Queries 316 If a server receives a query that it cannot interpret as an IIIDAP 317 query, it returns a 400 (Bad Request) response code. Optionally, it 318 MAY include additional information regarding this negative answer in 319 the HTTP entity body. 321 5.5. Rate Limits 323 Some servers apply rate limits to deter address scraping and other 324 abuses. When a server declines to answer a query due to rate limits, 325 it returns a 429 (Too Many Requests) response code as described in 326 [RFC6585]. A client that receives a 429 response SHOULD decrease its 327 query rate and honor the Retry-After header field if one is present. 328 Servers may place stricter limits upon clients that do not honor the 329 Retry-After header. Optionally, the server MAY include additional 330 information regarding the rate limiting in the HTTP entity body. 332 Note that this is not a defense against denial-of-service (DoS) 333 attacks, since a malicious client could ignore the code and continue 334 to send queries at a high rate. A server might use another response 335 code if it did not wish to reveal to a client that rate limiting is 336 the reason for the denial of a reply. 338 5.6. Cross-Origin Resource Sharing (CORS) 340 When responding to queries, it is RECOMMENDED that servers use the 341 Access-Control-Allow-Origin header field, as specified by [W3C.REC- 342 cors-20140116]. A value of "*" is suitable when IIIDAP is used for 343 public resources. 345 This header (often called the CORS header) helps in-browser web 346 applications by lifting the "same-origin" restriction (i.e., a 347 browser may load IIIDAP client code from one web server but query 348 others for IIIDAP data). 350 By default, browsers do not send cookies when cross origin requests 351 are allowed. Setting the Access-Control-Allow-Credentials header 352 field to "true" will send cookies. Use of the Access-Control-Allow- 353 Credentials header field is not recommended. 355 6. Security Considerations 357 This document does not pose strong security requirements to the 358 IIIDAP protocol. However, it does not restrict against the use of 359 security mechanisms offered by the HTTP protocol. It does require 360 that IIIDAP clients and servers MUST support HTTPS. 362 This document makes recommendations for server implementations 363 against DoS (Section 5.5) and interoperability with existing 364 security mechanisms in HTTP clients (Section 5.6). 366 Additional security considerations to the IIIDAP protocol are 367 covered in [IDENTIFIER-SECURITY]. 369 7. Internationalization Considerations 371 7.1. URIs and IRIs 373 Clients can use Internationalized Resource Identifiers (IRIs) 374 [RFC3987] for internal use as they see fit but MUST transform them 375 to URIs [RFC3986] for interaction with IIIDAP servers. IIIDAP 376 servers MUST use URIs in all responses, and again clients can 377 transform these URIs to IRIs for internal use as they see fit. 379 7.2. Language Identifiers in Queries and Responses 381 Under most scenarios, clients requesting data will not signal that 382 the data be returned in a particular language or script. On the 383 other hand, when servers return data and have knowledge that the 384 data is in a language or script, the data SHOULD be annotated with 385 language identifiers whenever they are available, thus allowing 386 clients to process and display the data accordingly. 388 [IDENTIFIER-RESPONSES] provides such a mechanism. 390 7.3. Language Identifiers in HTTP Headers 392 Given the description of the use of language identifiers in Section 393 9.2, unless otherwise specified, servers SHOULD ignore the HTTP 394 [RFC7231] Accept-Language header field when formulating HTTP entity 395 responses, so that clients do not conflate the Accept-Language 396 header with the 'lang' values in the entity body. 398 However, servers MAY return language identifiers in the Content- 399 Language header field so as to inform clients of the intended 400 language of HTTP layer messages. 402 8. IANA Considerations 404 9. References 406 9.1. Normative References 408 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 409 Requirement Levels", BCP 14, RFC 2119, March 1997, 410 . 412 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 413 Resource Identifier (URI): Generic Syntax", STD 66, RFC 414 3986, January 2005, 415 . 417 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 418 Identifiers (IRIs)", RFC 3987, January 2005, 419 . 421 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 422 Codes", RFC 6585, April 2012, 423 . 425 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 426 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 427 7230, June 2014, 428 . 430 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 431 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 432 June 2014, 433 . 435 [W3C.REC-cors-20140116] 436 Kesteren, A., "Cross-Origin Resource Sharing", W3C 437 Recommendation, REC-cors-20140116, January 2014, 438 . 440 9.2. Informative References 442 [REST] Fielding, R. and R. Taylor, "Principled Design of the 443 Modern Web Architecture", ACM Transactions on Internet 444 Technology, Vol. 2, No. 2, May 2002. 446 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 447 Interchange Format", RFC 7159, March 2014, 448 . 450 [IDENTIFIER-SECURITY] 451 Ma, C., "Security Services for the Industrial Internet 452 Identifier Data Access Protocol (IIIDAP)", Work in 453 Progress, draft-mcd-identifier-access-security-01, June 454 2020. 456 [IDENTIFIER-QUERY] 457 Ma, C., "Industrial Internet Identifier Data Access 458 Protocol (IIIDAP) Query Format", Work in Progress, draft- 459 mcd-identifier-access-query-01, June 2020. 461 [IDENTIFIER-RESPONSES] 462 Ma, C., "JSON Responses for the Industrial Internet 463 Identifier Data Access Protocol (IIIDAP)", Work in 464 Progress, draft-mcd-identifier-access-responce-01, June 465 2020. 467 [IDENTIFIER-AUTHORIZATION] 468 Ma, C., "Finding the Authoritative Registration Data 469 (IIIDAP) Service", Work in Progress, draft-mcd-identifier- 470 access-authority-01, June 2020. 472 Appendix A. Protocol Example 474 To demonstrate typical behavior of an IIIDAP client and server, the 475 following is an example of an exchange, including a redirect. The 476 data in the response has been elided for brevity, as the data format 477 is not described in this document. The media type used here is 478 described in [IDENTIFIER-RESPONSES]. 480 An example of an IIIDAP client and server exchange: 482 Client: 483 484 GET /iiidap/identifier/86.100.1 HTTP/1.1 485 Host: iiidap.example.com 486 Accept: application/iiidap+json 488 iiidap.example.com: 489 HTTP/1.1 301 Moved Permanently 490 Location: http://iiidap- 491 identifier.example.com/iiidap/identifier/86.100.1 492 Content-Length: 0 493 Content-Type: application/iiidap+json 494 496 Client: 497 498 GET /iiidap/identifier/86.100.1 HTTP/1.1 499 Host: iiidap-identifier.example.com 500 Accept: application/iiidap+json 502 iiidap-identifier.example.com: 503 HTTP/1.1 200 OK 504 Content-Type: application/iiidap+json 505 Content-Length: 9001 507 { ... } 508 510 Appendix B. Cache Busting 512 Some HTTP [RFC7230] cache infrastructures do not adhere to caching 513 standards adequately and could cache responses longer than is 514 intended by the server. To overcome these issues, clients can use an 515 ad hoc and improbably used query parameter with a random value of 516 their choosing. As Section 4.3 instructs servers to ignore unknown 517 parameters, this is compatible with the IIIDAP definition. 519 An example of using an unknown query parameter to bust caches: 521 http://example.com/identifier/86.100.1?__fuhgetaboutit=xyz123 523 Use of an unknown parameter to overcome misbehaving caches is not 524 part of any specification and is offered here for informational 525 purposes. 527 Appendix C. Bootstrapping and Redirection 529 These issues are solved in IIIDAP using HTTP redirects and 530 bootstrapping. Bootstrapping is discussed in [IDENTIFIER- 531 AUTHORIZATION]. In constrained environments, the processes outlined 532 in [IDENTIFIER-AUTHORIZATION] may not be viable, and there may be 533 the need for servers acting as a "redirector". 535 Redirector servers issue HTTP redirects to clients using a 536 redirection table informed by [IDENTIFIER-AUTHORIZATION]. Figure 1 537 diagrams a client using a redirector for bootstrapping. 539 REDIRECTOR ARIN 540 IIIDAP IIIDAP 541 . . 542 | | 543 Q: 86.100.1? -----------------> | | 544 | | 545 <---------- HTTP 301 --------| | 546 ('Try ARIN IIIDAP') | | 547 | | 548 | 549 Q: 86.100.1? -------------------------------> | 550 | 551 <---------- HTTP 200 --------------------- | 552 (JSON response is returned) | 553 | 554 | 555 . 557 Figure 1: Querying IIIDAP Data for 86.100.1 559 In some cases, multiple HTTP redirects will be issued. Figure 2 560 shows such a scenario. 562 REDIRECTOR LACNIC ARIN 563 IIIDAP IIIDAP IIIDAP 564 . . . 565 Q: 86.100.1? ----> | | | 566 | | | 567 <-- HTTP 301 --- | | | 568 ('Try LACNIC') | | | 569 | | | 570 | | | 571 Q: 86.100.1? -----------------> | | 572 | | 573 <---------- HTTP 301 --------| | 574 ('Try ARIN IIIDAP') | | 575 | | 576 | 577 Q: 86.100.1? -------------------------------> | 578 | 579 <---------- HTTP 200 --------------------- | 580 (JSON response is returned) | 581 | 582 | 583 . 585 Figure 2: Querying IIIDAP Data for Data That Has Been Transferred 587 Authors' Addresses 589 Chendi Ma 590 CAICT 591 No.52 Huayuan North Road, Haidian District 592 Beijing, Beijing, 100191 593 China 595 Phone: +86 177 1090 9864 596 Email: machendi@caict.ac.cn 598 Chen Jian 599 CAICT 600 No.52 Huayuan North Road, Haidian District 601 Beijing, Beijing, 100191 602 China 604 Phone: +86 138 1103 3332 605 Email: chenjian3@caict.ac.cn 607 Xiaotian Fan 608 CAICT 609 No.52 Huayuan North Road, Haidian District 610 Beijing, Beijing, 100191 611 China 613 Phone: +86 134 0108 6945 614 Email: fanxiaotian@caict.ac.cn 616 Meilan Chen 617 CAICT 618 No.52 Huayuan North Road, Haidian District 619 Beijing, Beijing, 100191 620 China 622 Phone: +86 139 1143 7301 623 Email: chenmeilan@caict.ac.cn 624 Zhiping Li 625 CAICT 626 No.52 Huayuan North Road, Haidian District 627 Beijing, Beijing, 100191 628 China 630 Phone: +86 185 1107 1386 631 Email: lizhiping@caict.ac.cn