TThhee CCCCSSOO NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt PPrroottooccooll 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 _I_n_t_r_o_d_u_c_t_i_o_n 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. _G_e_n_e_r_a_l _F_o_r_m_a_t 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, _F_i_l_e _T_r_a_n_s_f_e_r _P_r_o_t_o_c_o_l (_F_T_P), J. Postel and J. Reynolds. 22 TThhee CCCCSSOO NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt PPrroottooccooll 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 _d_o_u_b_l_e 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: _r_e_s_u_l_t _c_o_d_e:[[_e_n_t_r_y _i_n_d_e_x:]][[_f_i_e_l_d _n_a_m_e:]]_t_e_x_t 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, _T_e_l_n_e_t _P_r_o_t_o_c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n, J. Postel. TThhee CCCCSSOO NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt PPrroottooccooll 33 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. _T_h_e _C_o_m_m_a_n_d_s 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 _q_i 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 _T_h_e _C_C_S_O _N_a_m_e_s_e_r_v_e_r - _A _D_e_s_c_r_i_p_t_i_o_n, S. Dorner and P. Pomes, for a description of Nameserver modes. 44 TThhee CCCCSSOO NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt PPrroottooccooll _E_x_a_m_p_l_e_s 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 TThhee CCCCSSOO NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt PPrroottooccooll 55 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 _q_i program is being run directly from a terminal. This encryption should be done with the password of the logged in user. _E_x_a_m_p_l_e_s 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. _E_x_a_m_p_l_e_s login s_dorner 301:dkeiigjasdvvnmnmeigh answer ewituegndvbngkgdfkgl 200:s-dorner:Hi how are you? login s-dorner 301:?;_?DB,F9X;8O=H8Y?#(^='