The CCSO Nameserver Server-Client Protocol by Steven Dorner s-dorner@uiuc.edu Computer and Communications Services Office University of Illinois at Urbana April 2, 1990 updated by Paul Pomes paul-pomes@uiuc.edu Computer and Communications Services Office University of Illinois at Urbana August 2, 1992 Introduction This document describes the protocol used by the CCSO Nameserver. It provides all the information necessary to write a program that interfaces with the Nameserver, or for a human to speak directly to the Nameserver. While CCSO provides a client program for our Nameserver, we also expect the Nameserver to be used from programs other than this client. First, our client does not run on every system. Secondly, the Nameserver is potentially of use for more than just human lookup of information; other programs (such as mail delivery agents) may wish to use the Nameserver. This was kept in mind when designing the protocol used by the Nameserver. It is fairly easy to generate and parse (if not totally regular), and should prove easy to incorporate in any program. General Format The general format of the protocol is request/response, like that of FTP;[1] the client makes requests, and the server responds to them. The conversation is in "netascii", with a carriage ____________________ Converted to portable n/troff format using the -me macros from funky Next WriteNow format (icch). [1] See RFC-959, File Transfer Protocol (FTP), J. Postel and J. Reynolds. 2 The CCSO Nameserver Server-Client Protocol return-linefeed pair[2] separating the lines, as in telnet.[3] This allows a user to use the Nameserver with any telnet client, if they wish. A request begins with a keyword, and may have zero or more key- words or values, separated by spaces, tabs, or newlines, and fol- lowed by a carriage return-linefeed pair. Values containing spaces, tabs or newlines should be enclosed in double quotes (`"'). Any printable characters may be used in a quoted string (except `"'). In addition, the sequences "\n", "\t", "\"", and "\\" may be used to mean newline, tab, double quote, and backslash, respectively. Like FTP, numerical values are used to indicate the Nameserver's response to requests. Unlike FTP, data is passed on the same connection as commands. The format for responses is as follows: result code:[entry index:][field name:]text Multiline responses should preface each line of the response with the appropriate result code, negated (prefaced with "-"), on all lines of the response but the last. If a particular command can apply to more than one entry, responses involving individual entries will have an entry index directly following the result code. This index will begin with 1, and be incremented each time a new entry is being referred to. Commands that can apply to more than one field will have the name of the field to which the response applies directly following the entry index. The text of the response will be either an error message intended for human consumption, or data from the Nameserver. Whitespace (spaces or tabs) may appear anywhere in the response. Since more than one specific piece of information may be manipu- lated by a particular command, it is possible for parts of a com- mand to succeed, while other parts of the same command fail. This situation is handled as a single multi-line response, with the result code changing as appropriate. As for FTP, numerical responses are in the range 100-599 (or from -599 to -100 for multiline responses), where the leading digit has the following significance: 1: In progress 2: Success 3: More information needed 4: Temporary failure; it may be worthwile to try again. 5: Permanent failure ____________________ [2] The carriage return is optional. [3] See RFC-854, Telnet Protocol Specification, J. Postel. The CCSO Nameserver Server-Client Protocol 3 Specific numbers have meanings to some commands; all commands obey the general scheme. Many commands generate more than one line of response; every client should be prepared to deal with such continued responses. It is worthwhile to note that a command is finished when and only when the result code on a response line (treated as a signed integer) is greater than or equal to 200. Keywords must be given in lower case; case in the values of fields is preserved, although queries are not case-sensitive. The Commands query [field=]value. . . [return field1 [field2]] ph [field=]value. . . [return field1 [field2]] This is the basic client request. It may be used in any of the Nameserver modes.[4] Entries whose fields match the given values will be found, and the requested fields printed. If no field name is specified in the query part of the command, the "name" field is assumed. If no fields are specified with a return clause, a default set of fields will be returned. Fields from each entry will be prefaced with an entry index, a colon, the field name, and another colon. If the special field name "all" is given in the return clause, all fields from the entry will be printed (subject to normal constraints with regard to Nameserver mode and field properties). Note that to view some sensitive fields, it is necessary to use Nameserver login mode. Note also that fields whose descriptions include the property Encrypt cannot be printed by the server. Values containing newlines will be broken into lines and printed one line per response. The second number on each response is the entry index; it is incremented each time the response refers to a new entry. Some implementations of qi return a 102 response before the actual entries, giving the number of entries found; be prepared to see or not see this response. "Query" and "ph" are synonyms. ____________________ [4] See The CCSO Nameserver - A Description, S. Dorner and P. Pomes, for a description of Nameserver modes. 4 The CCSO Nameserver Server-Client Protocol Examples query name=dorner phone=244-1765 -200:1: alias: s-dorner -200:1: name: dorner steven c. -200:1: email: dorner@garcon.cso.uiuc.edu -200:1: phone: (w) 244-1765 -200:1: address: 181 DCL, MC 256 -200:1: : 1201 W. Washington, C, 61821 -200:1: department: computing services office -200:1: title: res programmer -200:1: nickname: Steve -200:1: hours: 8-4 weekdays 200:Ok. query alias=s-dorner -200:1: alias: s-dorner -200:1: name: dorner steven c. -200:1: email: dorner@garcon.cso.uiuc.edu -200:1: phone: (w) 244-1765 -200:1: address: 181 DCL, MC 256 -200:1: : 1201 W. Washington, C, 61821 -200:1: department: computing services office -200:1: title: res programmer -200:1: nickname: Steve -200:1: hours: 8-4 weekdays 200:Ok. query dorner return alias hours -200:1: alias: m-dorner -508:1: hours: Not present in entry. -200:2: alias: j-dorner -508:2: hours: Not present in entry. -200:3: alias: s-dorner -200:3: hours: 8-4 weekdays -200:4: alias: j-dorner1 -508:4: hours: Not present in entry. 200:Ok. query alias=s-dorner return id -503:1: id: You may not view this field. 200:Ok. query name=dorner address=moon 501:No matches to your query. change [field=]value. . . make field=value Change looks much like query. The entries to be changed are specified as in query. They keyword make separates the search criteria from the fields to be changed. The change command works in hero mode, or in login mode if applied to fields whose The CCSO Nameserver Server-Client Protocol 5 description contain the Change property[5] in the entry of the logged-in user. If it is desired remove a field, Adjacent double quotes ("") should be given as the "new value" of the field. Fields whose descriptions include the property Encrypted must be encrypted before transmission to the Nameserver, unless the qi program is being run directly from a terminal. This encryption should be done with the password of the logged in user. Examples change alias=s-dorner make hours="when the sun shines" 506:You must be logged in to use this command. change steven dorner make hours="" 200:1 entry changed. change steven dorner make name="Dr. Strangelove" -505:name:you may not change this field. 500:1 entry found, none changed. change ikenberry make email=zzz@xxx 518:Too many entries (3) selected; limit is 2. change stanley ikenberry make email=zzz@xxx -510:s-ikenberry:You may not change this entry. 500:1 entry found, none changed. login alias answer code clear password This is used to enter login or hero mode. The Nameserver will respond with a random challenge, which may be returned in encrypted form via the answer command. The encryption key will be a password known to both the Nameserver and the user. Alter- nately, the client may respond with the clear command, and give the proper password in clear text. This is not the recommended method, and is only provided for the lazy protocol implementor. Examples login s_dorner 301:dkeiigjasdvvnmnmeigh answer ewituegndvbngkgdfkgl 200:s-dorner:Hi how are you? login s-dorner 301:?;_?DB,F9X;8O=H8Y?#(^='