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: 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.