NNaammeesseerrvveerr SSeerrvveerr--CClliieenntt LLaanngguuaaggee
                        by Steven Dorner
                    Computing Services Office
                     University of Illinois
                             6/1/89

IInnttrroodduuccttiioonn

The language (or _p_r_o_t_o_c_o_l, if you prefer) used between the CSO
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.

GGeenneerraall FFoorrmmaatt

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
_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-
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 the string (ex-
cept ``"'').  In addition, the sequences ``0' and ``'' may be
used to mean newline and tab, respectively.

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:
          _n_u_m_b_e_r:_r_e_s_p_o_n_s_e
Multiline responses should preface the number with a minus sign
(``-'') on all lines of the response but the last.

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
field in the request is objectionable, that field should be iden-
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-
tion, and may vary from the examples given here.

As for FTP, numerical responses will be in the range 100-599,
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.

TThhee CCoommmmaannddss

qquueerryy [[ffiieelldd==]]vvaalluuee...... [[rreettuurrnn ffiieelldd......]]
     This is the basic client request.  It does not require (in
     the common case) any identification from the client.  En-
     tries whose fields match the given values will be found, and
     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
     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 to
     login to the Nameserver.  Values containing newlines will be
     broken into lines and printed one line per response.

     Examples:
          qquueerryy nnaammee==ddoorrnneerr pphhoonnee==33--33333399 rreettuurrnn aalliiaass
          200:1:alias:sdorner

          qquueerryy aalliiaass==ssddoorrnneerr
          -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

          qquueerryy ddoorrnneerr rreettuurrnn aalliiaass ""hhoommee pphhoonnee""
          200-:1:alias:adorner
          -508:1:home phone:This field is not present.
          -200:2:alias:anotherdorner
          -200:2:home phone:555-1212
          -200:3:alias:sdorner
          508:3:home phone:This field is not present.

          qquueerryy aalliiaass==ssddoorrnneerr rreettuurrnn uunniivviidd
          503:univid:You are not authorized for this information.

          qquueerryy nnaammee==ddoorrnneerr ""vvmmss lloovvee""==hhiigghh rreettuurrnn aalliiaass














          501:No matches.

cchhaannggee [[ffiieelldd==]]vvaalluuee...... mmaakkee ffiieelldd==vvaalluuee......
     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, Adjacent
     double quotes (``""'') should be used.   Fields marked _e_n_-
     _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:
          cchhaannggee aalliiaass==ssddoorrnneerr mmaakkee aalliiaass==ddrrddeeaatthh eemmaaiill==uuxxqq
          200:Ok

          cchhaannggee aalliiaass==ssddoorrnneerr mmaakkee aalliiaass==ddrrddeeaatthh
          506:change: must be logged in.

          cchhaannggee sstteevveenn ddoorrnneerr mmaakkee hhoouurrss==""""
          200:Ok

          cchhaannggee nnaammee==iikkeennbbeerrrryy pphhoonnee==333333--33333399
          510:ikenberry:You may not change this entry.

llooggiinn aalliiaass
aannsswweerr ccooddee
     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
     (unless the user is very good at encrypting text).

     Examples:
          llooggiinn ss__ddoorrnneerr
          301:dkeiigjasdvvnmnmeigh
          aannsswweerr eewwiittuueeggnnddvvbbnnggkkggddffkkggll
          200:Hello s_dorner!

          llooggiinn ss__ddoorrnneerr
          301:eiituerwbfncvkfdk;efdgi;
          aannsswweerr eewwiittuueeggnnddvvbbnnggkkggddffkkggll
          500:Die, hacker scum!

llooggoouutt
      Any user identity established with a previous login will be
     forgotten.  The connection is not closed, however.















     Examples:
          llooggoouutt
          200:Ok

ffiieellddss [[ffiieelldd......]]
     With no arguments, echoes the contents of the NameServer's
     fields.config file.  Otherwise, descriptions of the named
     fields are given.

     Examples:
          ffiieellddss
          200:<too verbose to print here>

aadddd ffiieelldd==vvaalluuee......
     Creates a nameserver entry with the given fields.  Only cer-
     tain users will be allowed to execute this command

     Examples:
          aadddd nnaammee==""ddoorrnneerr sstteevveenn cc"" aalliiaass==ssddoorrnneerr
          200:Ok.

          aadddd aalliiaass==ssddoorrnneerr
          509:"sdorner":Alias already in use.

          aadddd aalliiaass==ccddoorrnneerr
          511:You are not authorized to add entries.

ddeelleettee [[ffiieelldd==]]vvaalluuee......
     Deletes one or more nameserver entries.  Most people may not
     delete (even their own) entries.

     Examples:
          ddeelleettee aalliiaass==ssddoorrnneerr
          200:Ok.

          ddeelleettee aalliiaass==ssddoorrnneerr
          513:sdorner:You may not delete this.

sseett ooppttiioonn[[==vvaalluuee]]......
     Sets an option for this nameserver session.

     Examples:
          sseett tteerrssee==ooffff
          200:Ok.

          sseett mmaaxx==22000000
          512:max:Value out of bounds.

qquuiitt
     Ends a nameserver session.

     Examples:














          qquuiitt
          200:Bye!
































































                   Appendix A-Command Summary

qquueerryy [[ffiieelldd==]]vvaalluuee...... [[rreettuurrnn ffiieelldd......]]
cchhaannggee [[ffiieelldd==]]vvaalluuee...... mmaakkee ffiieelldd==vvaalluuee......
llooggiinn aalliiaass
aannsswweerr ccooddee
llooggoouutt
ffiieellddss [[ffiieelldd......]]
aadddd ffiieelldd==vvaalluuee......
ddeelleettee [[ffiieelldd==]]vvaalluuee......
sseett ooppttiioonn[[==vvaalluuee]]......
qquuiitt






















































                     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.
           503 Not authorized for requested information.
           504 Not authorized for requested search criteria.
           505 Not authorized to change requested field.
           506 Request refused; must be encrypted.
           507 Field does not exist.
           508 Field is not present in requested entry.
           509 Alias already in use.
           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.

























.