idnits 2.17.1 draft-ietf-wnils-whois-arch-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 43 longer pages, the longest (page 2) being 65 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 44 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** 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.) ** There are 111 instances of too long lines in the document, the longest one being 9 characters in excess of 72. ** The abstract seems to contain references ([Weider94]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. == There are 29 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (25 July 1994) is 10868 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'Weider94' on line 1934 looks like a reference -- Missing reference section? 'HARR85' on line 1910 looks like a reference -- Missing reference section? 'Weider93' on line 103 looks like a reference -- Missing reference section? 'IAFA1' on line 1916 looks like a reference -- Missing reference section? 'IAFA' on line 1913 looks like a reference -- Missing reference section? 'NIR' on line 1929 looks like a reference -- Missing reference section? 'IIIR' on line 1920 looks like a reference -- Missing reference section? 'BORE93' on line 1905 looks like a reference -- Missing reference section? 'MOOR93' on line 1925 looks like a reference -- Missing reference section? 'POST82' on line 1931 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 5 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Peter Deutsch 2 INTERNET-DRAFT BUNYIP INFORMATION SYSTEMS, inc 3 Rickard Schoultz 4 Expires: 25 January 95 KTHNOC 5 Patrik Faltstrom 6 KTH 7 Chris Weider 8 BUNYIP INFORMATION SYSTEMS, inc 10 25 July 1994 12 Architecture of the WHOIS++ service 14 STATUS OF THIS MEMO 16 This document is an Internet-Draft. Internet-Drafts are working 17 documents of the Internet Engineering Task Force (IETF), its areas, 18 and its working groups. Note that other groups may also distribute 19 working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other 23 documents at any time. It is inappropriate to use Internet- Drafts 24 as reference material or to cite them other than as ``work in 25 progress.'' 27 To learn the current status of any Internet-Draft, please check the 28 ``1id-abstracts.txt'' listing contained in the Internet- Drafts 29 Shadow Directories on ds.internic.net (US East Coast), 30 nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or 31 munnari.oz.au (Pacific Rim). 33 Abstract 35 This document describes WHOIS++, an extension to the trivial WHOIS 36 service described in RFC 954 to permit WHOIS-like servers to make 37 available more structured information to the Internet. We describe 38 an extension to the simple WHOIS data model and query protocol and 39 a companion extensible, distributed indexing service. A number of 40 options have also been added such as the use of multiple languages 41 and character sets, more advanced search expressions, structured 42 data and a number of other useful features. An optional authenti- 43 cation mechanism for protecting all or part of the associated 44 WHOIS++ information database from unauthorized access is also 45 described. 47 The additional architectural issues and commands added to support 48 the distributed indexing service are described in [Weider94]. This 49 present document should be read in conjunction with the additional 50 reference. 52 ^L 54 1. 55 Part I - WHOIS++ Overview 57 1.1. Purpose and Motivation 59 The current NIC WHOIS service [HARR85] is used to provide a very 60 limited directory service, serving information about a small number 61 of Internet users registered with the DDN NIC. Over time the basic 62 service has been expanded to serve additional information and simi- 63 lar services have also been set up on other hosts. Unfortunately, 64 these additions and extensions have been done in an ad hoc and 65 uncoordinated manner. 67 The basic WHOIS information model represents each individual record 68 as a Rolodex-like collection of text. Each record has a unique 69 identifier (or handle), but otherwise is assumed to have little 70 structure. The current service allows users to issue searches for 71 individual strings within individual records, as well as searches 72 for individual record handles using a very simple query-response 73 protocol. 75 Despite its utility, the current NIC WHOIS service cannot function 76 as a general White Pages service for the entire Internet. Given the 77 inability of a single server to offer guaranteed response or relia- 78 bility, the huge volume of traffic that a full scale directory ser- 79 vice will generate and the potentially huge number of users of such 80 a service, such a trivial architecture is obviously unsuitable for 81 the current Internet's needs for information services. 83 This document describes the architecture and protocol for WHOIS++, 84 a simple, distributed and extensible information lookup service 85 based upon a small set of extensions to the original WHOIS informa- 86 tion model. These extensions allow the new service to address the 87 community's needs for a simple directory service, yet the extensi- 88 ble architecture is expected to also allow it to find application 89 in a number of other information service areas. 91 Added features include an extension to the trivial WHOIS data model 92 and query protocol and a companion extensible, distributed indexing 93 service. A number of other options have also been added, like 94 boolean operators, more powerful search constraints and search 95 methods and most specificly structured the data to make both the 96 client and the server part of the dialogue more stringent and 97 parseable. An optional authentication mechanism for protecting all 98 or parts of the associated WHOIS++ information database from unau- 99 thorized access is also briefly described. 101 The additional architectural issues and commands added to support 102 an optional distributed indexing service are described in 103 [Weider93]. This present document should be read in conjunction 104 with the additional reference. 106 ^L 107 The basic architecture of WHOIS++ allows distributed maintenance of 108 the directory contents and the use of the WHOIS++ indexing service 109 for locating additional WHOIS servers. Although a general overview 110 of this service is included for completeness, the reader is 111 referred to [Weider94] for full details of the indexing extensions. 113 1.2. Basic Information Model 115 Our extensions to the existing WHOIS service are centered upon a 116 recommendation to structure user information around a series of 117 standardized information templates, such as to those described by 118 [IAFA1]. Such templates consist of ordered sets of data elements 119 (or attribute-value pairs) and a number of groups at the IETF are 120 now working on standardizing their format and content [IAFA], 121 [NIR]. 123 It is intended that adding such structured templates to a server 124 and subsequently identifying and searching them be simple tasks. 125 The creation and use of customized templates should also be possi- 126 ble with little effort, although their use should be discouraged 127 where appropriate standardized templates exist. 129 We also offer a set of extensions to the trivial protocol described 130 in RFC954 [HARR85] to allow the user to constrain searches to 131 desired attributes or template types, in addition to the existing 132 commands for specifying handles or simple strings. 134 It is expected that the minimalist approach we have taken will find 135 application where the high cost of configuring and operating tradi- 136 tional White Pages services can not currently be justified. 138 Also note that the new architecture makes no assumptions about the 139 search and retrieval mechanisms used within individual servers. 140 Operators are free to use dedicated database formats, fast indexing 141 software or even provide gateways to other directory services to 142 store and retrieve information, if desired. 144 The WHOIS++ server simply functions as a known front end, offering 145 a simple data model and communicating through a well known port and 146 query protocol. The format of both queries and replies has been 147 structured to allow the use of client software for generating 148 searches and displaying the results. At the same time, some effort 149 has been made to keep responses at least to some degree readible by 150 humans, to ensure low entry cost and to ease debugging. 152 The actual implemention details of of an individual WHOIS search 153 engine are left to the imagination of the implementor and it is 154 hoped that the simple, extensible approach taken will encourage 155 experimentation and the development of improved search engines. 157 ^L 159 1.2.1. Changes to the current WHOIS Model 161 The current WHOIS service is based upon an extremely simple data 162 model. The NIC WHOIS database consists of a series of individual 163 records, each of which is identified by a single unique identifer 164 (the "handle"). Each record contains one or more lines of informa- 165 tion. Currently, there is no structure or implicit ordering of this 166 information, although by implication each record is concerned with 167 information about a single user or service. 169 We have implemented two basic changes to this model. First, we have 170 structured the information within the database as collections of 171 data elements, or simple attribute/value pairs. Each individual 172 record contains a specified ordered set of these data elements. 174 Secondly, we have introduced typing of the database records. In 175 effect, each record is based upon one of a specified set of tem- 176 plates, each containing a finite and specified number of data ele- 177 ments. This allow users to easily limit searches to specific col- 178 lections of information, such as information about users, services, 179 abstracts of papers, descriptions of software, and so on. 181 As a final extension, we require that each individual WHOIS++ data- 182 base on the Internet be assigned a unique handle, analogous to the 183 handle associated with each database record. 185 The WHOIS++ database structure is shown in Fig. 1. 187 1.2.2. Registering WHOIS++ servers 189 We propose that individual database handles be registered through 190 the Internet Assigned Numbers Authority (the IANA), ensuring their 191 uniqueness. This will allow us to specify each WHOIS++ entry on the 192 Internet as a server handle and a unique record handle pair. This 193 pair is called the ``composed handle''. 195 A unique registered handle is preferable to using the host's IP 196 address, since it is conceivable that the WHOIS++ server for a par- 197 ticular domain may move over time. If we preserve the unique 198 WHOIS++ handle in such cases we have the option of using it for 199 resource discovery and networked information retrieval (see [IIIR] 200 for a discussion of resource and discovery and support issues). 201 There are many ways of guaranteeing uniqueness of server handles; 202 we will discuss them in a separate paper. 204 We believe that organizing information around a series of such tem- 205 plates will make it easier for administrators to gather and main- 206 tain this information and thus encourage them to make such informa- 207 tion available. At the same time, as users become more familiar 208 with the data elements available within specific templates they 209 will be better able to specify their searches, leading to a more 210 useful service. 212 ^L 214 ______________________________________________________________________ 215 | | 216 | + Single unique WHOIS++ database handle | 217 | | 218 | _______ _______ _______ | 219 | handle3 |.. .. | handle6 |.. .. | handle9 |.. .. | | 220 | _______ | _______ | _______ | | 221 | handle2 |.. .. | handle5 |.. .. | handle8 |.. .. | | 222 | _______ | _______ | _______ | | 223 | handle1 |.. .. | handle4 |.. .. | handle7 |.. .. | | 224 | |.. .. | |.. .. | |.. .. | | 225 | ------- ------- ------- | 226 | Template Template Template | 227 | Type 1 Type 2 Type 3 | 228 | | 229 | | 230 | | 231 | | 232 | Fig.1 - Structure of a WHOIS++ database. | 233 | | 234 | Notes: - Entire database is identified by a single unique WHOIS | 235 | handle. | 236 | - Each record has a single unique handle and a specific set | 237 | of attributes, determined by the template type used. | 238 | - Each value associated with an attribute can be any ASCII | 239 | string up to a specified length. | 240 |______________________________________________________________________| 242 1.2.3. The WHOIS++ Search Selection Mechanism 244 The WHOIS++ search mechanism is intended to be extremely simple. A 245 search command consists of one or more search terms, with an 246 optional nvset of global constraints (specifiers that modify or 247 control a search). 249 Search terms allow the user to specify template type, attribute, 250 value or handle that any record returns must satisfy. Each search 251 term can have an optional set of local constraints that apply to 252 only that term. 254 A WHOIS++ database may be seen as a single rolodex-like collection 255 of typed records. Each term specifies a further constraint that 256 the selected set of output records must satisfy. Each term may thus 257 be thought of as performing a subtractive selection, in the sense 258 that any record that does not fulfill the term is discarded from 259 the result set. Boolean searches are possible by the use of AND, 260 OR, NOT and parenthesis. 262 ^L 264 1.2.4. The WHOIS++ Architecture 266 The WHOIS++ directory service has an architecture which is 267 separated into two components; the base level server, which is 268 described in this paper, and a indexing server, which is described 269 in [Weider94]. A single physical server can act as both a base 270 level server and an indexing server. 272 A base level server is one which contains only filled templates. An 273 indexing server is one which contains forward knowledge (q.v.) and 274 pointers to other indexing servers or base level servers. 276 1.3. Indexing in WHOIS++ 278 Indexing in WHOIS++ is used to tie together many base level servers 279 and index servers into a unified directory service. 281 Each base level server and index server which wishes to participate 282 in the unified directory service must generate "forward knowledge" 283 for the entries it contains. One type of forward knowledge is the 284 "centroid", discussed in [Weider94]. 286 An example of a centroid is as follows: if a whois++ server con- 287 tained exactly three records, as follows: 289 Record 1 Record 2 290 Template: Person Template: Person 291 First-Name: John First-Name: Joe 292 Last-Name: Smith Last-Name: Smith 293 Favourite-Drink: Labatt Beer Favourite-Drink: Molson Beer 295 Record 3 296 Template: Domain 297 Domain-Name: foo.edu 298 Contact-Name: Mike Foobar 300 the centroid for this server would be 302 Template: Person 303 First-Name: Joe 304 John 305 Last-Name: Smith 306 Favourite-Drink:Beer 307 Labatt 308 Molson 310 Template: Domain 311 Domain-Name: foo.edu 312 Contact-Name: Mike 313 Foobar 315 ^L 317 An index server would then collect this centroid for this server as 318 forward knowledge. 320 Index servers can collect forward knowledge for any servers it 321 wishes. In effect, all of the servers that the index server knows 322 about can be searched with a single query to the index server; the 323 index server holds the forward knowledge along with pointers to the 324 servers it indexes, and can refer the query to servers which might 325 hold information which satisfies the query. 327 Implementors of this protocol are strongly encouraged to incor- 328 porate centroid generation abilities into their servers, and to 329 read [Weider94] carefully. 331 ------------------------------------------------------------------- 333 ____ ____ 334 top level | | | | 335 whois index | | | | 336 servers ---- ---- 338 ____ ____ 339 first level | | | | 340 whois index | | | | 341 servers ---- ---- 343 ____ ____ ____ 344 individual | | | | | | 345 whois servers | | | | | | 346 ---- ---- ---- 348 Fig. 2 - Indexing system architecture. 350 ------------------------------------------------------------------- 352 1.4. Getting Help 354 Another extension to the basic WHOIS service is the requirement 355 that all servers support at least a minimal set of help commands, 356 allowing users to find out information about both the individual 357 server and the entire WHOIS++ service itself. This is done in the 358 context of the new extended information model by defining two 359 specific template formats and requiring each server to offer at 360 least one example of each record using these formats. The operator 361 of each WHOIS service is therefor expected to have, as a minimum, a 362 single example of SERVICES and HELP records, which can be accessed 363 through appropriate commands. 365 ^L 367 1.4.1. Minimum HELP Required 369 Executing the command: 371 DESCRIBE 373 gives a brief information about the WHOIS++ server. 375 Executing the command: 377 HELP 379 gives a brief description of the WHOIS++ service itself. 381 The text of both required helped records should contain pointers to 382 additional help subjects that are available. 384 Executing the command: 386 HELP 388 may give information on any topic. 390 1.5. Options and Constraints 392 The WHOIS++ service is based upon a minimal core set of commands 393 and controlling constraints. A small set of additional optional 394 commands and constraints can be supported. These would allow users 395 to perform such tasks as provide security options, modify the 396 information contents of a server or add multilingual support. The 397 required set of WHOIS++ commands are summarized in section 2.2. 398 WHOIS++ constraints are described in section 2.4. Optional commands 399 and constraints are described in section 2.5. 401 1.6. Formatting Responses 403 The output returned by a WHOIS++ server is structured to allow 404 machine parsing and automated handling. Of particular interest in 405 the ability to return summary information about a search (without 406 having to return the entire results) and the ability to encode 407 graphics and other information, using the MIME message encoding 408 format. 410 All output of searches will be returned in one of six output for- 411 mats, which will be one of FULL, ABRIDGED, HANDLE, SUMMARY, 412 SERVERS-TO-ASK or MIME. Note that a conforming server is only 413 required to support the first four formats. 415 When available, SERVERS-TO-ASK format is used to indicate that a 417 ^L 418 search cannot be completed but that one or more alternative WHOIS++ 419 servers may be able to perform the search. 421 When available, MIME format is used to encode output in MIME format 422 [BORE93] and [MOOR93]. This allows the response to include attri- 423 bute values in different character sets. 425 Details of each output format are specified in section 2.5. 427 1.7. Reporting Warnings and Errors 429 The formatted response of WHOIS++ commands allows the encoding of 430 warning or error messages to simplify parsing and machine handling. 431 The syntax of output formats are described in detail in section 432 2.5, and details of WHOIS++ warnings and error conditions are given 433 in section appendix E. 435 All system messages are numerical, but can be tagged with text. It 436 is the clients decision if the text is presented to the user. 438 1.8. Privacy and Security Issues 440 The basic WHOIS++ service was conceived as a simple, unauthenti- 441 cated information lookup service, but there are occasions when 442 authentication mechanisms are required. To handle such cases, an 443 optional mechanism is provided for authenticating each WHOIS++ 444 transaction. 446 The current identified authentication mechanism is PASSWORD, which 447 uses simple password authentication. Any other scheme name used 448 must begin with the characters "X-" and should thus be regarded as 449 experimental and non-standard. 451 Note that the WHOIS++ authentication mechanism does not dictate the 452 actual authentication scheme used, it merely provides a framework 453 for indicating that a particular transaction is to be authenti- 454 cated, and the appropriate mechanisms to use. This mechanism is 455 extensible and individual implementors are free to add additional 456 mechanisms. 458 This document includes a very simple authentication scheme where a 459 combination of username and password is sent together with the 460 search string so the server can verify that the user have access to 461 the information. Note that this is NOT by any means a method recom- 462 mended to secure the data itself because both password and informa- 463 tion are tranferred unencrypted over the network. 465 Given the unauthenticated nature that default services like white 466 pages services are, it is easy to either forget the implications of 467 this and just show all data to the public Internet, or think that 469 ^L 470 Internet is so dangerous that information is hidden from the Inter- 471 net so the whole idea of a global whitepages service is lost. 472 Therefore the type of authentication scheme selected and the public 473 nature of the Internet environment must still be taken into con- 474 sideration when assessing the security and authentication of the 475 information served. 477 A more detailed exposition on security is outside the scope of this 478 document. 480 ^L 482 2. Part II - WHOIS++ Implementation 484 2.1. Introduction 486 The WHOIS++ protocol specifies the interactions between a WHOIS 487 client and a WHOIS server supporting the WHOIS++ extensions. These 488 extensions are designed to be backwards compatible with existing 489 servers, in the sense that a new server receiving any of the older 490 commands specified in RFC 954 [HARR85] will behave in the same 491 manner as the original NIC WHOIS server. 493 Obviously, it is not possible to ensure desired behaviour if one of 494 the extended commands is sent to an older WHOIS server, since the 495 requested functionality is simply not there. Still, it would be 496 possible to query whether the WHOIS++ command set is supported as 497 an attribute for each WHOIS server in an appropriate services 498 registry (which itself could be set up using a WHOIS++ server). 499 Thus, in practice this should not be a problem. In addition, any 500 such command sent to an older WHOIS server would simply be treated 501 as a search term, and thus no harm should result. 503 The small number of older servers, and the probability that at 504 least some of the older servers will be converted to WHOIS++ as 505 implementations become available, means that backwards compatibil- 506 ity is not expected to be a problem in practice. 508 2.1.1. The WHOIS++ interaction model 510 A WHOIS++ server will normally listen for a TCP connections on the 511 allocated WHOIS port (port 43) (although a WHOIS++ server can be 512 accessed over any TCP connection). Once a connection is esta- 513 blished, the server issues a banner message, then listens for 514 input. The command specified in this input is processed and the 515 results returned including an ending system message. If the 516 optional HOLD constraint has not been specified the connection is 517 then terminated. 519 If the server supports the optional HOLD constraint, and this con- 520 straint is specified as part of any command, the server continues 521 to listen on the connection for another line of input. This cycle 522 continues as long as the sender continues to append the required 523 HOLD constraint to each subsequent command. 525 At the same time, each server is permitted to set an optional 526 timeout value (which should be indicated in the response to the 527 CONSTRAINTS command). If set, the server is free to terminate an 528 idle connection at any time after this delay has passed with no 529 input from the client. If the server terminates the connection due 530 to timeout, it will be indicated by the system message. The timeout 531 value is not changeable by the client. 533 ^L 535 2.2. The WHOIS++ Command set 537 There are two types of WHOIS++ commands - system commands and the 538 WHOIS++ search command. 540 The WHOIS++ command set consists of a core set of required systems 541 commands, a single required search command and an set of optional 542 system commands which support features that are not required by all 543 servers. The set of required WHOIS++ system commands are listed in 544 Table I. Details of the allowable search terms for the search com- 545 mand are included in Table II. 547 Each WHOIS++ command also allows the use of one or more controlling 548 constraints, which select can be used to override defaults or oth- 549 erwise modify server behavior. There is a core set of constraints 550 that must be supported by all conforming servers. These include 551 SEARCH (which controls the type of search performed), FORMAT (which 552 determines the output format used) and MAXHITS (which determines 553 the maximum number of matches that a a search can return). These 554 required constraints are summarized in Table III. 556 An additional set of optional constraints are used to provide sup- 557 port for different character sets, indicate the need and type of 558 authentication to perform on a transaction, and permit multiple 559 transactions during a single communications session. These optional 560 constraints are listed in Table IV. 562 It is possible, using the required COMMANDS and CONSTRAINTS system 563 commands, to query any WHOIS++ server for its list of supported 564 commands and constraints. 566 2.2.1. System Commands 568 System commands are commands to the server for information or to 569 control its operation. These include commands to list the template 570 types available from individual servers, to obtain a single blank 571 template of any available type, and commands to obtain the list of 572 valid commands and constraints supported on a server. 574 There are also commands to obtain the current version of the 575 WHOIS++ protocol supported, to access a simple help subsystem, to 576 obtain a brief description of the service (which is intended, among 577 other things, to support the automated registration of the service 578 by yellow pages directory services). All of these commands are 579 required from a conforming WHOIS++ server. 581 ------------------------------------------------------------------------ 583 Short Long Form Functionality 584 ----- --------- ------------- 585 COMMANDS [ ':' HOLD ] list valid WHOIS++ commands 587 ^L 588 supported by this server 590 CONSTRAINTS [ ':' HOLD ] List valid constraints 591 supported by this server 593 DESCRIBE [ ':' HOLD ] Describe this server, 594 formating the response using 595 the standard IAFA "Services" 596 template 598 '?' HELP [ [':' ]] System help, using standard 599 IAFA "Help" template 601 LIST [ [':' ]] List templates supported 602 by this system 604 POLLED-BY [ ':' HOLD ] List indexing servers 605 that are know to track 606 this server 608 POLLED-FOR [ ':' HOLD ] List information about 609 what this server is 610 tracking for 612 SHOW [':' ] Show contents of templates 613 specified 615 VERSION [ ':' HOLD ] return current version of 616 the protocol supported. 618 Table I - Required WHOIS++ SYSTEM commands. 620 ------------------------------------------------------------------------ 622 Below follows a descriptions for each command. Examples of 623 responses to each command is in Appendix C. 625 2.2.1.1. The COMMANDS command 627 The COMMANDS command returns a list of commands that the server 628 supports. The response is formatted as an ABRIDGED response. 630 2.2.1.2. The CONSTRAINTS command 632 The CONSTRAINTS command returns a list of constraints and the 633 values of those that the server supports. The response is formatted 634 as a FULL response, where every constraint is represented as a 635 separate record. The template name for these records is CONSTRAINT. 636 No attention is paid to handles. Each record has, as a minimum, the 638 ^L 639 following two fields: 641 - "Constraint", which contains the attribute name described - 642 "Default", which shows the default value for this constraint. 644 If the client is permitted to change the value of the constraint, 645 there is also: 647 - "Range" field, which contains a list of values that this 648 server supports, as a comma separated list; Or, if the range 649 is numerical, as a pair of numbers separated with a hyphen. 651 2.2.1.3. The DESCRIBE command 653 This is equivalent to issuing the search command on the local 654 server with only the terms "template=services" and 655 "subject=describe" and will result in the display of the 656 corresponding SERVICES template with an attribute of "subject" and 657 value of "describe", except that the DESCRIBE command only searches 658 local information and may not return pointers to other servers. 660 2.2.1.4. The HELP command 662 The HELP command takes an optional argument as subject to get help 663 for. This is equivalent to issuing the search command on the local 664 server only with the terms "template=help and subject=" 665 (or "subject=help" if no argument specified) and will result in the 666 display of the corresponding HELP template with subject "help". 667 The HELP command differs from the above search command in that the 668 HELP command only searches local information and may not return 669 pointers to other servers. 671 2.2.1.5. The LIST command 673 The LIST command returns the name of the templates available on the 674 server. The answer is in ABRIDGED format with the template name as 675 the first word on each line. 677 2.2.1.6. The POLLED-BY command 679 The POLLED-BY command returns a list of servers and the templates 680 and attribute names that those server polled as centroids from this 681 server. The format is in FULL format with two attributes, Template 682 and Field. Each of these is a list of names of the templates or 683 fields polled. 685 ^L 687 2.2.1.7. The POLLED-FOR command 689 The POLLED-FOR command returns a list of servers that this server 690 has polled, and the template and attribute names for each of those. 691 The answer is in FULL format with two attributes, Template and 692 Field. 694 2.2.1.8. The SHOW command 696 The SHOW command takes a template name as argument and returns 697 information about a specific template, formatted as a FULL 698 response. The answer is formatted as a blank template with the 699 requested name. 701 2.2.1.9. The VERSION command 703 This is equivalent to issuing the search command on the local 704 server only with the terms "template=version" and will result in 705 the display of the VERSION template, except that the VERSION com- 706 mand only searches local information and may not return pointers to 707 other servers. 709 The output format is a FULL response containg a record with tem- 710 plate name VERSION. The handle for this record is unspecified. The 711 record must have attribute name "Version", which value is "1.0" for 712 this version of the protocol. The record may also have the addi- 713 tional fields "Program-Name" and "Program-Version" which gives 714 information about the server implementation if the server so 715 desires. 717 2.2.2. The Search Command 719 A search command consists of one or more search terms, which might 720 each have local constraints, followed by an optional colon with a 721 set of global search constraints. 723 Each attribute value in the WHOIS++ database is divided into one or 724 more words separated by whitespace. Each search term operates on 725 every word in the attribute value. 727 Two or more search terms may be combined with boolean operators 728 AND, OR or NOT (other than the implied AND between terms). The 729 operator AND has higher precedence than the operator OR, but this 730 can be changed by the use of parentheses. 732 Search constraints that apply to every search term are specified as 733 global constraints. Local constraints override global constraints 734 for the search term they are bound to. The search terms and the 736 ^L 737 global constraints are separated with a colon (':'). Additional 738 global constraints are appended to the end of the search command 739 delimited with a semicolon ';'. 741 If different search constraints can not be fulfilled, or the combi- 742 nation of different search constraints is uncombinable, the server 743 may choose to ignore some constraints, but still do the search and 744 return some records. 746 The set of required constraints are summarized in Table III. The 747 set of optional constraints are summarized in Table IV. 749 As an option, the server may accept specifications for attributes 750 for either inclusion or exclusion from a reply. Thus, users could 751 specify _only_ those attributes to return, or specific attributes 752 to filter out, thus creating custom views. 754 2.2.2.1. Format of a Search Term 756 Each search term consists of one of the following: 758 1) A search string, followed by an optional comma and set of 759 comma-separated local constraints. 761 2) A search term specifier (as listed in Table II), followed by '=', 762 followed by a search string, an optional comma and a set of 763 comma-separate local constraints. 765 3) An abbreviated search term specifier, followed by a search 766 string, followed by an optional comma and set of comma-separate 767 local constraints. 769 4) A combination of attribute name, followed by '=', followed by a 770 search string, followed by an optional comma and set of 771 comma-separate local constraints. 773 If no term identifier is provided, then the search will be applied 774 to attribute values only. This corresponds to an identifier of 775 VALUE. 777 If a HANDLE specifier is used then the search term can specify 778 either a composed handle or a record handle. The server is respon- 779 sible for resolving the composed handle to a server handle and a 780 record handle. 782 If a SEARCH-ALL specifier is used then the search will be applied 783 to all template names, handles, attribute names and attribute 784 values. 786 When the user specifies the search term using the form: 788 ^L 789 " = " 791 this is considered to be an ATTRIBUTE-VALUE search. 793 For discussion of the system reply format, and selecting the 794 appropriate reply format, see section 2.5. 796 ---------------------------------------------------------------------- 798 Valid specifiers: 799 ----------------- 801 Name Functionality 802 ---- ------------- 804 ATTRIBUTE-VALUE [ ',' ]* allows combining attribute and 805 value specifiers in one term. 806 HANDLE [ ',' ]* Confine search to handles. 807 SEARCH-ALL [ ',' ]* Search everything. 808 TEMPLATE [ ',' ]* Confine search to template names. 809 VALUE [ ',' ]* Confine search to attribute values. 810 This is the default. 812 (Note: The name HANDLE can be replaced with the shortname '!') 814 Acceptable forms of a search specifier: 815 --------------------------------------- 817 1) [',' ]* 819 2) = [',' ]* 821 3) [',' ]* 823 4) = [',' ]* 825 (Note: A is a name of a valid local constraint.) 827 Table II - Valid search command term specifiers. 829 ---------------------------------------------------------------------- 831 2.2.2.2. Format of a Search String 833 Special characters that need to be quoted are preceeded by a 834 backslash, '\'. 836 Special characters are space ' ', tab, equal sign '=', comma ',', 837 colon ':', backslash '\', semicolon ';', asterisk '*', period '.', 838 parenthesis '()', square brackets '[]', dollar sign '$' and circum- 839 flex '^'. 841 ^L 842 If the search term is given in some other character set than ISO- 843 8859-1, it must be specified by the constraint INCHARSET. 845 2.3. WHOIS++ Constraints 847 Constraints are intended to be hints or recommendations to the 848 server about how to process a command. They may also be used to 849 override default behaviour, such as requesting that a server not 850 drop the connection after performing a command. 852 Thus, a user might specify a search constraint as "SEARCH=exact", 853 which means that the search engine is to perform an exact match 854 search. It might also specify "LANGUAGE=Fr", which implies that the 855 server should use French in fuzzy matches. It might also be able to 856 issue system messages in French. 858 In general, contraints take the form "=", 859 with being one of a specified set of valid values. The not- 860 able exception is "HOLD", which takes no argument. 862 All constraints can be used as a global constraint, but only a few 863 can be used as local. See tables IV and V for information of which 864 constraints can be local. 866 The CONSTRAINTS system command is used to list the search con- 867 straints supported by an individual server. 869 If a server cannot satisfy the specified constraint there will be a 870 mechanism for informing the user in the reply, using system mes- 871 sages. In such cases, the search is still performed, with the the 872 server ignoring unsupported constraints. 874 2.3.1. Required Constraints 876 The following CONSTRAINTS must be supported in all conforming 877 WHOIS++ servers. 879 ^L 880 ------------------------------------------------------------------ 882 Format LOCAL/GLOBAL 883 ------ ------------- 885 SEARCH= {exact | lstring } LOCAL/GLOBAL 887 FORMAT= {full | abridged | handle | summary } GLOBAL 889 MAXHITS= { 1- } GLOBAL 891 Table III - Required WHOIS++ constraints. 893 ------------------------------------------------------------------ 895 2.3.2. Optional CONSTRAINTS 897 The following CONSTRAINTS and constraint values are not required of 898 a conforming WHOIS++ server, but may be supported. If supported, 899 their names and supported values must be returned in the response 900 to the CONSTRAINTS command. 902 ^L 903 --------------------------------------------------------------------- 905 Format LOCAL/GLOBAL 906 ------ ------------- 908 SEARCH= { regex | fuzzy | substring | } LOCAL/GLOBAL 910 CASE= { ignore | consider } LOCAL/GLOBAL 912 FORMAT= { servers-to-ask | mime | } GLOBAL 914 MAXFULL= { 1- } GLOBAL 916 AUTHENTICATE= password GLOBAL 918 NAME= GLOBAL 920 PASSWORD= GLOBAL 922 INCHARSET= { us-ascii | iso-8859-* } GLOBAL 924 LANGUAGE= GLOBAL 926 HOLD GLOBAL 928 IGNORE= {attributelist} GLOBAL 930 INCLUDE= {attributelist} GLOBAL 932 Table IV - Optional WHOIS++ constraints. 934 ---------------------------------------------------------------------- 936 2.3.2.1. The SEARCH Constraint 938 The SEARCH constraint is used for specifying the method that is to 939 be used for the search. The default method is "exact". Following is 940 a definition of each search method. 942 exact The search will succeed for a word that exactly 943 matches the search string. 945 substring The search will succeed for a word that matches 946 a part of a word. 948 regex The search will succeed for a word when a regular 949 expression matches the searched data. Regular 950 expression is built up by using constructions of 951 '*', '.', '^', '$', and '[]'. For use of 952 regular expressions see Appendix G. 954 ^L 956 fuzzy The search will succeed for words that matches the 957 search string by using an algorithm designed to catch 958 closely related names with different spelling, e.g. 959 names with the same pronounciation. The server 960 chooses which algorithm to use, but it may vary 961 depending on template name, attribute name and 962 language used (see Constraint Language above). 964 lstring The search will succed for words that begins 965 with the search string. 967 2.3.2.2. The FORMAT Constraint 969 The FORMAT constraint describes what format the result will be in. 970 Default format is FULL. For a description of each format, see 971 Server Response Modes below. 973 2.3.2.3. The MAXFULL Constraint 975 The MAXFULL constraint sets the limit of the number of matching 976 records the server allows before it enforces SUMMARY responses. 977 The client may attempt to override this value by specifying another 978 value to that constraint. Example: If, for privacy reasons, the 979 server will return the response in SUMMARY format if the number of 980 hits exceeds 2, the MAXFULL constraint is set to 2 by the server. 982 Regardless of what format the client did or did not ask for, the 983 server will change the response format to SUMMARY when the number 984 of matching records equals or exceeds this value. 986 2.3.2.4. The MAXHITS Constraint 988 The MAXHITS constraint sets the maximum number of records the 989 client can get in a search respone. 991 2.3.2.5. The CASE Constraint 993 The CASE constraint defines if the search should be done case sen- 994 sistive or not. Default value is to have case ignored. 996 2.3.2.6. The AUTHENTICATE Constraint 998 The AUTHENTICATE constraint describes which authentication method 1000 ^L 1001 to use when executing the search. By using a specific authentica- 1002 tion method, some other constraints might be needed which is speci- 1003 fied by the authentication method. 1005 The only authentication method described in this document is "pass- 1006 word", if used, also the two other constraints "name" and "pass- 1007 word" need to be set. 1009 2.3.2.7. The USER Constraint 1011 The USER constraint is only used together with some authentication 1012 method named by the constraint "authenticate". The only use 1013 described in this document is by sending a username as a string of 1014 characters which together with the string given as an argument to 1015 the "password" constraint is sent to the server. The server can use 1016 that pair of strings to do a simple authentication check, like the 1017 UNIX login program do. 1019 2.3.2.8. The PASSWORD Constraint 1021 The PASSWORD constraint is only used together with some authentica- 1022 tion method named by the constraint "authenticate". The only use 1023 described in this document is by sending a password as a string of 1024 characters which together with the string given as an argument to 1025 the "user" constraint is sent to the server. The server can use 1026 that pair of strings to do a simple authentication check, like the 1027 UNIX login program do. 1029 2.3.2.9. The LANGUAGE Constraint 1031 The LANGUAGE constraints can be used as an extra information to the 1032 fuzzy matching search method, and it might also be used to tell the 1033 server to give the system responses in another language, although 1034 this ability should be handled by the client. The two-letter 1035 language code defined in ISO 639:1988 can be used as a value for 1036 the language constraint. In these, the case of the letters are 1037 insignigicant. Other language codes shall be interpreted according 1038 to the Internet standard for language codes in RFC 822/MIME mes- 1039 sages, if and when such a standard is adopted. 1041 2.3.2.10. The INCHARSET Constraint 1043 The INCHARSET constraint tells the server in which character set 1044 the search string itself is given in. The default character set is 1045 "ISO-8859-1". 1047 ^L 1049 2.3.2.11. The IGNORE Constraint 1051 The IGNORE constraint specifies which attributes to NOT include in 1052 the result. All other attributes will be included (as if named 1053 explicitly by the "include" constraint). 1055 If an attribute is named both with the "include" and "ignore" con- 1056 straint, the attribute is to be included in the result, but the 1057 system message must be "% 205 Requested constraint not fulfilled". 1059 2.3.2.12. The INCLUDE Constraint 1061 The INCLUDE constraint specifies which attributes to include in the 1062 result. All other attributes will be excluded (as if named expli- 1063 citly by the "ignore" constraint). 1065 If an attribute is named both with the "include" and "ignore" con- 1066 straint, the attribute is to be included in the result, but the 1067 system message must be "% 205 Requested constraint not fulfilled". 1069 2.4. Server Response Modes 1071 There are currently a total of six different response modes possi- 1072 ble for WHOIS++ servers. These are FULL, ABRIDGED, HANDLE, SUMMARY, 1073 SERVERS-TO-ASK and MIME. The syntax of each output format is speci- 1074 fied in more detail in the following section. 1076 1) A FULL format response provides the complete contents of each 1077 template matching the specified query, including the template 1078 type and the composed handle for each record. 1080 2) An ABRIDGED format response provides a brief summary, including 1081 (as a minimum) the composed handle and relevant information for 1082 that template. 1084 3) A HANDLE format response returns only a list of handles that 1085 matched the specified query. 1087 4) A SUMMARY response provides only a brief summary of information 1088 the number of matches and the list of template types in which the 1089 matches occured. 1091 5) A SERVERS-TO-ASK response returns only a pointer to another 1092 WHOIS++ server, which might possibly be able to answer the 1093 specified query. 1095 6) A MIME response indicates that the body of the response has been 1096 encoded in MIME message format. 1098 ^L 1100 The server may respond with a null answer and may also respond with 1101 a null answer together with a correct system message to indicate 1102 that the query was too complex. 1104 2.4.1. Default Responses 1106 By default, a WHOIS++ server will provide a FULL response. This may 1107 be changed by the client with the use of the global constraint 1108 "format". 1110 The server is allowed to provide response in SUMMARY format if the 1111 number of hits exceeds the value of the global constraint "max- 1112 full". 1114 The server will not respond with more matches than the value speci- 1115 fied with the global constraint "maxhits"; Not in any response for- 1116 mat. If the number of matches exceeds this value, the server will 1117 issues the system message 110 (maxhits value exceeded), but will 1118 still show the responses, up to the number of the "maxhits" con- 1119 straint value. This mechanism will allow the server to hide the 1120 number of possible matches to a search command. 1122 The server response modes are summarized in Table V. 1124 2.4.2. Format of Responses 1126 Each response consists of a numerical system generated message, 1127 which can be tagged with text, followed by an optional formatted 1128 response message, followed by a second system generated messages. 1130 That is: 1132 '%' 1134 [ ] 1136 '%' 1138 If there are no matches to a query, the system is not required to 1139 generate any output as a formatted response, although it must still 1140 generate system messages. 1142 For information about the format for system messages, see Appendix 1143 E. 1145 ^L 1147 2.4.3. Syntax of a Formatted Response 1149 All formatted responses consist of a START line, followed by a 1150 response-specific section, followed by a TERMINATION line. It is 1151 permissible to insert any number of lines consisting solely of new- 1152 lines within a formatted response to improve readibility. 1154 A START line consists of a line beginning with a '#' in the first 1155 column, followed by one white space character (SPACE or TAB), fol- 1156 lowed by one of the following keywords FULL, ABRIDGED, HANDLE, SUM- 1157 MARY, SERVERS-TO-ASK or MIME. 1159 A START line must contain no more than 81 characters, including the 1160 terminating newline character. 1162 A TERMINATION line consists of a line beginning with a '#' in the 1163 first column, followed by one white space character (SPACE or TAB), 1164 followed by the keyword END, followed by zero or more characters, 1165 followed by a newline. 1167 A TERMINATION line must contain no more than 81 characters, includ- 1168 ing the terminating newline character. 1170 A response-specific section will be one of the following: 1172 1) FULL Format Response 1173 2) ABRIDGED Format Response 1174 3) HANDLE Format Response 1175 4) SUMMARY Format Response 1176 5) SERVERS-TO-ASK Format Response 1177 6) MIME format Response 1179 The details of each are specified in the following sections: 1181 2.4.3.1. A FULL format response 1183 A FULL format response consists of a series of responses, each con- 1184 sisting of a FORMAT specifier line, followed by the complete tem- 1185 plate information for the matching record. 1187 Each FORMAT specifier line consists of a '#' in the first column, 1188 followed by one white space character, the name of the correspond- 1189 ing template type, one white space character, the serverhandle, a 1190 colon, the handle for that record, and a terminating newline. 1192 The template information for each record will be returned as a 1193 series of lines consisting of a single space, followed by the 1194 corresponding line of the record. 1196 ^L 1197 The line of the record shall consist of a single space and the 1198 attribute name, followed by a ':', a single space, the value of 1199 that attribute, and a newline. 1201 Each such line shall be limited to no more than 81 characters, 1202 including the terminating newline. If a line (including the 1203 required leading single space) would exceed 81 characters, it is to 1204 be broken into lines of no more than 81 characters, with each con- 1205 tinuation line beginning with a "+" character in the first column, 1206 instead of the leading space. 1208 If the attribute value includes a line break, the line break must 1209 be replaced by a CR/LF pair and the following line begin with a "-" 1210 character in the first column, instead of the space character. The 1211 attribute name is not repeated on consecutive lines. 1213 2.4.3.2. ABRIDGED Format Response 1215 An ABRIDGED format response consists of a single set of responses, 1216 consisting of a single line excerpt of the template information 1217 from each matching record. The excerpt information shall include, 1218 as a minimum, the composed handle of the record, as well as other 1219 information that is relevant to the template type. 1221 The abridged template information for each record will be returned 1222 as a series of lines, each of which must consist of a single space, 1223 followed by the abridged line of the record, one or more space 1224 characters, the composed handle, and a CR/LF pair. 1226 Each line shall be limited to no more than 81 characters, including 1227 the terminating newline. If a line (including the required single 1228 space, would exceed 81 characters, it is to be broken into lines of 1229 no more than 81 characters, with the remainder following on the 1230 subsequent line, with the space replaced by a "+" character in the 1231 first column. 1233 If the attribute value includes a line break, the line break must 1234 be replaced by a CR/LF pair and the following line begin with a "-" 1235 character in the first column, instead of the space character. The 1236 attribute name is not repeated on consecutive lines. 1238 2.4.3.3. HANDLE Format Response 1240 A HANDLE format response consists of a single set of responses, 1241 consisting of a single line listing the composed handle and tem- 1242 plate type for each matching record. 1244 Each line shall start with one space, followed by the server han- 1245 dle, a colon, the record handle, one or more whitespace characters, 1246 the template type and terminated by a newline. 1248 ^L 1249 Each such line must contain no more than 81 characters, including 1250 the terminating newline character. If a line (including the 1251 required first space) would exceed 81 characters, it shall be split 1252 into multiple lines, with each continuation line beginning with a 1253 '+' instead of a space. 1255 2.4.3.4. SUMMARY Format Response 1257 A SUMMARY format response consists of a single set of responses, 1258 consisting of a line listing the number of matches to the specified 1259 query, followed by a list of all template types which satisfied the 1260 query at least once. 1262 The first line shall begin with the string "matches: ", be followed 1263 by a space and the number of responses to the query and terminated 1264 by a newline. The second line shall begin with the string "tem- 1265 plates: ", be followed by a newline separated list of the name of 1266 the template types which matched the query. Each line following the 1267 first which include the text "templates:" must begin with a '-' 1268 instead of a space. 1270 If the line is longer than 81 characters including the terminating 1271 CR/LF pair, it shall be split into multiple lines with each con- 1272 tinuation line beginning with a '+' instead of a space. 1274 2.4.3.5. MIME Format Response 1276 A MIME format response consists of a MIME encoding of all 1277 responses, each consisting of the data of one matching record. The 1278 result of a search is contained in one MIME message. The MIME mes- 1279 sage itself is indented with one space. Each record is embedded in 1280 the message type text/iafa-template. If the result consists of more 1281 than one record, the message type multipart/mixed is used to 1282 separate the different records from each other. 1284 See RFC-1521 [BORE93] and RFC-1522 [MOOR93] for more information 1285 about the MIME format. 1287 The format of the message type text/iafa-template follows the 1288 specification of the FULL template, as described above. 1290 The MIME message itself must be indented with one space character. 1292 2.4.3.6. SERVERS-TO-ASK Response 1294 A SERVERS-TO-ASK response consists of information to the client 1295 about which servers to contact next to resolve a query. 1297 ^L 1298 The servers-to-ask response will consist of a number of attribute- 1299 value pairs, separated by CRLF. Each line is indented with one 1300 space. 1302 Required attributes are "Version-number", which will be "1.0", and 1303 "Next-Servers". 1305 The "Next-Servers" field will be returned as a series of lines, 1306 each holding pointer information to one server. Consecutive lines 1307 shall have a hyphen "-" in the first column. Each line will be 1308 separated into five fields, separated with a semicolon. Those 1309 fields are: 1311 1. The server handle of the server pointed at. (required) 1312 2. A cached host named for the server pointed at. (optional) 1313 3. A cached port number for the server pointed at. (optional) 1315 Each such line shall be limited to no more than 81 characters, 1316 including the terminating newline. If a line (including the 1317 required leading single space) would exceed 81 characters, it is to 1318 be broken into lines of no more than 81 characters, with each con- 1319 tinuation line beginning with a "+" character in the first column. 1321 2.4.4. System Generated Messages 1323 All system generated messages must begin with a '%' as the first 1324 character, a space as the second one, followed by a three digit 1325 number, a space and an optional text message. The total length of 1326 the line must be no more than 81 characters long, including the 1327 terminating CR LF pair. There is no limit to the number of system 1328 messages that may be generated. 1330 The format for multiline replies requires that every line, except 1331 the last, begin with "%", followed by space, the reply code, a 1332 hyphen, and an optional text. The last line will begin with "%", 1333 followed by space, the reply code, a space and some optional text. 1335 System generated messages displayed before or after the formatted 1336 response section are expected to refer to operation of the system 1337 or refer to the entire query. System generated messages within the 1338 output of an individual record during a FULL reponse are expected 1339 to refer to that record only, and could (for example) be used to 1340 indicate problems with that record of the response. See Appendix E 1341 for a description of system messages. 1343 2.5. Compatibility with Older WHOIS Servers 1345 Note that this format, although potentially more verbose, is still 1346 in a human readible form. Responses from older systems that do not 1347 follow this format are still conformant, since their responses 1349 ^L 1350 would be interpreted as being equivalent to optional text messages, 1351 without a formatted response. Clients written to this specifica- 1352 tion would display the responses as a advisory text message, where 1353 it would still be readible by the user. 1355 3. Miscellaneous 1357 3.1. Acknowledgements 1359 The WHOIS++ effort began as an intensive brainstorming session at 1360 the 24th IETF, in Boston Massachusetts. Present at the birth, and 1361 contributing ideas through this early phase, were (alphabetically) 1362 Peter Deutsch, Alan Emtage, Jim Fullton, Joan Gargano, Brad Passwa- 1363 ters, Simon Spero, and Chris Weider. Others who have since helped 1364 shape this document with feedback and suggestions include Patrik 1365 Faltstrom, Dan Kegel, Mark Prior and Rickard Schoultz. 1367 3.2. Contact information 1369 Peter Deutsch, 1370 BUNYIP INFORMATION SYSTEMS, inc 1371 310 St-Catherine St West, 1372 suite 202, 1373 Montreal, Quebec H2X 2A1 1374 CANADA 1375 1377 Rickard Schoultz, 1378 KTHNOC, SUNET/NORDUnet/Ebone Operations Centre 1379 100 44 STOCKHOLM 1380 SWEDEN 1381 1383 Patrik Faltstrom 1384 KTH/NADA 1385 100 44 STOCKOLM 1386 SWEDEN 1387 1389 Chris Weider 1390 BUNYIP INFORMATION SYSTEMS, inc 1391 2001 S. Huron Parkway, #12 1392 Ann Arbor, MI 48104 1393 USA 1394 1396 ^L 1397 Appendix A - Some Sample Queries 1399 author=chris and template=user 1401 The result will consist of all records where attribute "author" 1402 matches "chris" with case ignored. Only USER templates will be 1403 searched. An example of a matching record is "Author=Chris Weider". 1404 This is the typical case of search. 1406 schoultz and rick;search=lstring 1408 The result will consist of all records which have one attribute 1409 value matching "schoultz" exactly and one having "rick" as leading 1410 substring, both with case ignored. One example is "Name=Rickard 1411 Schoultz". 1413 value=phone;search=substring 1415 The result will consist of all records which have attribute values 1416 matching *phone*, for example the record "Name=Acme telephone 1417 inc.", but will not match the attribute name "phone". (Since 1418 "value" term specifier is the default, the search term could be 1419 "phone" as well as "value=phone".) 1421 search-all=Peter ; search=substring;case=consider 1423 The result will consist of all records which have attribute names, 1424 template names or attribute values matching "Peter" with respect to 1425 case. One example is "Friend-Of-Peter: Yes". 1427 ucdavis;search=substring and (gargano or joan):include=name,email 1429 This search command will find records which have records containing 1430 the words "gargano" or "joan" somewhere in the record, and has the 1431 word "ucdavis" somewhere in a word. The result will only show the 1432 "name" and "email" fields. 1434 ^L 1435 Appendix B - Some sample responses. 1437 1) A FULL format response: 1439 # FULL 1441 # USER SERVHANDLE1:PD45 1442 Name: Peter Deutsch 1443 email: peterd@bunyip.com 1445 # USER SERVHANDLE1:AE1 1446 Name: Alan Emtage 1447 email: bajan@bunyip.com 1449 # USER SERVHANDLE1:NW1 1450 Name: Nick West 1451 Favourite-Bicycle-Forward-Wheel-Brand: New Bicy 1452 +cles Acme Inc. 1453 email: nick@bicycle.acme.com 1454 My-favourite-song: Happy birthday to you! 1455 -Happy birthday to you! 1456 -Happy birthday dear Nick! 1457 -Happy birthday to you. 1459 # SERVICES SERVHANDLE1:WWW1 1460 Type: World Wide Web 1461 Location: the world 1463 # END 1465 -------------------- 1467 2) An ABRIDGED format response: 1469 # ABRIDGED 1471 Peter Deutsch peterd@bunyip.com PD45 1472 Alan Emtage bajan@bunyip.com AE1 1473 World Wide Web the world WWW1 1475 # END 1477 -------------------- 1479 3) A HANDLE format response: 1481 # HANDLE 1483 SERVHANDLE1:PD45 User 1484 SERVHANDLE1:AE1 User 1486 ^L 1487 SERVHANDLE1:WWW1 Services 1489 # END 1491 -------------------- 1493 4) A SUMMARY HANDLE format response: 1495 # SUMMARY 1497 Matches: 175 1498 Templates: User 1499 - Services 1500 - Abstracts 1501 # END 1503 5) A MIME format response: 1505 # MIME 1506 Mime-Version: 1.0 1507 Content-Type: multipart/mixed;boundary=uniqueboundary 1509 --uniqueboundary 1510 Content-Type: text/iafa-template;charset=iso-8859-1;template=user; 1511 handle=nadakthse01:paf01 1512 Content-Transfer-Encoding: quoted-printable 1514 Name: Patrik F=E4ltstr=F6m 1515 Email: paf@nada.kth.se 1517 --uniqueboundary 1518 Content-Type: text/iafa-template;charset=us-ascii;template=user; 1519 handle=sunetse01:risc01 1521 Name: Rickard Schoultz 1522 Email: schoultz@sunet.se 1524 --uniqueboundary- 1525 # END 1527 ^L 1528 Appendix C - Sample responses to system commands 1530 C.1 Response to the LIST command 1532 # ABRIDGED 1533 USER 1534 SERVICES 1535 HELP 1536 # END 1538 C.2 Response to the SHOW command 1540 This example show the result after issuing "show help": 1542 # FULL 1543 # TEMPLATE serverhandle1:user-template 1544 Template-Name: USER 1545 Attribute-Names: Name,Organization-Name,Organization-Type,Work-Phone, 1546 +Work-Fax,Work-Postal,Job-Title,Department,Email,Handle,Home-Phone, 1547 +Home-Postal,Home-Fax 1548 # TEMPLATE serverhandle1:help 1549 Template-Name: HELP 1550 Attribute-Names: Subject,Description,Handle 1551 # END 1553 C.3 Response to the POLLED-BY command 1555 # FULL 1556 # POLLED-BY xyz:serverhandle1 1557 Server-handle: serverhandle1 1558 Cached-Host-Name: sunic.sunet.se 1559 Cached-Host-Port: 7070 1560 Template: user 1561 Field: ALL 1562 # POLLED-BY xyz:serverhandle2 1563 Server-handle: serverhandle2 1564 Cached-Host-Name: kth.se 1565 Cached-Host-Port: 7070 1566 Template: ALL 1567 Field: Name,Email 1568 # END 1570 C.4 Response to the POLLED-FOR command 1572 # FULL 1573 # POLLED-FOR xyz:serverhandle3 1574 Server-Handle: serverhandle3 1575 Template: ALL 1577 ^L 1578 Field: Name,Address,Job-Title,Organization-Name,Organization-Address, 1579 +Organization-Name 1580 # POLLED-FOR xyz:serverhandle4 1581 Server-Handle: serverhandle4 1582 Template: User 1583 Field: ALL 1584 # END 1586 C.5 Response to the VERSION command 1588 # FULL 1589 # VERSION serverhandle:version 1590 Version: 1.0 1591 Program-Name: kth-whoisd 1592 Program-Version: 2.0 1593 # END 1595 C.6 Response to the CONSTRAINTS command 1597 # FULL 1598 # CONSTRAINT asdjkq 1599 Constraint: format 1600 Default: full 1601 Range: full,abridged,summary,handle,mime 1602 # CONSTRAINT ljkqwer 1603 Constraint: maxhits 1604 Default: 200 1605 Range: 1-1000 1606 # CONSTRAINT slkjewer 1607 Constraint: search 1608 Default: exact 1609 Range: exact,substring,lstring 1610 # CONSTRAINT qwewerq 1611 Constraint: maxfull 1612 Default: 20 1613 # END 1615 ^L 1616 Appendix D - Sample whois++ session 1618 Below is an example of a session between a client and a server. The 1619 angle brackets to the left is not part of the communication, but is 1620 just put there to denonte the direction of the communication 1621 between the server or the client. Text appended to '>' means mes- 1622 sages from the server and '<' from the client. 1624 Client connects to the server 1626 >% 220-Welcome to 1627 >% 220-the whois++ server 1628 >% 220 at ACME inc. 1629 % 200 Command okay 1631 > 1632 ># FULL 1633 > 1634 ># USER serverhandle:nw1 1635 > name: Nick West 1636 > email: nick@acme.com 1637 ># END 1638 ># SERVERS-TO-ASK 1639 > Version-number: 1.0 1640 > Next-Servers: sunetse01;whois.sunet.se;7070 1641 >- kthse01 1642 >- anotherserverhandle01;whois.acme.com;7070 1643 ># END 1644 >% 226 Tranfer complete 1645 % 200 Command okay 1647 ># FULL 1648 ># VERSION ignoredserverhandle:version 1649 > Version: 1.0 1650 ># END 1651 >% 226 Tranfer complete 1652 >% 203 Bye 1653 Server closes the connection 1655 In the example above, the client connected to a whois++ server and 1656 queried for all records where the attribute "name" equals "Nick", 1657 and asked the server not to close the connection after the response 1658 by using the global constraint "HOLD". 1660 The server responds with one record and a pointer to three other 1661 servers that either holds records or pointers to other servers. 1662 The first server was polled for "USER" templates and "name" and 1663 "email" fields. 1665 The client continues with asking for servers version number without 1666 using the HOLD constraint. After responding with protocol version, 1667 the server closes the connection. 1669 ^L 1670 Note that each response from the server begins system message 200 1671 (Command OK), and ends with system message 226 (Transfer Complete). 1673 ^L 1674 Appendix E - System messages 1676 A system message begins with a '%', followed by a space and a three 1677 digit number, a space, and an optional text message. The line mes- 1678 sage must be no more than 81 characters long, including the ter- 1679 minating CR LF pair. There is no limit to the number of system mes- 1680 sages that may be generated. 1682 A multiline system message have a hyphen instead of a space in 1683 column 6, immediately after the numeric response code in all lines, 1684 except the last one, where the space is used. 1686 Example 1 1688 % 200 Command okay 1690 Example 2 1692 % 220-Welcome to 1693 % 220-the whois++ server 1694 % 220 at ACME inc. 1696 The client is not expected to parse the text part of the response 1697 message except when receiving reply 600, in which case the text 1698 part is the name of a character set that will be used by the server 1699 in the rest of the response. The valid values for characters sets 1700 is specified in the "characterset" list in the BNF listing in 1701 appendix F. 1703 The theory of reply codes is described in appendix E in RFC 821 1704 [POST82]. 1706 ------------------------------------------------------------------------ 1708 List of system response codes 1709 ------------------------------ 1711 110 Too many hits The number of matches exceeded 1712 the value specified by the 1713 maxhits constraint. Server 1714 will still reply with as many 1715 records as "maxhits" allows. 1717 111 Requested constraint not supported One or more constraints in 1718 query is not implemented, but 1719 the search is still done. 1721 112 Requested constraint not fullfilled One or more constraints in 1722 query has unacceptable value 1723 and was therefore not used, 1724 but the search is still done. 1726 ^L 1728 200 Command Ok Command accepted and executed. 1729 The client must wait for a 1730 transaction end system message. 1732 201 Command Completed successfully Command accepted and executed. 1734 203 Bye Server is closing connection 1736 220 Service Ready Greeting message. Server is 1737 accepting commands. 1739 226 Transaction complete End of data. All responses to 1740 query are sent. 1742 430 Authentication needed Client requested information 1743 that needs authentication. 1745 500 Syntax error 1747 502 Search expression too complicated This message is sent when the 1748 server is not able to resolve 1749 a query (i.e. when a client 1750 sent a regular expression that 1751 is too deeply nested). 1753 530 Authentication failed The authentication phase 1754 failed. 1756 600 Subsequent attribute values are 1757 encoded in the charater set 1758 specified by . 1760 Table V - System response codes 1762 ------------------------------------------------------------------------ 1764 ^L 1765 Appendix F - The WHOIS++ BNF Grammar 1767 whois-command = ( system-command [":" "hold"] 1768 / terms [":" globalcnstrnts] ) NL 1770 system-command = "constraints" 1771 / "describe" 1772 / "commands" 1773 / "polled-by" 1774 / "polled-for" 1775 / "version" 1776 / "list" 1*SP [string] 1777 / "show" 1*SP [string] 1778 / "help" 1*SP [string] 1779 / "?" [string] 1781 terms = and-expr *("or" and-expr) 1783 and-expr = not-expr *("and" not-expr) 1785 not-expr = ["not"] (term / ( "(" terms ")" )) 1787 term = generalterm / specificterm 1788 / shorthandle / combinedterm 1790 generalterm = string *(";" localcnstrnt) 1792 specificterm = specificname "=" string 1793 *(";" localcnstrnt) 1795 specificname = "handle" / "value" 1797 shorthandle = "!" string *(";" localcnstrnt) 1799 combinedterm = string "=" string *(";" localcnstrnt) 1801 globalcnstrnts = globalcnstrnt *(";" globalcnstrnt) 1803 globalcnstrnt = localcnstrnt 1804 / "format" "=" format 1805 / "maxfull" "=" 1*digit 1806 / "maxhits" "=" 1*digit 1807 / opt-globalcnst 1809 opt-globalcnst = "hold" 1810 / "authenticate" "=" auth-method 1811 / "name" "=" string 1812 / "password" "=" string 1813 / "language" "=" language 1814 / "incharset" "=" characterset 1815 / "ignore" "=" string 1816 / "include" "=" string 1818 ^L 1820 format = "full" / "abridged" / "handle" / "summary" 1821 / "servers-to-ask" / "mime" 1823 language = 1831 characterset = "us-ascii" / "iso-8859-1" / "iso-8859-2" / 1832 "iso-8859-3" / "iso-8859-4" / "iso-8859-5" / 1833 "iso-8859-6" / "iso-8859-7" / "iso-8859-8" / 1834 "iso-8859-9" / "iso-8859-10" / charset-value 1836 charset-value = 1*char 1838 localcnstrnt = "search" "=" searchvalue / 1839 "case" "=" casevalue 1841 searchvalue = "exact" / "substring" / "regex" / "fuzzy" 1842 / "lstring" 1844 casevalue = "ignore" / "consider" 1846 auth-method = "password" 1848 string = 0*char 1850 char = "\" specialchar 1851 / 1853 specialchar = " " / / "=" / "," / ":" / ";" / "\" / 1854 "*" / "." / "(" / ")" / "[" / "]" / "^" / 1855 "$" / "!" / "?" 1857 digit = "0" / "1" / "2" / "3" / "4" / 1858 "5" / "6" / "7" / "8" / "9" 1860 NL = 1862 NOTE: Significant blanks must be escaped. The following char- 1863 acters, when significant to the query, may be preceded and/or 1864 followed by a single blank: 1865 : ; , ( ) = ! 1867 ^L 1868 Appendix G - Description of Regular expressions 1870 The regular expressions described in this section is the same 1871 as used in many other applications and operating systems. It 1872 is though very simple and does not include logical operators 1873 AND and OR. 1875 Character Function 1876 --------- -------- 1878 Matches itself 1880 a* Matches zero or more 'a' 1882 [ab] Matches 'a' or 'b' 1884 [a-c] Matches 'a', 'b' or 'c' 1886 ^ Matches beginning of a string 1888 $ Matches end of a string 1890 Examples 1891 --------- 1893 String Matches Matches not 1894 ------- ------- ----------- 1895 hello hello helloo 1896 h.llo hello helio 1897 h.*o hello helloa 1898 h[a-f]llo hello hgllo 1899 ^he.* hello ehello 1900 .*lo$ hello helloo 1902 ^L 1903 References 1905 [BORE93] Borenstein N., and N. Freed, MIME (Multipurpose 1906 Internet Mail Extensions): Mechanisms for Specifying 1907 and Describing the Format of Internet Message Bodies, 1908 RFC 1521, Bellcore, Innosoft, September 1993. 1910 [HARR85] Harrenstein K., Stahl M., Feinler E., NICNAME/WHOIS, 1911 RFC954, SRI, October 1985 1913 [IAFA] Internet Anonymous FTP Archives Working Group (now 1914 closed). 1916 [IAFA1] Emtage A., and Deutsch P.. IAFA (Internet Anonymous 1917 FTP Archives) 1918 (not yet issued, pending some editing...) 1920 [IIIR] Weider C., and Deutsch P., A vision of an integrated 1921 internet information service, Internet Draft, 1922 October, 1993. < URL:ftp://nic.merit.edu/documents/ 1923 internet-drafts/draft-ietf-iiir-vision-02.txt > 1925 [MOOR93] Moore K., MIME (Multipurpose Internet Mail Extenssions) 1926 Part Two: Message Header Extensions for Non-ASCII Text, 1927 RFC 1522, University of Tennessee, September 1993. 1929 [NIR] Network Information Retrieval Working Group. 1931 [POST82] Postel J., Simple Mail Transfer Protocol, RFC 821, 1932 ISI, August 1982. 1934 [Weider94] Weider C., Fullton J., Spero S., Architecture of the 1935 WHOIS++ Index Service: Internet Draft, March, 1994. 1936 < URL:ftp://nic.merit.edu/documents/internet-drafts/ 1937 draft-ietf-wnils-whois-03.txt > 1939 Expires: 25 January 95 1941 Part I - WHOIS++ Overview 1943 1.1. Purpose and Motivation....................................... 2 1944 1.2. Basic Information Model...................................... 3 1945 1.2.1. Changes to the current WHOIS Model......................... 4 1946 1.2.2. Registering WHOIS++ servers................................ 4 1947 1.2.3. The WHOIS++ Search Selection Mechanism..................... 5 1948 1.2.4. The WHOIS++ Architecture................................... 6 1949 1.3. Indexing in WHOIS++.......................................... 6 1951 ^L 1952 1.4. Getting Help................................................. 7 1953 1.4.1. Minimum HELP Required...................................... 8 1954 1.5. Options and Constraints...................................... 8 1955 1.6. Formatting Responses......................................... 8 1956 1.7. Reporting Warnings and Errors................................ 9 1957 1.8. Privacy and Security Issues.................................. 9 1959 Part II - WHOIS++ Implementation 1961 2.1. Introduction................................................. 11 1962 2.1.1. The WHOIS++ interaction model.............................. 11 1963 2.2. The WHOIS++ Command set...................................... 12 1964 2.2.1. System Commands............................................ 12 1965 2.2.1.1. The COMMANDS command..................................... 13 1966 2.2.1.2. The CONSTRAINTS command.................................. 13 1967 2.2.1.3. The DESCRIBE command..................................... 14 1968 2.2.1.4. The HELP command......................................... 14 1969 2.2.1.5. The LIST command......................................... 14 1970 2.2.1.6. The POLLED-BY command.................................... 14 1971 2.2.1.7. The POLLED-FOR command................................... 15 1972 2.2.1.8. The SHOW command......................................... 15 1973 2.2.1.9. The VERSION command...................................... 15 1974 2.2.2. The Search Command......................................... 15 1975 2.2.2.1. Format of a Search Term.................................. 16 1976 2.2.2.2. Format of a Search String................................ 17 1977 2.3. WHOIS++ Constraints.......................................... 18 1978 2.3.1. Required Constraints....................................... 18 1979 2.3.2. Optional Constraints....................................... 19 1980 2.3.2.1. The SEARCH Constraint.................................... 20 1981 2.3.2.2. The FORMAT Constraint.................................... 21 1982 2.3.2.3. The MAXFULL Constraint................................... 21 1983 2.3.2.4. The MAXHITS Constraint................................... 21 1984 2.3.2.5. The CASE Constraint...................................... 21 1985 2.3.2.6. The AUTHENTICATE Constraint.............................. 21 1986 2.3.2.7. The USER Constraint...................................... 22 1987 2.3.2.8. The PASSWORD Constraint.................................. 22 1988 2.3.2.9. The LANGUAGE Constraint.................................. 22 1989 2.3.2.10. The INCHARSET Constraint................................ 22 1990 2.3.2.11. The IGNORE Constraint................................... 23 1991 2.3.2.12. The INCLUDE Constraint.................................. 23 1992 2.4. Server Response Modes........................................ 23 1993 2.4.1. Default Responses.......................................... 24 1994 2.4.2. Format of Responses........................................ 24 1995 2.4.3. Syntax of a Formatted Response............................. 25 1996 2.4.3.1. A FULL format response................................... 25 1997 2.4.3.2. ABRIDGED Format Response................................. 26 1998 2.4.3.3. HANDLE Format Response................................... 26 1999 2.4.3.4. SUMMARY Format Response.................................. 27 2000 2.4.3.5. MIME Format Response..................................... 27 2001 2.4.3.6. SERVERS-TO-ASK Response.................................. 27 2002 2.4.4. System Generated Messages.................................. 28 2003 2.5. Compatibility with Older WHOIS Servers....................... 28 2004 3. Miscellaneous.................................................. 29 2006 ^L 2007 3.1. Acknowledgements............................................. 29 2008 3.2. Contact information.......................................... 29 2010 Appendix A - Some Sample Queries................................... 30 2011 Appendix B - Some sample responses................................. 31 2012 Appendix C - Sample responses to system commands................... 33 2013 Appendix D - Sample whois++ session................................ 35 2014 Appendix E - System messages....................................... 37 2015 Appendix F - The WHOIS++ BNF Grammar............................... 39 2016 Appendix G - Description of Regular expressions.................... 41