              o                 NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt LLaanngguuaaggee (                         by Steven Dorner-                     Computing Services Office +                      University of Illinois #                              6/1/89   $ IInnttrroodduuccttiioonn  N The language (or _p_r_o_t_o_c_o_l, if you prefer) used between the CSOA Nameserver and its clients is meant to be relatively easy to gen- > erate and to parse, so that it can be used by programs.  It is< also meant to be not too onerous for use by humans directly.  ( GGeenneerraall FFoorrmmaatt  A The general format of the language is a request/response language ? like that of FTP.  The conversation is in netascii, with a car- < riage return-linefeed pair separating the lines.  The client? makes requests, and the server responds to them.  This allows a L _t_e_l_n_e_t client to connect to the Nameserver so that users may use< the Nameserver without any intervening client, if they wish.  ? A request begins with a keyword, and may have zero or more key- A words or values, separated by spaces, tabs, or newlines, and fol- < lowed by a carriage return-linefeed pair.  Values containingH spaces, tabs or newlines should be enclosed in _d_o_u_b_l_e quotesA (``"'').  Any printable characters may be used in the string (ex- = cept ``"'').  In addition, the sequences ``0' and ``'' may be + used to mean newline and tab, respectively.   7 Like FTP, numerical values will be used to indicate the < NameServer's response to requests.  Unlike FTP, data will be: passed on the same connection as commands.  The format for responses will be as follows: 5           _n_u_m_b_e_r:_r_e_s_p_o_n_s_e ? Multiline responses should preface the number with a minus sign 2 (``-'') on all lines of the response but the last.  A Notice that since more than one specific piece of information may @ be manipulated by a particular command, it is possible for parts> of a command to succeed, while other parts of the same command@ fail.  This will be handled as a single continued response, with? the result code changing as appropriate.  Also, if a particular A field in the request is objectionable, that field should be iden- A tified after the colon following the result code.  The field name > should be separated by a colon from the text of the error mes-> sage.  The text of the message is primarily for human consump-0 tion, and may vary from the examples given here.  = As for FTP, numerical responses will be in the range 100-599, 7 where the leading digit has the following significance:       1: In progress                                   2: Success       3: More information needed       4: Temporary failure       5: Permanent failure = Specific numbers have meanings to some commands; all commands  obey the general scheme.  = In practice, almost every command will generate more than one > line of response; every client should be prepared to deal with@ such continued responses.  It is worthwhile to note that no com-@ mand is finished unless the result code (treated as a signed in-' teger) is greater than or equal to 200.   " TThhee CCoommmmaannddss  r qquueerryy [[ffiieelldd==]]vvaalluuee...... [[rreettuurrnn ffiieelldd......]]?      This is the basic client request.  It does not require (in >      the common case) any identification from the client.  En-A      tries whose fields match the given values will be found, and A      the requested fields printed.  If no query fields are speci- >      fied, the name field is assumed.  If no return fields are=      specified, default fields will be returned.  Fields from A      each entry will be prefaced with a sequence number, a colon, '      the field name, and another colon.   @      Note that to view some sensitive fields, it is necessary toA      login to the Nameserver.  Values containing newlines will be 9      broken into lines and printed one line per response.         Examples:           qquueerryy nnaammee==ddoorrnneerr pphhoonnee==33--33333399 rreettuurrnn aalliiaass            200:1:alias:sdorner   A           qquueerryy aalliiaass==ssddoorrnneerr #           -200:1:name:Steven Dorner            -200:1:alias:sdorner           -200:1:phone:333-3339            200:1:address:189 DCL +           200:1:address:1304 W. Springfield   r           qquueerryy ddoorrnneerr rreettuurrnn aalliiaass ""hhoommee pphhoonnee""           200-:1:alias:adorner6           -508:1:home phone:This field is not present.$           -200:2:alias:anotherdorner$           -200:2:home phone:555-1212           -200:3:alias:sdorner5           508:3:home phone:This field is not present.   g           qquueerryy aalliiaass==ssddoorrnneerr rreettuurrnn uunniivviidd A           503:univid:You are not authorized for this information.              qquueerryy nnaammee==ddoorrnneerr ""vvmmss lloovvee""==hhiigghh rreettuurrnn aalliiaass                                       501:No matches.   { cchhaannggee [[ffiieelldd==]]vvaalluuee...... mmaakkee ffiieelldd==vvaalluuee...... A      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 user @      must be logged in for change to work, and must have the au-@      thority to change the fields in the entries selected by the>      query portion.  If it is desired delete a field, AdjacentE      double quotes (``""'') should be used.   Fields marked _e_n_- G      _c_r_y_p_t_e_d must be encrypted before transmission to the ?      Nameserver.  This encryption should be done with the pass-        word of the logged in user.        Examples:           cchhaannggee aalliiaass==ssddoorrnneerr mmaakkee aalliiaass==ddrrddeeaatthh eemmaaiill==uuxxqq            200:Ok  y           cchhaannggee aalliiaass==ssddoorrnneerr mmaakkee aalliiaass==ddrrddeeaatthh (           506:change: must be logged in.  h           cchhaannggee sstteevveenn ddoorrnneerr mmaakkee hhoouurrss==""""           200:Ok  r           cchhaannggee nnaammee==iikkeennbbeerrrryy pphhoonnee==333333--333333996           510:ikenberry:You may not change this entry.   llooggiinn aalliiaass  aannsswweerr ccooddee >      This is used to identify the user of a particular connec-@      tion.  The NameServer will respond with a random challenge,>      which must be returned in encrypted form.  The encryption@      key will be a password known to both the NameServer and the?      user (or user's trusted host).  Note that this scheme pre- ?      cludes the use of login through a direct telnet connection 7      (unless the user is very good at encrypting text).         Examples:2           llooggiinn ss__ddoorrnneerr"           301:dkeiigjasdvvnmnmeighY           aannsswweerr eewwiittuueeggnnddvvbbnnggkkggddffkkggll            200:Hello s_dorner!   2           llooggiinn ss__ddoorrnneerr&           301:eiituerwbfncvkfdk;efdgi;Y           aannsswweerr eewwiittuueeggnnddvvbbnnggkkggddffkkggll            500:Die, hacker scum!    llooggoouuttA       Any user identity established with a previous login will be 7      forgotten.  The connection is not closed, however.                                     Examples:           llooggoouutt           200:Ok  1 ffiieellddss [[ffiieelldd......]] ?      With no arguments, echoes the contents of the NameServer's >      fields.config file.  Otherwise, descriptions of the named      fields are given.        Examples:           ffiieellddss)           200:<too verbose to print here>   4 aadddd ffiieelldd==vvaalluuee......A      Creates a nameserver entry with the given fields.  Only cer- 7      tain users will be allowed to execute this command         Examples:z           aadddd nnaammee==""ddoorrnneerr sstteevveenn cc"" aalliiaass==ssddoorrnneerr           200:Ok.   ;           aadddd aalliiaass==ssddoorrnneerr -           509:"sdorner":Alias already in use.   ;           aadddd aalliiaass==ccddoorrnneerr 4           511:You are not authorized to add entries.  C ddeelleettee [[ffiieelldd==]]vvaalluuee...... A      Deletes one or more nameserver entries.  Most people may not %      delete (even their own) entries.         Examples:D           ddeelleettee aalliiaass==ssddoorrnneerr           200:Ok.   D           ddeelleettee aalliiaass==ssddoorrnneerr.           513:sdorner:You may not delete this.  = sseett ooppttiioonn[[==vvaalluuee]]...... 0      Sets an option for this nameserver session.        Examples:/           sseett tteerrssee==ooffff            200:Ok.   ,           sseett mmaaxx==22000000&           512:max:Value out of bounds.   qquuiitt      Ends a nameserver session.         Examples:                                       qquuiitt           200:Bye!                                                                                                                                -                    Appendix A-Command Summary   r qquueerryy [[ffiieelldd==]]vvaalluuee...... [[rreettuurrnn ffiieelldd......]]{ cchhaannggee [[ffiieelldd==]]vvaalluuee...... mmaakkee ffiieelldd==vvaalluuee......  llooggiinn aalliiaass  aannsswweerr ccooddee  llooggoouutt1 ffiieellddss [[ffiieelldd......]] 4 aadddd ffiieelldd==vvaalluuee......C ddeelleettee [[ffiieelldd==]]vvaalluuee...... = sseett ooppttiioonn[[==vvaalluuee]]......  qquuiitt                                                                                                            ,                      Appendix B-Result Codes    %            100 In progress (general). '            101 Echo of current command.   !            200 Success (general). -            201 Database ready, but read only.   *            300 More information (general).#            301 Encrypt this string.   )            400 Temporary error (general).   )            500 Permanent error (general). #            501 No matches to query. )            502 Too many matches to query. 8            503 Not authorized for requested information.<            504 Not authorized for requested search criteria.8            505 Not authorized to change requested field.2            506 Request refused; must be encrypted.$            507 Field does not exist.7            508 Field is not present in requested entry. $            509 Alias already in use.3            510 Not authorized to change this entry. -            511 Not authorized to add entries.             512 Illegal value.             513 Unknown option.            514 Unknown command. )            515 No indexed field in query. ,            516 No authorization for request.>            517 Operation failed because database is read only.;            518 Too many entries selected by change command.             599 Syntax error.                                                  