idnits 2.17.1 draft-ietf-asid-whoispp-00.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-03-28) 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. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 1898 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** 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 24 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The "Author's Address" (or "Authors' Addresses") section title is misspelled. == Line 277 has weird spacing: '... server hand...' -- 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 (November 1996) is 9995 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? 'HARR85' on line 1354 looks like a reference -- Missing reference section? 'IIIR' on line 1357 looks like a reference -- Missing reference section? 'ALL96' on line 1348 looks like a reference -- Missing reference section? 'ALVE95' on line 1351 looks like a reference -- Missing reference section? 'POST82' on line 1671 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 ASID Working Group Patrik Faltstrom 2 Internet-Draft Tele 2 3 Expires: May 1997 November 1996 4 draft-ietf-asid-whoispp-00.txt 5 Replaces: RFC-1835 7 Architecture of the WHOIS++ service 9 Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its 13 areas, and its working groups. Note that other groups may also 14 distribute working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six 17 months and may be updated, replaced, or obsoleted by other docu- 18 ments at any time. It is inappropriate to use Internet- Drafts as 19 reference material or to cite them other than as ``work in 20 progress.'' 22 To learn the current status of any Internet-Draft, please check 23 the ``1id-abstracts.txt'' listing contained in the Internet- 24 Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net 25 (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East 26 Coast), or ftp.isi.edu (US West Coast). 28 Distribution of this document is unlimited. 30 Abstract 32 This document describes WHOIS++, an extension to the trivial WHOIS 33 service described in RFC 954 to permit WHOIS-like servers to make 34 available more structured information to the Internet. We describe 35 an extension to the simple WHOIS data model and query protocol and a 36 companion extensible, distributed indexing service. A number of 37 options have also been added such as the use of multiple languages 38 and character sets, more advanced search expressions, structured data 39 and a number of other useful features. An optional authentication 40 mechanism for protecting all or part of the associated WHOIS++ 41 information database from unauthorized access is also described. 43 Table of Contents 45 Part I - WHOIS++ Overview ................................. 46 1.1. Purpose and Motivation .............................. 47 1.2. Basic Information Model ............................. 48 1.2.1. Changes to the current WHOIS Model ................ 49 1.2.2. Registering WHOIS++ servers ....................... 50 1.2.3. The WHOIS++ Search Selection Mechanism ............ 51 1.2.4. The WHOIS++ Architecture .......................... 52 1.3. Indexing in WHOIS++ ................................. 53 1.4. Getting Help ........................................ 54 1.4.1. Minimum HELP Required ............................. 55 1.5. Options and Constraints ............................. 56 1.6. Formatting Responses ................................ 57 1.7. Reporting Warnings and Errors ....................... 58 1.8. Privacy and Security Issues ......................... 59 Part II - WHOIS++ Implementation .......................... 60 2.1. The WHOIS++ interaction model ....................... 61 2.2. The WHOIS++ Command set ............................. 62 2.2.1. System Commands ................................... 63 2.2.1.1. The COMMANDS command ............................ 64 2.2.1.2. The CONSTRAINTS command ......................... 65 2.2.1.3. The DESCRIBE command ............................ 66 2.2.1.4. The HELP command ................................ 67 2.2.1.5. The LIST command ................................ 68 2.2.1.6. The POLLED-BY command ........................... 69 2.2.1.7. The POLLED-FOR command .......................... 70 2.2.1.8. The SHOW command ................................ 71 2.2.1.9. The VERSION command ............................. 72 2.2.2. The Search Command ................................ 73 2.2.2.1. Format of a Search Term ......................... 74 2.2.2.2. Format of a Search String ....................... 75 2.3. WHOIS++ Constraints ................................. 76 2.3.1. Required Constraints .............................. 77 2.3.2. Optional CONSTRAINTS .............................. 78 2.3.2.1. The SEARCH Constraint ........................... 79 2.3.2.2. The FORMAT Constraint ........................... 80 2.3.2.3. The MAXFULL Constraint .......................... 81 2.3.2.4. The MAXHITS Constraint .......................... 82 2.3.2.5. The CASE Constraint ............................. 83 2.3.2.6. The AUTHENTICATE Constraint ..................... 84 2.3.2.7. The NAME Constraint ............................. 85 2.3.2.8. The PASSWORD Constraint ......................... 86 2.3.2.9. The LANGUAGE Constraint ......................... 87 2.3.2.10. The INCHARSET Constraint ....................... 88 2.3.2.11. The INCHARSET Constraint ....................... 89 2.3.2.12. The IGNORE Constraint .......................... 90 2.3.2.13. The INCLUDE Constraint ......................... 91 2.4. Server Response Modes ............................... 92 2.4.1. Default Responses ................................. 93 2.4.2. Format of Responses ............................... 94 2.4.3. Syntax of a Formatted Response .................... 95 2.4.3.1. A FULL format response .......................... 96 2.4.3.2. ABRIDGED Format Response ........................ 97 2.4.3.3. HANDLE Format Response .......................... 98 2.4.3.4. SUMMARY Format Response ......................... 99 2.4.3.5. SERVERS-TO-ASK Response ......................... 100 2.4.4. System Generated Messages ......................... 101 2.5. Compatibility with Older WHOIS Servers .............. 102 3. Miscellaneous ......................................... 103 3.1. Acknowledgements .................................... 104 3.2. References .......................................... 105 3.3. Authors' Addresses .................................. 106 Appendix A - Some Sample Queries .......................... 107 Appendix B - Some sample responses ........................ 108 Appendix C - Sample responses to system commands .......... 109 Appendix D - Sample whois++ session ....................... 110 Appendix E - System messages .............................. 111 Appendix F - The WHOIS++ BNF Grammar ...................... 112 Appendix G - Description of Regular expressions ........... 114 1. Part I - WHOIS++ Overview 116 1.1. Purpose and Motivation 118 The current NIC WHOIS service [HARR85] is used to provide a very 119 limited directory service, serving information about a small number 120 of Internet users registered with the DDN NIC. Over time the basic 121 service has been expanded to serve additional information and similar 122 services have also been set up on other hosts. Unfortunately, these 123 additions and extensions have been done in an ad hoc and 124 uncoordinated manner. 126 The basic WHOIS information model represents each individual record 127 as a Rolodex-like collection of text. Each record has a unique 128 identifier (or handle), but otherwise is assumed to have little 129 structure. The current service allows users to issue searches for 130 individual strings within individual records, as well as searches for 131 individual record handles using a very simple query-response 132 protocol. 134 Despite its utility, the current NIC WHOIS service cannot function as 135 a general White Pages service for the entire Internet. Given the 136 inability of a single server to offer guaranteed response or 137 reliability, the huge volume of traffic that a full scale directory 138 service will generate and the potentially huge number of users of 139 such a service, such a trivial architecture is obviously unsuitable 140 for the current Internet's needs for information services. 142 This document describes the architecture and protocol for WHOIS++, a 143 simple, distributed and extensible information lookup service based 144 upon a small set of extensions to the original WHOIS information 145 model. These extensions allow the new service to address the 146 community's needs for a simple directory service, yet the extensible 147 architecture is expected to also allow it to find application in a 148 number of other information service areas. 150 Added features include an extension to the trivial WHOIS data model 151 and query protocol and a companion extensible, distributed indexing 152 service. A number of other options have also been added, like boolean 153 operators, more powerful search constraints and search methods, and 154 most specificly structured the data to make both the client and the 155 server part of the dialogue more stringent and parseable. An optional 156 authentication mechanism for protecting all or parts of the 157 associated WHOIS++ information database from unauthorized access is 158 also briefly described. 160 The basic architecture of WHOIS++ allows distributed maintenance of 161 the directory contents and the use of the WHOIS++ indexing service 162 for locating additional WHOIS++ servers. Although a general overview 163 of this service is included for completeness, the indexing extensions 164 are described in a separate paper. 166 WHOIS++ is though not backward compatible with WHOIS. 168 1.2. Basic Information Model 170 The WHOIS++ service is centered in a recommendation to structure user 171 information around a series of standardized information templates. 172 Such templates consist of ordered sets of data elements (or 173 attribute-value pairs). 175 It is intended that adding such structured templates to a server and 176 subsequently identifying and searching them be simple tasks. The 177 creation and use of customized templates should also be possible with 178 little effort, although their use should be discouraged where 179 appropriate standardized templates exist. 181 Registration and schema definitions are done attribute per attribute, 182 so a client that receives a record parses the record structure 183 attribute per attribute. Because of this, the client does not have 184 to know the structure of the attribute values more than the whole 185 template. If the client sees an unknown attribute, skip that one 186 and continue parsing on the next. 188 A server that defines schemas can because of this add their own 189 unregistered attributes to a well-defined template type. 191 We also offer methods to allow the user to constrain searches to 192 desired attributes or template types, in addition to the existing 193 commands for specifying handles or simple strings. 195 It is expected that the minimalist approach we have taken will find 196 application where the high cost of configuring and operating 197 traditional White Pages services can not currently be justified. 199 Also note that the architecture makes no assumptions about the search 200 and retrieval mechanisms used within individual servers. Operators 201 are free to use dedicated database formats, fast indexing software or 202 even provide gateways to other directory services to store and 203 retrieve information, if desired. 205 The WHOIS++ server simply functions as a known front end, offering a 206 simple data model and communicating through a well known port and 207 query protocol. The format of both queries and replies has been 208 structured to allow the use of client software for generating 209 searches and displaying the results. At the same time, some effort 210 has been made to keep responses at least to some degree readible by 211 humans, to ensure low entry cost and to ease debugging. 213 The actual implemention details of an individual WHOIS++ search 214 engine are left to the imagination of the implementor and it is hoped 215 that the simple, extensible approach taken will encourage 216 experimentation and the development of improved search engines. 218 1.2.1. Changes to the current WHOIS Model 220 The current WHOIS service is based upon an extremely simple data 221 model. The NIC WHOIS database consists of a series of individual 222 records, each of which is identified by a single unique identifer 223 (the "handle"). Each record contains one or more lines of 224 information. Currently, there is no structure or implicit ordering of 225 this information, although by implication each record is concerned 226 with information about a single user or service. 228 We have implemented two basic changes to this model. First, we have 229 structured the information within the database as collections of data 230 elements, or simple attribute/value pairs. Each individual record 231 contains a specified ordered set of these data elements. 233 Secondly, we have introduced typing of the database records. In 234 effect, each record is based upon one of a specified set of 235 templates, each containing a finite and specified number of data 236 elements. This allow users to easily limit searches to specific 237 collections of information, such as information about users, 238 services, abstracts of papers, descriptions of software, and so on. 240 It is though possible, because of the typing per attribute, to add 241 non-standard attributes to a well-known template type. 243 As a final extension, we require that each individual WHOIS++ 244 database on the Internet be assigned a unique handle, analogous to 245 the handle associated with each database record. 247 The WHOIS++ database structure is shown in Fig. 1. 249 1.2.2. Registering WHOIS++ servers 251 We propose that individual database handles be registered through the 252 Internet Assigned Numbers Authority (the IANA), ensuring their 253 uniqueness. This will allow us to specify each WHOIS++ entry on the 254 Internet as a unique pair consisting of a server handle and a record 255 handle. 257 A unique registered handle is preferable to using the host's IP 258 address, since it is conceivable that the WHOIS++ server for a 259 particular domain may move over time. If we preserve the unique 260 WHOIS++ handle in such cases we have the option of using it for 261 resource discovery and networked information retrieval (see [IIIR] 262 for a discussion of resource and discovery and support issues). 264 There are many ways of guaranteeing uniqueness of server handles; we 265 will discuss them in a separate paper. 267 We believe that organizing information around a series of such 268 templates will make it easier for administrators to gather and 269 maintain this information and thus encourage them to make such 270 information available. At the same time, as users become more 271 familiar with the data elements available within specific templates 272 they will be better able to specify their searches, leading to a more 273 useful service. 275 ______________________________________________________________________ 276 | | 277 | + Single unique WHOIS++ server handle | 278 | | 279 | _______ _______ _______ | 280 | handle3 |.. .. | handle6 |.. .. | handle9 |.. .. | | 281 | _______ | _______ | _______ | | 282 | handle2 |.. .. | handle5 |.. .. | handle8 |.. .. | | 283 | _______ | _______ | _______ | | 284 | handle1 |.. .. | handle4 |.. .. | handle7 |.. .. | | 285 | |.. .. | |.. .. | |.. .. | | 286 | ------- ------- ------- | 287 | Template Template Template | 288 | Type 1 Type 2 Type 3 | 289 | | 290 | | 291 | | 292 | | 293 | Fig.1 - Structure of a WHOIS++ database. | 294 | | 295 | Notes: - Entire database is identified by a single unique WHOIS++ | 296 | serverhandle. | 297 | - Each record has a single unique handle and a specific set | 298 | of attributes, determined by the template type used. | 299 | - Each value associated with an attribute can be any ASCII | 300 | string of an arbitrary length. | 301 |______________________________________________________________________| 303 1.2.3. The WHOIS++ Search Selection Mechanism 305 The WHOIS++ search mechanism is intended to be extremely simple. A 306 search command consists of one or more search terms, with an optional 307 set of global constraints (specifiers that modify or control a 308 search). 310 Search terms allow the user to specify template type, attribute, 311 value or handle that any record returns must satisfy. Each search 312 term can have an optional set of local constraints that apply to only 313 that term. 315 A WHOIS++ database may be seen as a single rolodex-like collection of 316 typed records. Each term specifies a further constraint that the 317 selected set of output records must satisfy. Each term may thus be 318 thought of as performing a subtractive selection, in the sense that 319 any record that does not fulfil the term is discarded from the result 320 set. Boolean searches are possible by the use of AND, OR, NOT and 321 parenthesis. 323 1.2.4. The WHOIS++ Architecture 325 The WHOIS++ directory service has an architecture which is separated 326 into two components; the base level server, which is described in 327 this paper, and a indexing server. A single physical server can act 328 as both a base level server and an indexing server. 330 A base level server is one which contains only filled templates. An 331 indexing server is one which contains forward knowledge (q.v.) and 332 pointers to other indexing servers or base level servers. 334 1.3. Indexing in WHOIS++ 336 Indexing in WHOIS++ is used to tie together many base level servers 337 and index servers into a unified directory service. 339 Each base level server and index server which wishes to participate 340 in the unified directory service must generate "forward knowledge" 341 for the entries it contains. One type of forward knowledge is the 342 "centroid". 344 An example of a centroid is as follows: if a whois++ server contained 345 exactly three records, as follows: 347 Record 1 Record 2 348 Template: Person Template: Person 349 First-Name: John First-Name: Joe 350 Last-Name: Smith Last-Name: Smith 351 Favourite-Drink: Labatt Beer Favourite-Drink: Molson Beer 353 Record 3 354 Template: Domain 355 Domain-Name: foo.edu 356 Contact-Name: Mike Foobar 358 the centroid for this server would be 360 Template: Person 361 First-Name: Joe 362 John 363 Last-Name: Smith 364 Favourite-Drink:Beer 365 Labatt 366 Molson 368 Template: Domain 369 Domain-Name: foo.edu 370 Contact-Name: Mike 371 Foobar 373 An index server would then collect this centroid for this server as 374 forward knowledge. 376 Index servers can collect forward knowledge for any servers it 377 wishes. In effect, all of the servers that the index server knows 378 about can be searched with a single query to the index server; the 379 index server holds the forward knowledge along with pointers to the 380 servers it indexes, and can refer the query to servers which might 381 hold information which satisfies the query. 383 Implementors of this protocol are strongly encouraged to incorporate 384 centroid generation abilities into their servers. 386 Whois++ uses the Common Indexing Protocol [ALL96] to forward 387 knowledge, and more specifically a centroid-like CIP Index Object. 389 ------------------------------------------------------------------- 391 ____ ____ 392 top level | | | | 393 whois index | | | | 394 servers ---- ---- 395 / \________ / 396 / \ / 397 ____ ____ 398 first level | | | | 399 whois index | | | | 400 servers ---- ---- 401 / / \ 402 / / \ 403 ____ ____ ____ 404 individual | | | | | | 405 whois servers | | | | | | 406 ---- ---- ---- 408 Fig. 2 - Indexing system architecture. 410 ------------------------------------------------------------------- 412 1.4. Getting Help 414 Another extension to the basic WHOIS service is the requirement that 415 all servers support at least a minimal set of help commands, allowing 416 users to find out information about both the individual server and 417 the entire WHOIS++ service itself. This is done in the context of the 418 new extended information model by defining two specific template 419 formats and requiring each server to offer at least one example of 420 each record using these formats. The operator of each WHOIS service 421 is therefor expected to have, as a minimum, a single example of 422 SERVICES and HELP records, which can be accessed through appropriate 423 commands. 425 1.4.1. Minimum HELP Required 427 Executing the command: 429 DESCRIBE 431 gives a brief information about the WHOIS++ server. 433 Executing the command: 435 HELP 437 gives a brief description of the WHOIS++ service itself. 439 The text of both required helped records should contain pointers to 440 additional help subjects that are available. 442 Executing the command: 444 HELP 446 may give information on any topic. 448 1.5. Options and Constraints 450 The WHOIS++ service is based upon a minimal core set of commands and 451 controlling constraints. A small set of additional optional commands 452 and constraints can be supported. These would allow users to perform 453 such tasks as provide security options, modify the information 454 contents of a server or add multilingual support. The required set of 455 WHOIS++ commands are summarized in section 2.2. WHOIS++ constraints 456 are described in section 2.3. Optional constraints are described in 457 section 2.3.2. 459 1.6. Formatting Responses 461 The output returned by a WHOIS++ server is structured to allow 462 machine parsing and automated handling. Of particular interest in the 463 ability to return summary information about a search (without having 464 to return the entire results). 466 All output of searches will be returned in one of five output 467 formats, which will be one of FULL, ABRIDGED, HANDLE, SUMMARY or 468 SERVER-TO-ASK. Note that a conforming server is only required to 469 support the FULL format. 471 When available, SERVER-TO-ASK format is used to indicate that a 472 search cannot be completed but that one or more alternative WHOIS++ 473 servers may be able to perform the search. 475 Details of each output format are specified in section 2.4. 477 1.7. Reporting Warnings and Errors 479 The formatted response of WHOIS++ commands allows the encoding of 480 warning or error messages to simplify parsing and machine handling. 481 The syntax of output formats are described in detail in section 2.4, 482 and details of WHOIS++ warnings and error conditions are given in 483 Appendix E. 485 All system messages are numerical, but can be tagged with text. It is 486 the clients decision if the text is presented to the user. 488 1.8. Privacy and Security Issues 490 The basic WHOIS++ service was conceived as a simple, unauthenticated 491 information lookup service, but there are occasions when 492 authentication mechanisms are required. To handle such cases, an 493 optional mechanism is provided for authenticating each WHOIS++ 494 transaction. 496 The current identified authentication mechanism is PASSWORD, which 497 uses simple password authentication. Any other scheme name used must 498 begin with the characters "X-" and should thus be regarded as 499 experimental and non-standard. 501 Note that the WHOIS++ authentication mechanism does not dictate the 502 actual authentication scheme used, it merely provides a framework for 503 indicating that a particular transaction is to be authenticated, and 504 the appropriate mechanisms to use. This mechanism is extensible and 505 individual implementors are free to add additional mechanisms. 507 This document includes a very simple authentication scheme where a 508 combination of username and password is sent together with the search 509 string so the server can verify that the user have access to the 510 information. Note that this is NOT by any means a method recommended 511 to secure the data itself because both password and information are 512 tranferred unencrypted over the network. 514 Given the unauthenticated nature that default services like white 515 pages services are, it is easy to either forget the implications of 516 this and just show all data to the public Internet, or think that 517 Internet is so dangerous that information is hidden from the Internet 518 so the whole idea of a global white pages service is lost. Therefore 519 the type of authentication scheme selected and the public nature of 520 the Internet environment must still be taken into consideration when 521 assessing the security and authentication of the information served. 523 A more detailed exposition on security is outside the scope of this 524 document. 526 2. Part II - WHOIS++ Implementation 528 2.1. The WHOIS++ interaction model 530 A WHOIS++ server will normally listen for a TCP connections on the 531 allocated WHOIS++ port 63 (although a WHOIS++ server can be accessed 532 over any TCP connection). Once a connection is established, the 533 server issues a banner message, and listens for input. The command 534 specified in this input is processed and the results returned 535 including an ending system message. If the optional HOLD constraint 536 has not been specified the connection is then terminated. 538 If the server supports the optional HOLD constraint, and this 539 constraint is specified as part of any command, the server continues 540 to listen on the connection for another line of input. This cycle 541 continues as long as the sender continues to append the required HOLD 542 constraint to each subsequent command. 544 At the same time, each server is permitted to set an optional timeout 545 value (which should be indicated in the response to the CONSTRAINTS 546 command). If set, the server is free to terminate an idle connection 547 at any time after this delay has passed with no input from the 548 client. If the server terminates the connection due to timeout, it 549 will be indicated by the system message. The timeout value is not 550 changeable by the client. 552 2.2. The WHOIS++ Command set 554 There are two types of WHOIS++ commands - system commands and the 555 WHOIS++ search command. 557 The WHOIS++ command set consists of a core set of required systems 558 commands, a single required search command and an set of optional 559 system commands which support features that are not required by all 560 servers. The set of required WHOIS++ system commands are listed in 561 Table I. Details of the allowable search terms for the search command 562 are included in Table II. 564 Each WHOIS++ command also allows the use of one or more controlling 565 constraints, when selected can be used to override defaults or 566 otherwise modify server behavior. There is a core set of constraints 567 that must be supported by all conforming servers. These include 568 SEARCH (which controls the type of search performed), FORMAT (which 569 determines the output format used) and MAXHITS (which determines the 570 maximum number of matches that a search can return). 572 These required constraints are summarized in Table III. 574 An additional set of optional constraints are used to provide support 575 for different character sets, indicate the need and type of 576 authentication to perform on a transaction, and permit multiple 577 transactions during a single communications session. These optional 578 constraints are listed in Table IV. 580 It is possible, using the required COMMANDS and CONSTRAINTS system 581 commands, to query any WHOIS++ server for its list of supported 582 commands and constraints. 584 2.2.1. System Commands 586 System commands are commands to the server for information or to 587 control its operation. These include commands to list the template 588 types available from individual servers, to obtain a single blank 589 template of any available type, and commands to obtain the list of 590 valid commands and constraints supported on a server. 592 There are also commands to obtain the current version of the WHOIS++ 593 protocol supported, to access a simple help subsystem, to obtain a 594 brief description of the service (which is intended, among other 595 things, to support the automated registration of the service by 596 yellow pages directory services). All of these commands are required 597 from a conforming WHOIS++ server. 599 ------------------------------------------------------------------------ 601 Short Long Form Functionality 602 ----- --------- ------------- 603 COMMANDS [ ':' HOLD ] list valid WHOIS++ commands 604 supported by this server 606 CONSTRAINTS [ ':' HOLD ] List valid constraints 607 supported by this server 609 DESCRIBE [ ':' HOLD ] Describe this server, 610 formating the response 611 using a standard 612 "Services" template 614 '?' HELP [ [':' ]] System help, using a "Help" 615 template 617 LIST [':' ] List templates supported 618 by this system 620 POLLED-BY [ ':' HOLD ] List indexing servers 621 that are know to track 622 this server 624 POLLED-FOR [ ':' HOLD ] List information about 625 what this server is 626 tracking for 628 SHOW [':' ] Show contents of templates 629 specified 631 VERSION [ ':' HOLD ] return current version of 632 the protocol supported. 634 Table I - Required WHOIS++ SYSTEM commands. 636 ------------------------------------------------------------------------ 638 Below follows a descriptions for each command. Examples of responses 639 to each command is in Appendix C. 641 2.2.1.1. The COMMANDS command 643 The COMMANDS command returns a list of commands that the server 644 supports. The response is formatted as a FULL response. 646 2.2.1.2. The CONSTRAINTS command 648 The CONSTRAINTS command returns a list of constraints and the values 649 of those that the server supports. The response is formatted as a 650 FULL response, where every constraint is represented as a separate 651 record. The template name for these records is CONSTRAINT. No 652 attention is paid to handles. Each record has, as a minimum, the 653 following two fields: 655 - "Constraint", which contains the attribute name described - 656 "Default", which shows the default value for this constraint. 658 If the client is permitted to change the value of the constraint, 659 there is also: 661 - "Range" field, which contains a list of values that this 662 server supports, as a comma separated list; Or, if the range 663 is numerical, as a pair of numbers separated with a hyphen. 665 2.2.1.3. The DESCRIBE command 667 The DESCRIBE command gives a brief description about the server in a 668 "Services" template. The result is formatted as a FULL response with 669 as a minimum one field: 671 - "Text", which in a human readable form describes the service. 673 2.2.1.4. The HELP command 675 The HELP command takes an optional argument as subject to get help 676 for. 678 2.2.1.5. The LIST command 680 The LIST command returns the name of the templates available on the 681 server. The answer is formatted FULL format response. 683 2.2.1.6. The POLLED-BY command 685 The POLLED-BY command returns a list of servers and the templates and 686 attribute names that those server polled as centroids from this 687 server. The format is in FULL format with two attributes, Template 688 and Field. Each of these is a list of names of the templates or 689 fields polled. An empty result means either that the server is not 690 polled by anyone, or that it doesn't support indexing. 692 2.2.1.7. The POLLED-FOR command 694 The POLLED-FOR command returns a list of servers that this server has 695 polled, and the template and attribute names for each of those. The 696 answer is in FULL format with two attributes, Template and Field. An 697 empty result means either that the server is not polling anyone, or 698 that it doesn't support indexing. 700 2.2.1.8. The SHOW command 702 The SHOW command takes a template name as argument and returns 703 information about a specific template, formatted as a FULL response. 704 The answer is formatted as a blank template with the requested name. 706 2.2.1.9. The VERSION command 708 The output format is a FULL response containg a record with template 709 name VERSION. The record must have attribute name "Version", which 710 value is "2.0" for this version of the protocol. The record may also 711 have the additional fields "Program-Name" and "Program-Version" which 712 gives information about the server implementation if the server so 713 desires. 715 If the server also supports the earlier version of the protocol, 716 "1.0", two records are given back as a response to the VERSION 717 command, one for each version supported. 719 2.2.2. The Search Command 721 A search command consists of one or more search terms, which might 722 each have local constraints, followed by an optional colon with a set 723 of global search constraints. 725 Each attribute value in the WHOIS++ database is divided into one or 726 more words separated by whitespace. Each search term operates on 727 every word in the attribute value. 729 Two or more search terms have to be combined with boolean operators AND, 730 OR or NOT. The operator AND has higher precedence than the operator OR, 731 but this can be changed by the use of parentheses. 733 Boolean operators operates on the separate result sets created 734 when doing searches according to each of the search terms. The operation 735 A AND B produces C which have all objects occuring in both A and B. 736 The operation A OR B creates a result set of all objects in either 737 A or B etc. The NOT operator is in the same way specifying when operating 738 on result set A, all objects not in the set A. 740 Search constraints that apply to every search term are specified as 741 global constraints. Local constraints override global constraints for 742 the search term they are bound to. The search terms and the global 743 constraints are separated with a colon (':'). Additional global 744 constraints are appended to the end of the search command delimited 745 with a semicolon ';'. 747 If different search constraints can not be fulfilled, or the 748 combination of different search constraints is uncombinable, the 749 server may choose to ignore some constraints, but still do the search 750 and return some records. 752 The set of required constraints are summarized in Table III. The set 753 of optional constraints are summarized in Table IV. 755 As an option, the server may accept specifications for attributes for 756 either inclusion or exclusion from a reply. Thus, users could specify 757 -only- those attributes to return, or specific attributes to filter 758 out, thus creating custom views. 760 2.2.2.1. Format of a Search Term 762 Each search term consists of one of the following: 764 1) A search string, followed by an optional semicolon and set of 765 semicolon-separated local constraints. 767 2) A search term specifier (as listed in Table II), followed by a 768 '=', followed by a search string, an optional semicolon and a 769 set of semicolon-separate local constraints. 771 3) An abbreviated search term specifier, followed by a search 772 string, followed by an optional semicolon and set of 773 semicolon-separated local constraints. 775 4) A combination of attribute name, followed by '=', followed by 776 a search string, followed by an optional semicolon and set of 777 semicolon-separate local constraints. 779 If no term identifier is provided, then the search will be applied to 780 attribute values only. This corresponds to an identifier of VALUE. 782 When the user specifies the search term using the form: 784 " = " 786 this is considered to be an ATTRIBUTE-VALUE search. 788 For discussion of the system reply format, and selecting the 789 appropriate reply format, see section 2.4. 791 ------------------------------------------------------------------- 793 Valid specifiers: 794 ----------------- 796 Name Functionality 797 ---- ------------- 799 HANDLE Confine search to handles. 800 VALUE Confine search to attribute 801 values. 803 (Note: The name HANDLE can be replaced with the shortname '!') 805 Acceptable forms of a search specifier: 806 --------------------------------------- 808 1) [';' ]* 810 2) = [';' ]* 812 3) [';' ]* 814 4) = [';' ]* 816 (Note: A is a valid local constraint specification.) 818 Table II - Valid search command term specifiers. 820 ------------------------------------------------------------------- 822 2.2.2.2. Format of a Search String 824 Special characters that need to be quoted are preceeded by a 825 backslash, '\'. 827 Special characters are space ' ', tab, equal sign '=', comma ',', 828 colon ':', backslash '\', semicolon ';', asterisk '*', period '.', 829 parenthesis '()', square brackets '[]', dollar sign '$' and 830 circumflex '^'. 832 If the search term is given in some other character set than ISO- 833 8859-1, it must be specified by the constraint INCHARSET. 835 2.3. WHOIS++ Constraints 837 Constraints are intended to be hints or recommendations to the server 838 about how to process a command. They may also be used to override 839 default behaviour, such as requesting that a server not drop the 840 connection after performing a command. 842 Thus, a user might specify a search constraint as "SEARCH=exact", 843 which means that the search engine is to perform an exact match 844 search. It might also specify "LANGUAGE=Fr", which implies that the 845 server should display the french versions of the attribute values, 846 and if possible use french in fuzzy matches. It might also 847 be able to issue system messages in French. 849 In general, contraints take the form "=", with 850 being one of a specified set of valid values. The notable 851 exception is "HOLD", which takes no argument. 853 All constraints can be used as a global constraint, but only a few 854 can be used as local. See tables IV and V for information of which 855 constraints can be local. 857 The CONSTRAINTS system command is used to list the search constraints 858 supported by an individual server. 860 If a server cannot satisfy the specified constraint there will be a 861 mechanism for informing the user in the reply, using system messages. 862 In such cases, the search is still performed, with the the server 863 ignoring unsupported constraints. 865 2.3.1. Required Constraints 867 The following CONSTRAINTS must be supported in all conforming WHOIS++ 868 servers. 870 ------------------------------------------------------------------ 872 Format LOCAL/GLOBAL 873 ------ ------------- 875 SEARCH= {exact | lstring } LOCAL/GLOBAL 877 FORMAT= {full | abridged | handle | summary } GLOBAL 879 MAXHITS= { 1- } GLOBAL 881 Table III - Required WHOIS++ constraints. 883 ------------------------------------------------------------------ 885 2.3.2. Optional CONSTRAINTS 887 The following CONSTRAINTS and constraint values are not required of a 888 conforming WHOIS++ server, but may be supported. If supported, their 889 names and supported values must be returned in the response to the 890 CONSTRAINTS command. 892 --------------------------------------------------------------------- 894 Format LOCAL/GLOBAL 895 ------ ------------- 897 SEARCH= { regex | fuzzy | substring | } LOCAL/GLOBAL 899 CASE= { ignore | consider } LOCAL/GLOBAL 901 FORMAT= { server-to-ask | } GLOBAL 903 MAXFULL= { 1- } GLOBAL 905 AUTHENTICATE= password GLOBAL 907 NAME= GLOBAL 909 PASSWORD= GLOBAL 911 INCHARSET= { us-ascii | iso-8859-* | 912 UNICODE-1-1-UTF-8 | UNICODE-2-0-UTF-8} GLOBAL 914 OUTCHARSET= { us-ascii | iso-8859-* | 915 UNICODE-1-1-UTF-8 | UNICODE-2-0-UTF-8} GLOBAL 917 LANGUAGE= GLOBAL 919 HOLD GLOBAL 921 IGNORE= {attributelist} GLOBAL 923 INCLUDE= {attributelist} GLOBAL 925 Table IV - Optional WHOIS++ constraints. 927 ---------------------------------------------------------------------- 929 2.3.2.1. The SEARCH Constraint 931 The SEARCH constraint is used for specifying the method that is to be 932 used for the search. The default method is "exact". Following is a 933 definition of each search method. 935 exact The search will succeed for a word that exactly 936 matches the search string. 938 substring The search will succeed for a word that matches 939 a part of a word. 941 regex The search will succeed for a word when a regular 942 expression matches the searched data. Regular 943 expression is built up by using constructions of 944 '*', '.', '^', '$', and '[]'. For use of 945 regular expressions see Appendix G. 947 fuzzy The search will succeed for words that matches the 948 search string by using an algorithm designed to catch 949 closely related names with different spelling, e.g. 950 names with the same pronounciation. The server 951 chooses which algorithm to use, but it may vary 952 depending on template name, attribute name and 953 language used (see Constraint Language above). 955 lstring The search will succed for words that begins 956 with the search string. 958 2.3.2.2. The FORMAT Constraint 960 The FORMAT constraint describes what format the result will be in. 961 Default format is FULL. For a description of each format, see Server 962 Response Modes below. 964 2.3.2.3. The MAXFULL Constraint 966 The MAXFULL constraint sets the limit of the number of matching 967 records the server allows before it enforces SUMMARY responses. The 968 client may attempt to override this value by specifying another value 969 to that constraint. Example: If, for privacy reasons, the server will 970 return the response in SUMMARY format if the number of hits exceeds 971 2, the MAXFULL constraint is set to 2 by the server. 973 Regardless of what format the client did or did not ask for, the 974 server will change the response format to SUMMARY when the number of 975 matching records equals or exceeds this value. 977 2.3.2.4. The MAXHITS Constraint 979 The MAXHITS constraint sets the maximum number of records the client 980 can get in a search respone. 982 2.3.2.5. The CASE Constraint 984 The CASE constraint defines if the search should be done case 985 sensistive or not. Default value is to have case ignored. 987 2.3.2.6. The AUTHENTICATE Constraint 989 The AUTHENTICATE constraint describes which authentication method to 990 use when executing the search. By using a specific authentication 991 method, some other constraints might be needed which is specified by 992 the authentication method. 994 The only authentication method described in this document is 995 "password", if used, also the two other constraints "name" and 996 "password" need to be set. 998 2.3.2.7. The NAME Constraint 1000 The NAME constraint is only used together with some authentication 1001 method named by the constraint "authenticate". The only use described 1002 in this document is by sending a username as a string of characters 1003 which together with the string given as an argument to the "password" 1004 constraint is sent to the server. The server can use that pair of 1005 strings to do a simple authentication check, similar to the UNIX 1006 login program. 1008 2.3.2.8. The PASSWORD Constraint 1010 The PASSWORD constraint is only used together with some 1011 authentication method named by the constraint "authenticate". The 1012 only use described in this document is by sending a password as a 1013 string of characters which together with the string given as an 1014 argument to the "name" constraint is sent to the server. The server 1015 can use that pair of strings to do a simple authentication check, 1016 similar tothe UNIX login program. 1018 2.3.2.9. The LANGUAGE Constraint 1020 The LANGUAGE constraints is given to specify which attribute values 1021 should be presented to the client. It can be used as an extra 1022 information to the fuzzy matching search method, and it might 1023 also be used to tell the server to give the system responses 1024 in another language, although this ability should be handled by 1025 the client. The language codes defined in RFC 1766 [ALVE95] should be 1026 used as a value for the language constraint. In these, the case of 1027 the letters are insignigicant. 1029 If a record have attribute values in different languages, and no LANGUAGE 1030 search constraint was given in the query, the switch between the 1031 different languages should be given in the response by the use 1032 of system messages 601 which has one argument only, the name of the 1033 language or one of the predefined strings "ANY" or "DEF". A block 1034 of alternative attribute values starts with a language definition 1035 like "% 601 SE". After the first language specification, zero or 1036 more language specifications can be given, each switching into the 1037 desired language. When all specific languages have been tagged, the 1038 specification "% 601 DEF" can be used for specifying default attribute 1039 values. A block of alternative attributes must end with "% 601 ANY". 1041 The following is an example of the use of the language messages: 1043 # FULL USER LOCAL USER-DOE 1044 % 601 FR 1045 Name: Monsieur John Doe 1046 % 601 SV 1047 Name: Herr John Doe 1048 % 601 DEF 1049 Name: Mister John Doe 1050 % 601 ANY 1051 Email: jdoe@doe.pp.se 1052 # END 1054 The language specifications might not be specified by the server if the 1055 client has explicitely, by using the global constraint LANGUAGE, asked 1056 for a specific language. 1058 2.3.2.10. The INCHARSET Constraint 1060 The INCHARSET constraint tells the server in which character set the 1061 search string itself is given in. The default character set is ISO- 1062 8859-1. 1064 2.3.2.11. The OUTCHARSET Constraint 1066 The OUTCHARSET constraint tells the server in which character set the 1067 search result is supposed to be given in. The default character set is 1068 ISO-8859-1, but the server might choose something else if necessary. 1070 2.3.2.12. The IGNORE Constraint 1072 The IGNORE constraint specifies which attributes to NOT include in 1073 the result. All other attributes will be included (as if named 1074 explicitly by the "include" constraint). 1076 If an attribute is named both with the "include" and "ignore" 1077 constraint, the attribute is to be included in the result, but the 1078 system message must be "% 205 Requested constraint not fulfilled". 1080 2.3.2.13. The INCLUDE Constraint 1082 The INCLUDE constraint specifies which attributes to include in the 1083 result. All other attributes will be excluded (as if named explicitly 1084 by the "ignore" constraint). 1086 If an attribute is named both with the "include" and "ignore" 1087 constraint, the attribute is to be included in the result, but the 1088 system message must be "% 205 Requested constraint not fulfilled". 1090 2.4. Server Response Modes 1092 There are currently a total of five different response modes possible 1093 for WHOIS++ servers. These are FULL, ABRIDGED, HANDLE, SUMMARY and 1094 SERVER-TO-ASK. The syntax of each output format is specified in more 1095 detail in the following section. 1097 1) A FULL format response provides the complete contents of a 1098 template matching the specified query, including the template 1099 type, the server handle and an optional record handle. 1101 2) An ABRIDGED format response provides a brief summary, including 1102 (as a minimum) the server handle, the corresponding record handle 1103 and relevant information for that template. 1105 3) A HANDLE format response returns a line with information about 1106 the server handle and record handle for a record that matched 1107 the specified query. 1109 4) A SUMMARY response provides only a brief summary of information 1110 the number of matches and the list of template types in which the 1111 matches occured. 1113 5) A SERVER-TO-ASK response only returns pointers to other index 1114 servers which might possibly be able to answer the specified 1115 query. 1117 The server may respond with a null answer and may also respond with a 1118 null answer together with a correct system message to indicate that 1119 the query was too complex. 1121 2.4.1. Default Responses 1123 By default, a WHOIS++ server will provide FULL responses. This may be 1124 changed by the client with the use of the global constraint "format". 1126 The server will not respond with more matches than the value 1127 specified with the global constraint "maxhits" in any response 1128 format. If the number of matches exceeds this value, the server will 1129 issues the system message 110 (maxhits value exceeded), but will 1130 still show the responses, up to the number of the "maxhits" 1131 constraint value. This mechanism will allow the server to hide the 1132 number of possible matches to a search command. 1134 The server response modes are summarized in Table V. 1136 2.4.2. Format of Responses 1138 Each response consists of a numerical system generated message, which 1139 can be tagged with text, followed by an optional formatted response 1140 message, followed by a second system generated message. The formatted 1141 response itself can include system messages, for example for switches in 1142 language. 1144 That is: 1146 '%' 1148 [ ] 1150 '%' 1152 If there are no matches to a query, the system is not required to 1153 generate any output as a formatted response, although it must still 1154 generate system messages. 1156 For information about the format for system messages, see Appendix E. 1158 2.4.3. Syntax of a Formatted Response 1160 All formatted responses except for the HANDLE response, consists of a 1161 response-specific START line, followed by an optional response- 1162 specific data section, followed by a TERMINATION line. The HANDLE 1163 response is different in that it only consists of a START line. It 1164 is permissible to insert any number of lines consisting solely of 1165 newlines within a formatted response to improve readibility. 1167 Each line shall be limited to no more than 81 characters, including 1168 the terminating newline. If a line (including the required leading 1169 single space) would exceed 81 characters, it is to be broken into 1170 lines of no more than 81 characters, with each continuation line 1171 beginning with a "+" character in the first column instead of the 1172 leading character. 1174 If an attribute value in a data section includes a line break, the 1175 line break must be replaced by a CR/LF pair and the following line 1176 begin with a "-" character in the first column, instead of the 1177 leading character. The attribute name is not repeated on consecutive 1178 lines. 1180 A TERMINATION line consists of a line with a '#' in the first column, 1181 followed by one white space character (SPACE or TAB), followed by the 1182 keyword END, followed by zero or more characters, followed by a 1183 newline. 1185 A response-specific section will be one of the following: 1187 1) FULL Format Response 1188 2) ABRIDGED Format Response 1189 3) HANDLE Format Response 1190 4) SUMMARY Format Response 1191 5) SERVER-TO-ASK Format Response 1193 The details of each are specified in the following sections: 1195 2.4.3.1. A FULL format response 1197 A FULL format response consists of a series of responses, each 1198 consisting of a START line, followed by the complete template 1199 information for the matching record and a TERMINATION line. 1201 Each START line consists of a '#' in the first column, followed by 1202 one white space character, the word "FULL", a white space character, 1203 the name of the corresponding template type, one white space 1204 character, the server handle, a white space character, an optional 1205 handle for the record, and a terminating newline. 1207 The template information for the record will be returned as a series 1208 of lines consisting of a single space, followed by the corresponding 1209 line of the record. 1211 The line of the record shall consist of a single space and the 1212 attribute name followed by a ':', a single space, the value of that 1213 attribute, and a newline. 1215 2.4.3.2. ABRIDGED Format Response 1217 Each ABRIDGED format response consists of a START line, a single line 1218 excerpt of the template information from each matching record and a 1219 TERMINATION line. The excerpt information shall include information 1220 that is relevant to the template type. 1222 The START line consists of a '#' in the first column, followed by one 1223 white space character, the word "ABRIDGED", a white space character, 1224 the name of the corresponding template type, a white space character, 1225 the server handle, a white space character, the handle for the 1226 record, and a terminating newline. 1228 The abridged template information will be returned as a line, 1229 consisting of a single space, followed by the abridged line of the 1230 record and a newline pair. 1232 2.4.3.3. HANDLE Format Response 1234 A HANDLE response consists of a single START line, which shall start 1235 with a '#' in the first column, followed by one white space 1236 character, the word "HANDLE", a white space character, the name of 1237 the corresponding template, a white space character, the handle for 1238 the server, a white space character, the handle for that record, and 1239 a terminating newline. 1241 2.4.3.4. SUMMARY Format Response 1243 A SUMMARY format response consists of a single set of responses, 1244 consisting of a line listing the number of matches to the specified 1245 query, followed by a list of all template types which satisfied the 1246 query at least once. 1248 The START line shall begin with a '#' in the first column, be 1249 followed by one white space character, the word "SUMMARY", a white 1250 space character, the handle for the server, and a terminating 1251 newline. 1253 The format of the attributes in the SUMMARY format follows the 1254 rules for the FULL template, with the attributes "matches", 1255 "referrals" and "templates". "matches" and "templates" are 1256 mandatory, "referrals" optional. 1258 The first line must begin with the string "matches:", be 1259 followed by a space and the number of responses to the query and 1260 terminated by a newline. 1262 The following line shall either begin with the string "templates: " 1263 or the string "referrals: ". The string "templates: " are followed 1264 by a newline separated list of the name of the template types 1265 which matched the query. Each line following the first which 1266 include the text "templates:" must begin with a '-' instead of 1267 a space. The string "referrals: " is followed by the number of 1268 referrals included in the number of hits. 1270 2.4.3.5. SERVER-TO-ASK Response 1272 A SERVER-TO-ASK response consists of information to the client about 1273 a server to contact next to resolve a query. If the server has 1274 pointers to more than one server, it will present additional SERVER- 1275 TO-ASK responses. 1277 The SERVER-TO-ASK response will consist of a START line and a number 1278 of lines with attribute-value pairs, separated by CRLF. Each line is 1279 indented with one space. The end of a SERVER-TO-ASK response is 1280 indicated with a TERMINATION line. 1282 Each START line consists of a '#' in the first column, followed by 1283 one white space character, the word "SERVER-TO-ASK", a white space 1284 character, the handle of the server and a terminating newline. 1286 1. "Server-Handle" - The server handle of the server pointed at. 1287 (req.) 1288 2. "Host-Name" - Hostname for the server pointed at. 1289 3. "Host-Port" - Portnumber for the server pointed at. 1290 4. "Protocol" - The protocol to use when contacting this server. (opt.) 1292 Other attributes may be present, depending on the index server. 1293 The default protocol to use is Whois++. 1295 2.4.4. System Generated Messages 1297 All system generated messages must begin with a '%' as the first 1298 character, a space as the second one, followed by a three digit 1299 number, a space and an optional text message. The total length of the 1300 line must be no more than 81 characters long, including the 1301 terminating CR LF pair. There is no limit to the number of system 1302 messages that may be generated. 1304 The format for multiline replies requires that every line, except the 1305 last, begin with "%", followed by space, the reply code, a hyphen, 1306 and an optional text. The last line will begin with "%", followed by 1307 space, the reply code, a space and some optional text. 1309 System generated messages displayed before or after the formatted 1310 response section are expected to refer to operation of the system or 1311 refer to the entire query. System generated messages within the 1312 output of an individual record during a FULL reponse are expected to 1313 refer to that record only, and could (for example) be used to 1314 indicate problems with that record of the response. See Appendix E 1315 for a description of system messages. 1317 2.5. Compatibility with Older WHOIS Servers 1319 Note that this format, although potentially more verbose, is still in 1320 a human readible form. Responses from older systems that do not 1321 follow this format are still conformant, since their responses would 1322 be interpreted as being equivalent to optional text messages, without 1323 a formatted response. Clients written to this specification would 1324 display the responses as a advisory text message, where it would 1325 still be readible by the user. 1327 3. Miscellaneous 1329 3.1. Acknowledgements 1331 The WHOIS++ effort began as an intensive brainstorming session at the 1332 24th IETF, in Boston Massachusetts. Present at the birth, and 1333 contributing ideas through this early phase, were (alphabetically) 1334 Peter Deutsch, Alan Emtage, Jim Fullton, Joan Gargano, Brad 1335 Passwaters, Simon Spero, and Chris Weider. Others who have since 1336 helped shape this document with feedback and suggestions include 1337 Roxana Bradescu, Patrik Faltstrom, Kevin Gamiel, Dan Kegel, Michael 1338 Mealling, Mark Prior and Rickard Schoultz. 1340 Version 2 of the protocol is based on input during the lifetime of 1341 version 1. Especially I have to mention Jeff Allen, Leslie Daigle, 1342 and Philippe Boucher. During the polishing of the RFC for version 2, 1343 important input was given by Len Charest, Clarke Anderson and others 1344 in the ASID working group of the IETF. 1346 3.2 References 1348 [ALL96] Allen J., "The Common Indexing Protocol (CIP)", 1349 draft-ietf-find-new-cip-02.txt, Nov 1996. 1351 [ALVE95] Alvestrand H., "Tags for the Identification of 1352 Languages", RFC 1766, UNINETT, March 1995. 1354 [HARR85] Harrenstein K., Stahl M., and E. Feinler, 1355 "NICNAME/WHOIS", RFC 954, SRI, October 1985. 1357 [IIIR] Weider C., and P. Deutsch, "A Vision of an 1358 Integrated Internet Information Service", RFC 1727 1359 Bunyip Information Systems, Inc., December 1994. 1361 [POST82] Postel J., "Simple Mail Transfer Protocol", STD 10, 1362 RFC 821, USC/Information Sciences Institute, 1363 August 1982. 1365 3.3. Authors Addresses 1367 Patrik Faltstrom 1368 Tele2 1369 Borgarfjordsgatan 16 1370 BOX 62 1371 194 64 Kista 1372 SWEDEN 1374 Email: paf@swip.net 1376 Appendix A - Some Sample Queries 1378 author=leslie and template=user 1380 The result will consist of all records where attribute "author" 1381 matches "chris" with case ignored. Only USER templates will be 1382 searched. An example of a matching attribute is "Author=Leslie L. Daigle". 1383 This is the typical case of search. 1385 author=leslie and template=user:language=fr 1387 The result will consist of the same records as above, but if 1388 attributes are available in alternative languages, only the 1389 ones in french will be displayed. This means either the ones which 1390 have explicitely french values, or the default language. 1392 schoultz and rick;search=lstring 1394 The result will consist of all records which have one attribute value 1395 matching "schoultz" exactly and one having "rick" as leading 1396 substring, both with case ignored. One example is "Name=Rickard 1397 Schoultz". 1399 value=phone;search=substring 1401 The result will consist of all records which have attribute values 1402 matching *phone*, for example the record "Name=Acme telephone inc.", 1403 but will not match the attribute name "phone". (Since "value" term 1404 specifier is the default, the search term could be "phone" as well as 1405 "value=phone".) 1407 ucdavis;search=substring and (gargano or joan):include=name,email 1409 This search command will find records which have records containing 1410 the words "gargano" or "joan" somewhere in the record, and has the 1411 word "ucdavis" somewhere in a word. The result will only show the 1412 "name" and "email" fields. 1414 Appendix B - Some sample responses 1416 1) FULL format responses: 1418 # FULL USER SERVERHANDLE1 PD45 1419 Name: Peter Deutsch 1420 email: peterd@bunyip.com 1421 # END 1422 # FULL USER SERVERHANDLE1 AE1 1423 Name: Alan Emtage 1424 email: bajan@bunyip.com 1425 # END 1426 # FULL USER SERVERHANDLE1 NW1 1427 Name: Nick West 1428 Favourite-Bicycle-Forward-Wheel-Brand: New Bicy 1429 +cles Acme Inc. 1430 email: nick@bicycle.acme.com 1431 My-favourite-song: Happy birthday to you! 1432 -Happy birthday to you! 1433 -Happy birthday dear Nick! 1434 -Happy birthday to you. 1435 # END 1436 # FULL SERVICES SERVERHANDLE1 WWW1 1437 Type: World Wide Web 1438 Location: the world 1439 # END 1441 -------------------- 1443 2) An ABRIDGED format response: 1445 # ABRIDGED USER SERVERHANDLE1 PD45 1446 Peter Deutsch peterd@bunyip.com 1447 # END 1448 # ABRIDGED USER SERVERHANDLE1 AE1 1449 Alan Emtage bajan@bunyip.com 1450 # END 1451 # ABRIDGED USER SERVERHANDLE1 WWW1 1452 World Wide Web the world 1453 # END 1455 -------------------- 1457 3) HANDLE format responses: 1459 # HANDLE USER SERVERHANDLE1 PD45 1460 # HANDLE USER SERVERHANDLE1 AE1 1461 # HANDLE SERVICES SERVERHANDLE1 WWW1 1463 -------------------- 1465 4) A SUMMARY HANDLE format response: 1467 # SUMMARY SERVERHANDLE1 1468 Matches: 35 1469 Referrals: 2 1470 Templates: User 1471 -Services 1472 -Abstracts 1473 # END 1475 Appendix C - Sample responses to system commands 1477 C.1 Response to the LIST command 1479 # FULL LIST SERVERHANDLE1 1480 Templates: USER 1481 -SERVICES 1482 -HELP 1483 # END 1485 C.2 Response to the SHOW command 1487 This example shows the result after issuing "show user": 1489 # FULL USER SERVERHANDLE1 1490 Name: 1491 Email: 1492 Work-Phone: 1493 Organization-Name: 1494 City: 1495 Country: 1496 # END 1498 C.3 Response to the POLLED-BY command 1500 # FULL POLLED-BY SERVERHANDLE1 1501 Server-handle: serverhandle2 1502 Cached-Host-Name: sunic.sunet.se 1503 Cached-Host-Port: 7070 1504 Template: USER 1505 Field: ALL 1506 # END 1507 # FULL POLLED-BY SERVERHANDLE1 1508 Server-handle: serverhandle3 1509 Cached-Host-Name: kth.se 1510 Cached-Host-Port: 7070 1511 Template: ALL 1512 Field: Name,Email 1513 # END 1515 C.4 Response to the POLLED-FOR command 1517 # FULL POLLED-FOR SERVERHANDLE1 1518 Server-Handle: serverhandle5 1519 Template: ALL 1520 Field: Name,Address,Job-Title,Organization-Name, 1521 +Organization-Address,Organization-Name 1522 # END 1523 # FULL POLLED-FOR SERVERHANDLE1 1524 Server-Handle: serverhandle4 1525 Template: USER 1526 Field: ALL 1527 # END 1529 C.5 Response to the VERSION command 1531 # FULL VERSION BUNYIP.COM 1532 Version: 2.0 1533 Program-Name: Digger 1534 Program-Version: 3.0b1 1535 Program-Author: Bunyip Information Systems Inc. 1536 Program-Author-Email: digger-info@bunyip.com 1537 Bug-Report-Email: digger-bugs@bunyip.com 1538 # END 1540 C.6 Response to the CONSTRAINTS command 1542 # FULL CONSTRAINTS SERVERHANDLE1 1543 CONSTRAINT: maxhits 1544 DEFAULT: 100 1545 RANGE: 0-100 1546 # END 1547 # FULL CONSTRAINTS SERVERHANDLE1 1548 CONSTRAINT: case 1549 DEFAULT: ignore 1550 RANGE: ignore, consider 1551 # END 1552 # FULL CONSTRAINTS SERVERHANDLE1 1553 CONSTRAINT: search 1554 DEFAULT: exact 1555 RANGE: exact, lstring, substring, fuzzy 1556 # END 1557 # FULL CONSTRAINTS SERVERHANDLE1 1558 CONSTRAINT: language 1559 DEFAULT: DEF 1560 RANGE: FR, EN, SV, ANY, DEF 1561 # END 1562 # FULL CONSTRAINTS SERVERHANDLE1 1563 CONSTRAINT: incharset 1564 DEFAULT: ISO-8859-1 1565 RANGE: ISO-8859-1, UNICODE-1-1-UTF8 1566 # END 1567 # FULL CONSTRAINTS SERVERHANDLE1 1568 CONSTRAINT: outcharset 1569 DEFAULT: ISO-8859-1 1570 RANGE: ISO-8859-1, UNICODE-1-1-UTF8, HTML 1571 # END 1573 C.3 Response to the COMMANDS command 1575 # FULL COMMANDS SERVERHANDLE1 1576 Commands: commands 1577 -constraints 1578 -describe 1579 -help 1580 -list 1581 -polled-by 1582 -polled-for 1583 -show 1584 -version 1585 # END 1587 Appendix D - Sample whois++ session 1589 Below is an example of a session between a client and a server. The 1590 angle brackets to the left is not part of the communication, but is 1591 just put there to denonte the direction of the communication between 1592 the server or the client. Text appended to '>' means messages from 1593 the server and '<' from the client. 1595 Client connects to the server 1597 >% 220-Welcome to 1598 >% 220-the whois++ server 1599 >% 220 at ACME inc. 1600 % 200 Command okay 1602 > 1603 ># FULL USER ACME.COM NW1 1604 > name: Nick West 1605 > email: nick@acme.com 1606 ># END 1607 ># SERVER-TO-ASK ACME.COM 1608 > Server-Handle: SUNETSE01 1609 > Host-Name: whois.sunet.se 1610 > Host-Port: 7070 1611 ># END 1612 ># SERVER-TO-ASK ACME.COM 1613 > Server-Handle: KTHSE01 1614 ># END 1615 >% 226 Tranfer complete 1616 % 200 Command okay 1618 ># FULL VERSION ACME.COM 1619 > Version: 2.0 1620 ># END 1621 >% 226 Tranfer complete 1622 >% 203 Bye 1623 Server closes the connection 1625 In the example above, the client connected to a whois++ server and 1626 queried for all records where the attribute "name" equals "Nick", and 1627 asked the server not to close the connection after the response by 1628 using the global constraint "HOLD". 1630 The server responds with one record and a pointer to two other 1631 servers that either holds records or pointers to other servers. 1633 The client continues with asking for the servers version number 1634 without using the HOLD constraint. After responding with protocol 1635 version, the server closes the connection. 1637 Note that each response from the server begins system message 200 1638 (Command OK), and ends with system message 226 (Transfer Complete). 1640 Appendix E - System messages 1642 A system message begins with a '%', followed by a space and a three 1643 digit number, a space, and an optional text message. The line message 1644 must be no more than 81 characters long, including the terminating CR 1645 LF pair. There is no limit to the number of system messages that may 1646 be generated. 1648 A multiline system message have a hyphen instead of a space in column 1649 6, immediately after the numeric response code in all lines, except 1650 the last one, where the space is used. 1652 Example 1 1654 % 200 Command okay 1656 Example 2 1658 % 220-Welcome to 1659 % 220-the whois++ server 1660 % 220 at ACME inc. 1662 The client is not expected to parse the text part of the response 1663 message except when receiving reply 600 or 601, in which case the 1664 text part is in the former case the name of a character set that 1665 will be used by the server in the rest of the response, and in the 1666 latter case when it specifies what language the attribute value is in. 1667 The valid values for characters sets is specified in the "characterset" 1668 list in the BNF listing in Appendix F. 1670 The theory of reply codes is described in Appendix E in STD 10, RFC 1671 821 [POST82]. 1673 ------------------------------------------------------------------------ 1675 List of system response codes 1676 ------------------------------ 1678 110 Too many hits The number of matches exceeded 1679 the value specified by the 1680 maxhits constraint. Server 1681 will still reply with as many 1682 records as "maxhits" allows. 1684 111 Requested constraint not supported One or more constraints in 1685 query is not implemented, but 1686 the search is still done. 1688 112 Requested constraint not fullfilled One or more constraints in 1689 query has unacceptable value 1690 and was therefore not used, 1691 but the search is still done. 1693 200 Command Ok Command accepted and executed. 1694 The client must wait for a 1695 transaction end system message. 1697 201 Command Completed successfully Command accepted and executed. 1699 203 Bye Server is closing connection 1701 220 Service Ready Greeting message. Server is 1702 accepting commands. 1704 226 Transaction complete End of data. All responses to 1705 query are sent. 1707 430 Authentication needed Client requested information 1708 that needs authentication. 1710 500 Syntax error 1712 502 Search expression too complicated This message is sent when the 1713 server is not able to resolve 1714 a query (i.e. when a client 1715 sent a regular expression that 1716 is too deeply nested). 1718 530 Authentication failed The authentication phase 1719 failed. 1721 600 Subsequent attribute values 1722 are encoded in the charater 1723 set specified by . 1725 601 Subsequent attribute values 1726 are in the language specified 1727 by . 1729 601 DEF Subsequent attribute values 1730 are default values, i.e. they 1731 should be used for all languages 1732 not specified by "601 " 1733 since last "601 ANY" message. 1735 601 ANY Subsequent attribute values 1736 are for all languages. 1738 Table V - System response codes 1740 ------------------------------------------------------------------------ 1742 Appendix F - The WHOIS++ BNF Grammar 1744 whois-command = ( system-command [":" "hold"] 1745 / terms [":" globalcnstrnts] ) NL 1747 system-command = "constraints" 1748 / "describe" 1749 / "commands" 1750 / "polled-by" 1751 / "polled-for" 1752 / "version" 1753 / "list" 1754 / "show" [1*SP string] 1755 / "help" [1*SP string] 1756 / "?" [string] 1758 terms = and-expr *("or" and-expr) 1760 and-expr = not-expr *("and" not-expr) 1762 not-expr = ["not"] (term / ( "(" terms ")" )) 1764 term = generalterm / specificterm 1765 / shorthandle / combinedterm 1767 generalterm = string *(";" localcnstrnt) 1769 specificterm = specificname "=" string 1770 *(";" localcnstrnt) 1772 specificname = "handle" / "value" 1774 shorthandle = "!" string *(";" localcnstrnt) 1776 combinedterm = attributename "=" string *(";" localcnstrnt) 1778 globalcnstrnts = globalcnstrnt *(";" globalcnstrnt) 1780 globalcnstrnt = localcnstrnt 1781 / "format" "=" format 1782 / "maxfull" "=" 1*digit 1783 / "maxhits" "=" 1*digit 1784 / opt-globalcnst 1786 opt-globalcnst = "hold" 1787 / "authenticate" "=" auth-method 1788 / "name" "=" string 1789 / "password" "=" string 1790 / "language" "=" language 1791 / "incharset" "=" characterset 1792 / "ignore" "=" string 1793 / "include" "=" string 1795 format = "full" / "abridged" / "handle" / "summary" 1796 / "server-to-ask" 1798 language = 1800 characterset = "us-ascii" / "iso-8859-1" / "iso-8859-2" / 1801 "iso-8859-3" / "iso-8859-4" / "iso-8859-5" / 1802 "iso-8859-6" / "iso-8859-7" / "iso-8859-8" / 1803 "iso-8859-9" / "iso-8859-10" / "UNICODE-1-1-UTF-8" / 1804 "UNICODE-2-0-UTF-8" / charset-value 1806 charset-value = 1*char 1808 localcnstrnt = "search" "=" searchvalue / 1809 "case" "=" casevalue 1811 searchvalue = "exact" / "substring" / "regex" / "fuzzy" 1812 / "lstring" 1814 casevalue = "ignore" / "consider" 1816 auth-method = "password" 1818 string = 0*char 1820 attributename = 1*normalchar 1822 char = "\" specialchar / normalchar 1824 normalchar = 1826 specialchar = " " / / "=" / "," / ":" / ";" / "\" / 1827 "*" / "." / "(" / ")" / "[" / "]" / "^" / 1828 "$" / "!" / "?" 1830 digit = "0" / "1" / "2" / "3" / "4" / 1831 "5" / "6" / "7" / "8" / "9" 1833 NL = 1835 NOTE: Significant blanks must be escaped. The following 1836 characters, when significant to the query, may be preceded 1837 and/or followed by a single blank: 1839 : ; , ( ) = ! 1841 Appendix G - Description of Regular expressions 1843 The regular expressions described in this section is the same as used 1844 in many other applications and operating systems. It is though very 1845 simple and does not include logical operators AND and OR. 1847 Searches using regular expressions are always using substring 1848 matching except when the regular expression contains the characters 1849 '^' or '$'. 1851 Character Function 1852 --------- -------- 1854 Matches itself 1856 . Matches any character 1858 a* Matches zero or more 'a' 1860 [ab] Matches 'a' or 'b' 1862 [a-c] Matches 'a', 'b' or 'c' 1864 ^ Matches beginning of 1865 a token 1867 $ Matches end of a token 1869 Examples 1870 --------- 1872 String Matches Matches not 1873 ------- ------- ----------- 1874 hello xhelloy heello 1875 h.llo hello helio 1876 h.*o hello helloa 1877 h[a-f]llo hello hgllo 1878 ^he.* hello ehello 1879 .*lo$ hello helloo