idnits 2.17.1 draft-mcd-identifier-access-query-05.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 21, 2022) is 672 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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 21, 2022 M. Chen 5 Z. Li 6 China Academy of Information and Communications Technology 7 June 21, 2022 9 Industrial Internet Identifier Data Access Protocol (IIIDAP) Query 10 Format 11 draft-mcd-identifier-access-query-05 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 21, 2022. 36 Copyright Notice 38 Copyright (c) 2022 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 Abstract 53 This document describes uniform patterns to construct HTTP URLs that 54 may be used to retrieve identifier information from Second-Level 55 Nodes (SLN) using "RESTful" web access patterns. These uniform 56 patterns define the query syntax for the Industrial Internet 57 Identifier Data Access Protocol (IIIDAP). 59 Table of Contents 61 1. Introduction ................................................ 2 62 2. Conventions used in this document ............................ 3 63 2.1. Acronyms and Abbreviations .............................. 3 64 3. Path Segment Specification ................................... 4 65 3.1. Lookup Path Segment Specification ....................... 4 66 3.1.1. Identifier Path Segment Specification .............. 4 67 3.1.2. Name Path Segment Specification .................... 5 68 3.1.3. Help Path Segment Specification .................... 5 69 3.2. Search Path Segment Specification ....................... 6 70 3.2.1. Name Search ........................................ 6 71 4. Query Processing ............................................ 6 72 4.1. Partial String Searching ................................ 7 73 4.2. Associated Records ...................................... 7 74 5. Internationalization Considerations .......................... 8 75 5.1. Character Encoding Considerations ....................... 8 76 6. Security Considerations ...................................... 9 77 7. IANA Considerations ......................................... 9 78 8. References .................................................. 9 79 8.1. Normative References ................................... 10 80 8.2. Informative References ................................. 10 82 1. Introduction 84 This document describes a specification for querying identifier data 85 using a RESTful web service and uniform query patterns. The service 86 is implemented using the Hypertext Transfer Protocol (HTTP) 87 [RFC9110] and the conventions described in [IDENTIFIER-HTTP]. These 88 uniform patterns define the query syntax for the Industrial Internet 89 Identifier Data Access Protocol (IIIDAP). 91 The intent of the patterns described here are to enable queries of 92 the identifier information by identifiers or names. [RFC3986] 93 patterns specified in this document are only applicable to the HTTP 94 [RFC9110] GET and HEAD methods. As described in Section 4.1 of 95 [IDENTIFIER-HTTP], HEAD method can be used to determine, if an 96 object exists (or not) without returning IIIDAP-encoded results; GET 97 method can be used to retrieve detailed results. 99 This document does not describe the results or entities returned 100 from issuing the described URLs with an HTTP GET. The specification 101 of these entities is described in [IDENTIFIER-RESPONSES]. 103 Additionally, resource management, provisioning, and update 104 functions are out of scope for this document. Second-Level Nodes 105 (SLN) have various and divergent methods covering these functions, 106 and it is unlikely a uniform approach is needed for 107 interoperability. 109 HTTP contains mechanisms for servers to authenticate clients and for 110 clients to authenticate servers (from which authorization schemes 111 may be built), so such mechanisms are not described in this 112 document. Policy, provisioning, and processing of authentication and 113 authorization are out of scope for this document as deployments will 114 have to make choices based on local criteria. Supported 115 authentication mechanisms are described in [IDENTIFIER-SECURITY]. 117 2. Conventions used in this document 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 121 document are to be interpreted as described in [RFC2119]. 123 2.1. Acronyms and Abbreviations 125 TLN: Top-Level Nodes 127 SLN: Second-Level Nodes 129 ELN: Enterprise-Level Nodes 131 NFC: Unicode Normalization Form C [Unicode-UAX15] 133 NFKC: Unicode Normalization Form KC [Unicode-UAX15] 135 IIIDAP: Industrial Internet Identifier Data Access Protocol 136 REST: Representational State Transfer. The term was first described 137 in a doctoral dissertation [REST]. 139 RESTful: An adjective that describes a service using HTTP and the 140 principles of REST. 142 3. Path Segment Specification 144 The base URLs used to construct IIIDAP queries are maintained in an 145 TLN described in [IDENTIFIER-AUTHORIZATION]. Queries are formed by 146 retrieving an appropriate base URL from the TLN and appending a path 147 segment specified in either Sections 3.1 or 3.2. Generally, a TLN or 148 other service provider will provide a base URL that identifies the 149 protocol, host, and port, and this will be used as a base URL that 150 the complete URL is resolved against, as per Section 5 of RFC 3986 151 [RFC3986]. For example, if the base URL is 152 "https://example.com/iiidap/", all IIIDAP query URLs will begin with 153 "https://example.com/iiidap/". 155 The bootstrap registry does not support searching for identifier 156 information through query fields that are not part of a global 157 namespace, including "name" and "help". A base URL for an associated 158 object is required to construct a complete query. 160 3.1. Lookup Path Segment Specification 162 The resource type path segments for exact match lookup are: 164 o 'identifier': Used to identify the identifier information of SLN 165 or ELN query using a string identifier. 167 o 'name': Used to identify the identifier information of SLN or ELN 168 query using a node (SLN or ELN) name. 170 3.1.1. Identifier Path Segment Specification 172 Syntax: identifier/ 174 Take Handle Protocol [RFC3651] as an example, Identifier format of 175 TLN is XX; identifier format of SLD is XX.YY; identifier format of 176 ELD is XX.YY.ZZ; XX, YY, ZZ are UTF-8 encoded character strings, 177 which use any characters from the Unicode 2.0 standard except the 178 ASCII character '/' (0x2F). Therefore, queries for information about 179 identifiers are of the form /identifier/XX.YY/...(for SLN) or 180 /identifier/XX.YY.ZZZ/...(for ELN) 181 For example, identifier of a TLN can be 86; identifier of a SLN can 182 be 86.100; identifier of a TLN can be 86.100.1; Identifiers of 183 TLN/SLN/ELN are usually called identifiers prefix in Industry 184 Internet Identifier System. Identifier suffix is used to identify a 185 product or component in an enterprise. Prefixes and suffixes are 186 joined by backslashes. The prefix and suffix together constitute the 187 globally qualified identity for a product or component. Naming rules 188 of identifier suffix is beyond the scope of this specification. The 189 length of an identifier of must range from 2 to 255 number 190 characters. 192 For example, the following URL would be used to find identifier 193 information for the most specific identifier of a SLN containing 194 86.100: 196 https://example.com/iiidap/identifier/86.100 198 The following URL would be used to find identifier information for 199 the most specific identifier of an ELN containing 86.100.1: 201 https://example.com/iiidap/identifier/86.100.1 203 3.1.2. Name Path Segment Specification 205 Syntax: name/ 207 Queries for identifier information regarding name of SLN or ELN are 208 of the form /name/XXX/... where XXX is the name of a SLN or ELN. XXX 209 is a string of length from 1 to 255. It can contain non-US-ASCII 210 characters. The detailed requirements for character encoding are 211 specified in Section 5.1. 213 For example, the following URL would be used to find identifier 214 information of the node named "mengniu": 216 https://example.com/iiidap/name/mengniu 218 3.1.3. Help Path Segment Specification 220 Syntax: help 222 The help path segment can be used to request helpful information 223 (command syntax, terms of service, privacy policy, rate-limiting 224 policy, supported authentication methods, supported extensions, 225 technical support contact, etc.) from an IIIDAP server. The response 226 to "help" should provide basic information that a client needs to 227 successfully use the service. The following URL would be used to 228 return "help" information: 230 https://example.com/iiidap/help 232 3.2. Search Path Segment Specification 234 Pattern matching semantics are described in Section 4.1. The name 235 path segment for search is: 237 o 'names': Used to identify a SLN or ELN identifier information 238 search using a pattern to match a fully qualified SLN/ELN name. 240 IIIDAP search path segments are formed using a concatenation of the 241 plural form of the object being searched for and an HTTP query 242 string. The HTTP query string is formed using a concatenation of the 243 question mark character ('?', US-ASCII value 0x003F), the JSON 244 object value associated with the object being searched for, the 245 equal sign character ('=', US-ASCII value 0x003D), and the search 246 pattern. Search pattern query processing is described more fully in 247 Section 4. For the name described in this document, the plural 248 object forms are "names". 250 3.2.1. Name Search 252 Syntax: names?name= 254 Searches for identifier information by name are specified using this 255 form: 257 names?name=XXXX 259 XXXX is a search pattern representing a name of SLN OR ELN. The 260 following URL would be used to find identifier information for SLN 261 or ELN names matching the "example*" pattern: 263 https://example.com/iiidap/names?name=example* 265 4. Query Processing 267 Servers indicate the success or failure of query processing by 268 returning an appropriate HTTP response code to the client. Response 269 codes not specifically identified in this document are described in 270 [IDENTIFIER-HTTP]. 272 4.1. Partial String Searching 274 Partial string searching uses the asterisk ('*', US-ASCII value 275 0x002A) character to match zero or more trailing characters. A 276 character string representing multiple names MAY be concatenated to 277 the end of the search pattern to limit the scope of the search. For 278 example, the search pattern "exam*" will match "example1" and 279 "example2". The search pattern "ex*mple" will match "example". If an 280 asterisk appears in a search string, any label that contains the 281 non-asterisk characters in sequence plus zero or more characters in 282 sequence in place of the asterisk would match. Additional pattern 283 matching processing is beyond the scope of this specification. 285 If a server receives a search request but cannot process the request 286 because it does not support a particular style of partial match 287 searching, it SHOULD return an HTTP 422 (Unprocessable Entity) 288 [RFC4918] response. When returning a 422 error, the server MAY also 289 return an error response body as specified in Section 6 of 290 [IDENTIFIER-RESPONSES] if the requested media type is one that is 291 specified in [IDENTIFIER-HTTP]. 293 Partial matching is not feasible across combinations of Unicode 294 characters because Unicode characters can be combined with each 295 other. Servers SHOULD NOT partially match combinations of Unicode 296 characters where a legal combination is possible. It should be 297 noted, though, that it may not always be possible to detect cases 298 where a character could have been combined with another character, 299 but was not, because characters can be combined in many different 300 ways. 302 Clients should avoid submitting a partial match search of Unicode 303 characters where a Unicode character may be legally combined with 304 another Unicode character or characters. Partial match searches with 305 incomplete combinations of characters where a character must be 306 combined with another character or characters are invalid. Partial 307 match searches with characters that may be combined with another 308 character or characters are to be considered non-combined characters 309 (that is, if character x may be combined with character y but 310 character y is not submitted in the search string, then character x 311 is a complete character and no combinations of character x are to be 312 searched). 314 4.2. Associated Records 316 Conceptually, any query-matching record in a server's database might 317 be a member of a set of related records, related in some fashion as 318 defined by the server. The entire set ought to be considered as 319 candidates for inclusion when constructing the response. However, 320 the construction of the final response needs to be mindful of 321 privacy and other data-releasing policies when assembling the IIIDAP 322 response set. 324 Note too that due to the nature of searching, there may be a list of 325 query-matching records. Each one of those is subject to being a 326 member of a set as described in the previous paragraph. What is 327 ultimately returned in a response will be the union of all the sets 328 that has been filtered by whatever policies are in place. 330 Note that this model includes arrangements for associated names, 331 including those that are linked by policy mechanisms and names bound 332 together for some other purposes. Note also that returning 333 information that was not explicitly selected by an exact-match 334 lookup, including additional names that match a relatively fuzzy 335 search as well as lists of names that are linked together, may cause 336 privacy issues. 338 Note that there might not be a single, static information return 339 policy that applies to all clients equally. Client identity and 340 associated authorizations can be a relevant factor in determining 341 how broad the response set will be for any particular query. 343 5. Internationalization Considerations 345 5.1. Character Encoding Considerations 347 Servers can expect to receive search patterns from clients that 348 contain character strings encoded in different forms supported by 349 HTTP. It is entirely possible to apply filters and normalization 350 rules to search patterns prior to making character comparisons, but 351 this type of processing is more typically needed to determine the 352 validity of registered strings than to match patterns. 354 An IIIDAP client submitting a query string containing non-US-ASCII 355 characters converts such strings into Unicode in UTF-8 encoding. It 356 then performs any local case mapping deemed necessary. Strings are 357 normalized using Normalization Form C (NFC) [Unicode-UAX15]; note 358 that clients might not be able to do this reliably. UTF-8 encoded 359 strings are then appropriately percent-encoded [RFC3986] in the 360 query URL. 362 After parsing any percent-encoding, an IIIDAP server treats each 363 query string as Unicode in UTF-8 encoding. If a string is not valid 364 UTF-8, the server can immediately stop processing the query and 365 return an HTTP 400 (Bad Request) response. 367 For everything else, servers map fullwidth and halfwidth characters 368 to their decomposition equivalents. Servers convert strings to the 369 same coded character set of the target data that is to be looked up 370 or searched, and each string is normalized using the same 371 normalization that was used on the target data. In general, storage 372 of strings as Unicode is RECOMMENDED. For the purposes of 373 comparison, Normalization Form KC (NFKC) [Unicode-UAX15] with case 374 folding is used to maximize predictability and the number of 375 matches. Note the use of case-folded NFKC as opposed to NFC in this 376 case. 378 6. Security Considerations 380 Security services for the operations specified in this document are 381 described in "Security Services for the Industrial Internet 382 Identifier Data Access Protocol (IIIDAP)" [IDENTIFIER-SECURITY]. 384 Search functionality typically requires more server resources (such 385 as memory, CPU cycles, and network bandwidth) when compared to basic 386 lookup functionality. This increases the risk of server resource 387 exhaustion and subsequent denial of service due to abuse. This risk 388 can be mitigated by developing and implementing controls to restrict 389 search functionality to identified and authorized clients. If those 390 clients behave badly, their search privileges can be suspended or 391 revoked. Rate limiting as described in Section 5.5 of "HTTP Usage in 392 the Industrial Internet Identifier Data Access Protocol (IIIDAP)" 393 [IDENTIFIER-HTTP] can also be used to control the rate of received 394 search requests. Server operators can also reduce their risk by 395 restricting the amount of information returned in response to a 396 search request. 398 Search functionality also increases the privacy risk of disclosing 399 object relationships that might not otherwise be obvious. 401 Note that there might not be a single, static information return 402 policy that applies to all clients equally. Client identity and 403 associated authorizations can be a relevant factor in determining 404 how broad the response set will be for any particular query. 406 7. IANA Considerations 408 8. References 410 References to IIIDAP are subject to the latest edition. 412 8.1. Normative References 414 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 415 Requirement Levels", BCP 14, RFC 2119, March 1997. 417 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 418 Resource Identifier (URI): Generic Syntax", STD 66, RFC 419 3986, January 2005, 420 . 422 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 423 Authoring and Versioning (WebDAV)", RFC 4918, June 2007, 424 . 426 [RFC9110] Fielding, R., Ed., M. Nottingham, Ed. and J. Reschke, Ed., 427 " HTTP Semantics", RFC 9110, June 2022, 428 . 430 [Unicode-UAX15] 431 The Unicode Consortium, "Unicode Standard Annex #15: 432 Unicode Normalization Forms", September 2013, 433 . 435 8.2. Informative References 437 [RFC3651] Sun, S., Reilly, S. and L. Lannom, "Handle System 438 Namespace and Service Definition", RFC 3651, November 439 2003, . 441 [REST] Fielding, R., "Architectural Styles and the Design of 442 Network-based Software Architectures", Ph.D. Dissertation, 443 University of California, Irvine, 2000, 444 . 447 [IDENTIFIER-HTTP] 448 Ma, C., "HTTP Usage in the Industrial Internet Identifier 449 Data Access Protocol (IIIDAP)", Work in Progress, draft- 450 ma-identifier-access-http, June 2022. 452 [IDENTIFIER-SECURITY] 453 Ma, C., "Security Services for the Industrial Internet 454 Identifier Data Access Protocol (IIIDAP)", Work in 455 Progress, draft-mcd-identifier-access-security, June 2022. 457 [IDENTIFIER-RESPONSES] 458 Ma, C., "JSON Responses for the Industrial Internet 459 Identifier Data Access Protocol (IIIDAP)", Work in 460 Progress, draft-mcd-identifier-access-responce, June 2022. 462 [IDENTIFIER-AUTHORIZATION] 463 Ma, C., "Finding the Authoritative Industrial Internet 464 Identifier Data (IIIDAP) Service", Work in Progress, 465 draft-mcd-identifier-access-authority, June 2022. 467 Authors' Addresses 469 Chendi Ma 470 CAICT 471 No.52 Huayuan North Road, Haidian District 472 Beijing, Beijing, 100191 473 China 475 Phone: +86 177 1090 9864 476 Email: machendi@caict.ac.cn 478 Chen Jian 479 CAICT 480 No.52 Huayuan North Road, Haidian District 481 Beijing, Beijing, 100191 482 China 484 Phone: +86 138 1103 3332 485 Email: chenjian3@caict.ac.cn 487 Xiaotian Fan 488 CAICT 489 No.52 Huayuan North Road, Haidian District 490 Beijing, Beijing, 100191 491 China 493 Phone: +86 134 0108 6945 494 Email: fanxiaotian@caict.ac.cn 496 Meilan Chen 497 CAICT 498 No.52 Huayuan North Road, Haidian District 499 Beijing, Beijing, 100191 500 China 502 Phone: +86 139 1143 7301 503 Email: chenmeilan@caict.ac.cn 504 Zhiping Li 505 CAICT 506 No.52 Huayuan North Road, Haidian District 507 Beijing, Beijing, 100191 508 China 510 Phone: +86 185 1107 1386 511 Email: lizhiping@caict.ac.cn