Документ взят из кэша поисковой машины. Адрес оригинального документа : http://mirror.msu.net/pub/rfc-editor/rfc-ed-all/pdfrfc/rfc2229.txt.pdf Дата изменения: Wed Mar 27 23:25:07 2002 Дата индексирования: Tue Oct 2 18:57:47 2012 Кодировка: Поисковые слова: star trail

Network Working Group Request for Comments: 2229 Category: Informational

R. Faith U. North Carolina, Chapel Hill B. Martin Miranda Productions October 1997

A Dictionary Server Protocol

Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1997). Abstract The Dictionary Server Protocol (DICT) is a TCP transaction based query/response protocol that allows a client to access dictionary definitions from a set of natural language dictionary databases. Table of Contents 1. 1.1. 2. 2.1. 2.2. 2.3. 2.4. 2.4.1. 2.4.2. 2.4.3. 3. 3.1. 3.2. 3.3. 3.4. 3.5. 3.5.1. 3.5.2. 3.5.3. 3.5.4. 3.6. Introduction ......................................... Requirements ......................................... Protocol Overview .................................... Link Level ........................................... Lexical Tokens ....................................... Commands ............................................. Responses ............................................ Status Responses ..................................... General Status Responses ............................. Text Responses ....................................... Command and Response Details ......................... Initial Connection ................................... The DEFINE Command ................................... The MATCH Command .................................... A Note on Virtual Databases .......................... The SHOW Command ..................................... SHOW DB .............................................. SHOW STRAT ........................................... SHOW INFO ............................................ SHOW SERVER .......................................... The CLIENT Command ................................... 2 3 3 3 3 4 5 5 6 6 7 7 9 10 12 13 13 13 14 14 15 All Rights Reserved.

Faith & Martin

Informational

[Page 1]


RFC 2229

A Dictionary Server Protocol

October 1997

3.7. 3.8. 3.9. 3.10. 3.10.1. 3.11. 3.12. 4. 5. 6. 6.1. 6.2. 7. 8. 8.1. 8.2. 8.3. 8.4. 9. 10. 11. 12. 13. 1.

The STATUS Command ................................... The HELP Command ..................................... The QUIT Command ..................................... The OPTION Command ................................... OPTION MIME .......................................... The AUTH Command ..................................... The SASLAUTH Command ................................. Command Pipelining ................................... URL Specification .................................... Extensions ........................................... Experimental Command Syntax .......................... Experimental Commands and Pipelining ................. Summary of Response Codes ............................ Sample Conversations ................................. Sample 1 - HELP, DEFINE, and QUIT commands ........... Sample 2 - SHOW commands, MATCH command .............. Sample 3 - Server downtime ........................... Sample 4 - Authentication ............................ Security Considerations .............................. References ........................................... Acknowledgements ..................................... Authors' Addresses ................................... Full Copyright Statement .............................

15 15 16 16 16 18 18 20 20 22 22 22 23 23 24 25 26 26 26 27 29 29 30

Introduction For many years, the Internet community has relied on the "webster" protocol for access to natural language definitions. The webster protocol supports access to a single dictionary and (optionally) to a single thesaurus. In recent years, the number of publicly available webster servers on the Internet has dramatically decreased. Fortunately, several freely-distributable dictionaries and lexicons have recently become available on the Internet. However, these freely-distributable databases are not accessible via a uniform interface, and are not accessible from a single site. They are often small and incomplete individually, but would collectively provide an interesting and useful database of English words. Examples include the Jargon file [JARGON], the WordNet database [WORDNET], MICRA's version of the 1913 Webster's Revised Unabridged Dictionary [WEB1913], and the Free Online Dictionary of Computing [FOLDOC]. Translating and non-English dictionaries are also becoming available (for example, the FOLDOC dictionary is being translated into Spanish).

Faith & Martin

Informational

[Page 2]


RFC 2229

A Dictionary Server Protocol

October 1997

The webster protocol is not suitable for providing access to a large number of separate dictionary databases, and extensions to the current webster protocol were not felt to be a clean solution to the dictionary database problem. The DICT protocol is designed to provide access to multiple databases. Word definitions can be requested, the word index can be searched (using an easily extended set of algorithms), information about the server can be provided (e.g., which index search strategies are supported, or which databases are available), and information about a database can be provided (e.g., copyright, citation, or distribution information). Further, the DICT protocol has hooks that can be used to restrict access to some or all of the databases. 1.1. Requirements

In this document, we adopt the convention discussed in Section 1.3.2 of [RFC1122] of using the capitalized words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the significance of each particular requirement specified in this document. In brief: "MUST" (or "REQUIRED") means that the item is an absolute requirement of the specification; "SHOULD" (or "RECOMMENDED") means there may exist valid reasons for ignoring this item, but the full implications should be understood before doing so; and "MAY" (or "OPTIONAL") means that his item is optional, and may be omitted without careful consideration. 2. 2.1. Protocol Overview Link Level

The DICT protocol assumes a reliable data stream such as provided by TCP. When TCP is used, a DICT server listens on port 2628. This server is only an interface between programs and the dictionary databases. It does not perform any user interaction or presentation-level functions. 2.2. Lexical Tokens

Commands and replies are composed of characters from the UCS character set [ISO10646] using the UTF-8 [RFC2044] encoding. specifically, using the grammar conventions from [RFC822]:

More

Faith & Martin

Informational

[Page 3]


RFC 2229

A Dictionary Server Protocol

October 1997

CHAR CTL CR LF SPACE HTAB <"> <'> CRLF WS dqstring dqtext sqstring sqtext quoted-pair atom string word description text 2.3. Commands

= = = = = = = = = = = = = = = = = = = =

; ( Octal, Decimal.) ;( 177, 127.) ; ( 15, 13.) ;( 12, 10.) ;( 40, 32.) ;( 11, 9.) ;( 42, 34.) ;( 47, 39.) CR LF 1*(SPACE / HTAB) <"> , "\", *(dqtext/quoted-pair) CHAR except <'>, "\", CHAR <"> and CTLs> <'> and CTLs>

1*, <">, and "\"> * * * *

Commands consist of a command word followed by zero or more parameters. Commands with parameters must separate the parameters from each other and from the command by one or more space or tab characters. Command lines must be complete with all required parameters, and may not contain more than one command. Each command line must be terminated by a CRLF. The grammar for commands is: command cmd-word cmd-param database strategy = = = = = cmd-word * atom database / strategy / word atom atom

Commands are not case sensitive.

Faith & Martin

Informational

[Page 4]


RFC 2229

A Dictionary Server Protocol

October 1997

Command lines MUST NOT exceed 1024 characters in length, counting all characters including spaces, separators, punctuation, and the trailing CRLF. There is no provision for the continuation of command lines. Since UTF-8 may encode a character using up to 6 octets, the command line buffer MUST be able to accept up to 6144 octets. 2.4. Responses

Responses are of two kinds, status and textual. 2.4.1. Status Responses

Status responses indicate the server's response to the last command received from the client. Status response lines begin with a 3 digit numeric code which is sufficient to distinguish all responses. Some of these may herald the subsequent transmission of text. The first digit of the response broadly indicates the success, failure, or progress of the previous command (based generally on [RFC640,RFC821]): 1yz 2yz 3yz 4yz 5yz Positive Positive Positive Transient Permanent Preliminary reply Completion reply Intermediate reply Negative Completion reply Negative Completion reply

The next digit in the code indicates the response category: x0z x1z x2z x3z x4z x5z Syntax Information (e.g., help) Connections Authentication Unspecified as yet DICT System (These replies indicate the status of the receiver DICT system vis-a-vis the requested transfer or other DICT system action.) x8z - Nonstandard (private implementation) extensions The exact response codes that should be expected from each command are detailed in the description of that command. Certain status responses contain parameters such as numbers and strings. The number and type of such parameters is fixed for each response code to simplify interpretation of the response. Other status responses do not require specific text identifiers. Parameter -

Faith & Martin

Informational

[Page 5]


RFC 2229

A Dictionary Server Protocol

October 1997

requirements are detailed in the description of relevant commands. Except for specifically detailed parameters, the text following response codes is server-dependent. Parameters are separated from the numeric response code and from each other by a single space. All numeric parameters are decimal, and may have leading zeros. All string parameters MUST conform to the "atom" or "dqstring" grammar productions. If no parameters are present, and the server implementation provides no implementation-specific text, then there MAY or MAY NOT be a space after the response code. Response codes not specified in this standard may be used for any installation-specific additional commands also not specified. These should be chosen to fit the pattern of x8z specified above. The use of unspecified response codes for standard commands is prohibited. 2.4.2. General Status Responses

In response to every command, the following general status responses are possible: 500 501 502 503 420 421 2.4.3. Syntax Syntax Command Command Server Server error, command not recognized error, illegal parameters not implemented parameter not implemented temporarily unavailable shutting down at operator request

Text Responses

Before text is sent a numeric status response line, using a 1yz code, will be sent indicating text will follow. Text is sent as a series of successive lines of textual matter, each terminated with a CRLF. A single line containing only a period (decimal code 46, ".") is sent to indicate the end of the text (i.e., the server will send a CRLF at the end of the last line of text, a period, and another CRLF). If a line of original text contained a period as the first character of the line, that first period is doubled by the DICT server. Therefore, the client must examine the first character of each line received. Those that begin with two periods must have those two periods collapsed into one period. Those that contain only a single period followed by a CRLF indicate the end of the text response.

Faith & Martin

Informational

[Page 6]


RFC 2229

A Dictionary Server Protocol

October 1997

If the OPTION MIME command has been given, all textual responses will be prefaced by a MIME header [RFC2045] followed by a single blank line (CRLF). See section 3.10.1 for more details on OPTION MIME. Following a text response, a 2yz response code will be sent. Text lines MUST NOT exceed 1024 characters in length, counting all characters including spaces, separators, punctuation, the extra initial period (if needed), and the trailing CRLF. Since UTF-8 may encode a character using up to 6 octets, the text line input buffer MUST be able to accept up to 6144 octets. By default, the text characters from the [RFC2044] encoding. preserving the full Clients and servers fashion. 3. of the definitions MUST be composed of UCS character set [ISO10644] using the UTF-8 The UTF-8 encoding has the advantage of range of 7-bit US ASCII [USASCII] values. MUST support UTF-8, even if only in some minimal

Command and Response Details Below, each DICT command and appropriate responses are detailed. Each command is shown in upper case for clarity, but the DICT server is case-insensitive. Except for the AUTH and SASLAUTH commands, every command described in this section MUST be implemented by all DICT servers.

3.1.

Initial Connection

When a client initially connects to a DICT server, a code 220 is sent if the client's IP is allowed to connect: 220 text capabilities msg-id The code 220 is a banner, usually containing host name and DICT server version information. The second-to-last sequence of characters in the banner is the optional capabilities string, which will allow servers to declare support for extensions to the DICT protocol. The capabilities string is defined below: capabilities = msg-atom = ["<" msg-atom *("." msg-atom) ">"] 1*", ".", and "\">

Faith & Martin

Informational

[Page 7]


RFC 2229

A Dictionary Server Protocol

October 1997

Individual capabilities are described by a single msg-atom. For example, the string might be used to describe a server that supports extensions which allow HTML or compressed output. Capability names beginning with "x" or "X" are reserved for experimental extensions, and SHOULD NOT be defined in any future DICT protocol specification. Some of these capabilities may inform the client that certain functionality is available or can be requested. The following capabilities are currently defined: mime auth kerberos_v4 gssapi skey external The The The The The The OPTION MIME command is supported AUTH command is supported SASL Kerberos version 4 mechanism is supported SASL GSSAPI [RFC2078] mechanism is supported SASL S/Key [RFC1760] mechanism is supported SASL external mechanism is supported

The last sequence of characters in the banner is a msg-id, similar to the format specified in [RFC822]. The simplified description is given below: msg-id spec local-part domain = = = = "<" spec ">" ; Unique message id local-part "@" domain msg-atom *("." msg-atom) msg-atom *("." msg-atom)

Note that, in contrast to [RFC822], spaces and quoted pairs are not allowed in the msg-id. This restriction makes the msg-id much easier for the client to locate and parse but does not significantly decrease any security benefits, since the msg-id may be arbitrarily long (as bounded by the response length limits set forth elsewhere in this document). Note also that the open and close brackets are part of the msg-id and should be included in the string that is used to compute the MD5 checksum. This message id will be used by the client when formulating the authentication string used in the AUTH command. If the client's IP is not allowed to connect, then a code 530 is sent instead: 530 Access denied Transient failure responses are also possible: 420 Server temporarily unavailable 421 Server shutting down at operator request

Faith & Martin

Informational

[Page 8]


RFC 2229

A Dictionary Server Protocol

October 1997

For example, response code 420 should be used if the server cannot currently fork a server process (or cannot currently obtain other resources required to proceed with a usable connection), but expects to be able to fork or obtain these resources in the near future. Response code 421 should be used when the server has been shut down at operator request, or when conditions indicate that the ability to service more requests in the near future will be impossible. This may be used to allow a graceful operator-mediated temporary shutdown of a server, or to indicate that a well known server has been permanently removed from service (in which case, the text message might provide more information). 3.2. The DEFINE Command

DEFINE database word 3.2.1. Description

This command will look up the specified word in the specified database. All DICT servers MUST implement this command. If the database name is specified with an exclamation point (decimal code 33, "!"), then all of the databases will be searched until a match is found, and all matches in that database will be displayed. If the database name is specified with a star (decimal code 42, "*"), then all of the matches in all available databases will be displayed. In both of these special cases, the databases will be searched in the same order as that printed by the "SHOW DB" command. If the word was not found, then status code 552 is sent. If the word was found, then status code 150 is sent, indicating that one or more definitions follow. For each definition, status code 151 is sent, followed by the textual body of the definition. The first three space-delimited parameters following status code 151 give the word retrieved, the name of the database (which is the same as the first column of the SHOW DB command), and a short description for the database (which is the same as the second column of the SHOW DB command). The short name is suitable for printing as: From name: before the definition is printed. for the user. This provides source information

Faith & Martin

Informational

[Page 9]


RFC 2229

A Dictionary Server Protocol

October 1997

The textual body of each definition is terminated with a CRLF period CRLF sequence. After all of the definitions have This command can provide optional dependent and is not intended to additional information is useful server. 3.2.2. Responses 550 552 150 151 250 Invalid database, use "SHOW DB" for list of databases No match n definitions retrieved - definitions follow word database name - text follows ok (optional timing information here) been sent, status timing information be parsable by the when debugging and code 250 is sent. (which is server client). This tuning the

Response codes 150 and 151 require special parameters as part of their text. The client can use these parameters to display information on the user's terminal. For code 150, parameters 1 indicates the number of definitions retrieved. For code 151, parameter 1 is the word retrieved, parameter 2 is the database name (the first name as shown by "SHOW DB") from which the definition has been retrieved, and parameter 3 is the the short database description (the second column of the "SHOW DB" command). 3.3. The MATCH Command

MATCH database strategy word 3.3.1. Description

This command searches an index for the dictionary, and reports words which were found using a particular strategy. Not all strategies are useful for all dictionaries, and some dictionaries may support additional search strategies (e.g., reverse lookup). All DICT servers MUST implement the MATCH command, and MUST support the "exact" and "prefix" strategies. These are easy to implement and are generally the most useful. Other strategies are server dependent. The "exact" strategy matches a word exactly, although different servers may treat non-alphanumeric data differently. We have found that a case-insensitive comparison which ignores non-alphanumeric

Faith & Martin

Informational

[Page 10]


RFC 2229

A Dictionary Server Protocol

October 1997

characters and which folds whitespace is useful for English-language dictionaries. Other comparisons may be more appropriate for other languages or when using extended character sets. The "prefix" strategy is similar to "exact", except that it only compares the first part of the word. Different servers may implement these algorithms differently. The requirement is that strategies with the names "exact" and "prefix" exist so that a simple client can use them. Other strategies that might be considered by a server implementor are matches based on substring, suffix, regular expressions, soundex [KNUTH73], and Levenshtein [PZ85] algorithms. These last two are especially useful for correcting spelling errors. Other useful strategies perform some sort of "reverse" lookup (i.e., by searching definitions to find the word that the query suggests). If the database name is specified with an exclamation point (decimal code 33, "!"), then all of the databases will be searched until a match is found, and all matches in that database will be displayed. If the database name is specified with a star (decimal code 42, "*"), then all of the matches in all available databases will be displayed. In both of these special cases, the databases will be searched in the same order as that printed by the "SHOW DB" command. If the strategy is specified using then the word will be matched using strategy, which should be the best spell checking. This is usually a algorithm [PZ85]. a period (decimal code 46, "."), a server-dependent default strategy available for interactive derivative of the Levenshtein

If no matches are found in any of the searched databases, then status code 552 will be returned. Otherwise, status code 152 will be returned followed by a list of matched words, one per line, in the form: database word This makes the responses directly useful in a DEFINE command. The textual body of the match list is terminated with a CRLF period CRLF sequence. Following the list, status code 250 is sent, which may include server-specific timing and statistical information, as discussed in the section on the DEFINE command.

Faith & Martin

Informational

[Page 11]


RFC 2229

A Dictionary Server Protocol

October 1997

3.3.2.

Responses 550 551 552 152 250 Invalid database, use "SHOW DB" for list of databases Invalid strategy, use "SHOW STRAT" for a list of strategies No match n matches found - text follows ok (optional timing information here)

Response code 152 requires a special parameter as part of its text. Parameter 1 must be the number of matches retrieved. 3.4. A Note on Virtual Databases

The ability to search all of the provided databases using a single command is given using the special "*" and "!" databases. However, sometimes, a client may want to search over some but not all of the databases that a particular server provides. One alternative is for the client to use the SHOW DB command to obtain a list of databases and descriptions, and then (perhaps with the help of a human), select a subset of these databases for an interactive search. Once this selection has been done once, the results can be saved, for example, in a client configuration file. Another alternative is for the server to provide "virtual" databases which merge several of the regular databases into one. For example, a virtual database may be provided which includes all of the translating dictionaries, but which does not include regular dictionaries or thesauri. The special "*" and "!" databases can be considered as names of virtual databases which provide access to all of the databases. If a server implements virtual databases, then the special "*" and "!" databases should probably exclude other virtual databases (since they merely provide information duplicated in other databases). If virtual databases are supported, they should be listed as a regular database with the SHOW DB command (although, since "*" and "!" are required, they need not be listed). Virtual databases are an implementation-specific detail which has absolutely no impact on the DICT protocol. The DICT protocol views virtual and non-virtual databases the same way. We mention virtual databases here, however, because they solve a problem of database selection which could also have been solved by changes in the protocol. For example, each dictionary could be assigned attributes, and the protocol could be extended to specify searches over databases with certain attributes. However, this needlessly complicates the parsing and analysis that must be performed by the implementation. Further, unless the classification

Faith & Martin

Informational

[Page 12]


RFC 2229

A Dictionary Server Protocol

October 1997

system is extremely general, there is a risk that it would restrict the types of databases that can be used with the DICT protocol (although the protocol has been designed with human-language databases in mind, it is applicable to any read-only database application, especially those with a single semi-unique alphanumeric key and textual data). 3.5. 3.5.1. The SHOW Command SHOW DB

SHOW DB SHOW DATABASES 3.5.1.1. Description

Displays the list of currently accessible databases, one per line, in the form: database description The textual body of the database list is terminated with a CRLF period CRLF sequence. All DICT servers MUST implement this command. Note that some databases may be restricted due to client domain or lack of user authentication (see the AUTH and SASLAUTH commands in sections 3.11 and 3.12). Information about these databases is not available until authentication is performed. Until that time, the client will interact with the server as if the additional databases did not exist. 3.5.1.2. Responses 110 n databases present - text follows 554 No databases present Response code 110 requires a special parameter. Parameter 1 must be the number of databases available to the user. 3.5.2. SHOW STRAT

SHOW STRAT SHOW STRATEGIES

Faith & Martin

Informational

[Page 13]


RFC 2229

A Dictionary Server Protocol

October 1997

3.5.2.1.

Description

Displays the list of currently supported search strategies, one per line, in the form: strategy description The textual body of the strategy list is terminated with a CRLF period CRLF sequence. All DICT servers MUST implement this command. 3.5.2.2. Responses 111 n strategies available - text follows 555 No strategies available Response code 111 requires a special parameter. the number of strategies available. 3.5.3. SHOW INFO Parameter 1 must be

SHOW INFO database 3.5.3.1. Description copyright, and licensing information about the The information is free-form text and is to the user in the same manner as a definition. the information is terminated with a CRLF period DICT servers MUST implement this command.

Displays the source, specified database. suitable for display The textual body of CRLF sequence. All 3.5.3.2. Responses

550 Invalid database, use "SHOW DB" for list of databases 112 database information follows These response codes require no special parameters. 3.5.4. SHOW SERVER

SHOW SERVER 3.5.4.1. Description

Displays local server information written by the local administrator. This could include information about local databases or strategies, or administrative information such as who to contact for access to databases requiring authentication. All DICT servers MUST implement this command.

Faith & Martin

Informational

[Page 14]


RFC 2229

A Dictionary Server Protocol

October 1997

3.5.4.2.

Responses 114 server information follows

This response code requires no special parameters. 3.6. The CLIENT Command

CLIENT text 3.6.1. This for send MUST have 3.6.2. Description command allows the client to provide information about itself possible logging and statistical purposes. All clients SHOULD this command after connecting to the server. All DICT servers implement this command (note, though, that the server doesn't to do anything with the information provided by the client). Responses 250 ok (optional timing information here) This response code requires no special parameters. 3.7. The STATUS Command

STATUS 3.7.1. Description server-specific may be useful in MUST implement response is not timing or debugging debugging or tuning this command (note, specified and may be information. This a DICT server. All though, that the text omitted).

Display some information DICT servers part of the 3.7.2.

Responses 210 (optional timing and statistical information here)

This response code requires no special parameters. 3.8. The HELP Command

HELP

Faith & Martin

Informational

[Page 15]


RFC 2229

A Dictionary Server Protocol

October 1997

3.8.1.

Description understood by this text will be presented period on a line by command.

Provides a short summary of commands that are implementation of the DICT server. The help as a textual response, terminated by a single itself. All DICT servers MUST implement this 3.8.2. Responses 113 help text follows

This response code requires no special parameters. 3.9. The QUIT Command

QUIT 3.9.1. Description All

This command is used by the client to cleanly exit the server. DICT servers MUST implement this command. 3.9.2. Responses 221 Closing Connection This response code requires no special parameters. 3.10. 3.10.1. The OPTION Command OPTION MIME

OPTION MIME 3.10.1.1. Description

Requests that all text responses be prefaced by a MIME header [RFC2045] followed by a single blank line (CRLF). If a client requests this option, then the client MUST be able to parse Content-Type and Content-transfer-encoding headers, and MUST be able to ignore textual responses which have an unsupported content or encoding. A client MUST support the UTF-8 encoding [RFC2044], which minimally means that the client MUST recognize UTF-8 multi-octet encodings and convert these into some symbol that can be printed by the client.

Faith & Martin

Informational

[Page 16]


RFC 2229

A Dictionary Server Protocol

October 1997

If a client header. If single blank as a default

requests this the header is line (CRLF), header. The

option, then the server will provide a MIME empty, the text response will start with a in which case a client MUST interpret this default header for SASL authentication is:

Content-type: application/octet-stream Content-transfer-encoding: base64 The default header for all other textual responses is: Content-type: text/plain; charset=utf-8 Content-transfer-encoding: 8bit If OPTION restrict example, clip, but client is MIME is not specified by the client, then the server may the information content provided to the client. For a definition may be accompanied by an image and an audio the server cannot transmit this information unless the able to parse MIME format headers.

Note that, because of the line length restrictions and end-ofresponse semantics, the "binary" content-transfer-encoding MUST NOT be used. In the future, extensions to the protocol may be provided which allow a client to request binary encodings, but the default SHOULD always be that the client can look for a "CRLF . CRLF" sequence to locate the end of the current text response. This allows clients to easily skip over text responses which have unsupported types or encodings. In the future, after significant experience with large databases in various languages has been gained, and after evaluating the need for specifying character sets and other encodings (e.g., compressed or BASE64 encoding), standard extensions to this protocol should be proposed which allow the client to request certain content types or encodings. Care should be taken that these extensions do not require a handshake which defeats pipelining. In the mean time, private extensions should be used to explore the parameter space to determine how best to implement these extensions. OPTION MIME is a REQUIRED server capability, all DICT servers MUST implement this command. 3.10.1.2. Responses 250 ok (optional timing information here) Note that some older server implementations, completed before this document was finalized, will return a status code 500 if this command is not implemented. Clients SHOULD be able to accept this behavior,

Faith & Martin

Informational

[Page 17]


RFC 2229

A Dictionary Server Protocol

October 1997

making default assumptions. Clients may also examine the capabilities string in the status code 220 header to determine if a server supports this capability. 3.11. The AUTH Command

AUTH username authentication-string 3.11.1. Description

The client can authenticate itself to the server using a username and password. The authentication-string will be computed as in the APOP protocol discussed in [RFC1939]. Briefly, the authentication-string is the MD5 checksum of the concatenation of the msg-id (obtained from the initial banner) and the "shared secret" that is stored in the server and client configuration files. Since the user does not have to type this shared secret when accessing the server, the shared secret can be an arbitrarily long passphrase. Because of the computational ease of computing the MD5 checksum, the shared secret should be significantly longer than a usual password. Authentication may make more dictionary databases available for the current session. For example, there may be some publicly distributable databases available to all users, and other private databases available only to authenticated users. Or, a server may require authentication from all users to minimize resource utilization on the server machine. Authentication is an optional server capability. MAY be implemented by a DICT server. 3.11.2. Responses 230 Authentication successful 531 Access denied, use "SHOW INFO" for server information These response codes require no special parameters. 3.12. The SASLAUTH Command The AUTH command

SASLAUTH mechanism initial-response SASLRESP response 3.12.1. Description

The Simple Authentication and Security Layer (SASL) is currently being developed [RFC2222]. The DICT protocol reserves the SASLAUTH and SASLRESP commands for this method of authentication. The results

Faith & Martin

Informational

[Page 18]


RFC 2229

A Dictionary Server Protocol

October 1997

of successful authentication with SALSAUTH will be the same as the results of successful AUTH authentication: more dictionary databases may become available for the current session. The initial-response is an optional parameter for the SASLAUTH command, encoded using BASE64 encoding [RFC2045]. Some SASL mechanisms may allow the use of this parameter. If SASL authentication is supported by a DICT server, then this parameter MUST also be supported. A typical SASL authentication will be initiated by the client using the SASLAUTH command. The server will reply with status code 130, followed by a challenge. The challenge will be followed by status code 330, indicating that the client must now send a response to the server. Depending on the details of the SASL mechanism currently in use, the server will either continue the exchange using status code 130, a challenge, and status code 330; or the server will use status code 230 or 531 to indicate authentication was successful or has failed. The challenges binary tokens standard DICT OPTION MIME is sent by the server are defined of arbitrary length, and should textual response, as described not set, then BASE64 encoding by the mechanisms as be sent using a in section 2.4.3. If MUST be used. If

OPTION MIME is set, then BASE64 is the default encoding, as specified in section 3.10.1. The client will send all responses using the SASLRESP command and a BASE64-encoded parameter. The responses sent by the client are defined by the mechanisms as binary tokens of arbitrary length. Remember that DICT command lines may only be 1024 characters in length, so the response provided by a DICT client is limited. If the mechanism specified in the SASLAUTH command is not supported, then status code 532 will be returned. Authentication is an optional server capability. command MAY be implemented by a DICT server. 3.12.2. Responses 130 330 230 531 532 challenge follows send response Authentication successful Access denied, use "SHOW INFO" for server information Access denied, unknown mechanism The SASLAUTH

Faith & Martin

Informational

[Page 19]


RFC 2229

A Dictionary Server Protocol

October 1997

These response codes require no special parameters. 4. Command Pipelining All DICT TCP send commands the face servers MUST be able to accept multiple commands in a single operation. Using a single TCP send operation for multiple can improved DICT performance significantly, especially in of high latency network links.

The possible implementation problems for a DICT server which would prevent command pipelining are similar to the problems that prevent pipelining in an SMTP server. These problems are discussed in detail in [RFC1854], which should be consulted by all DICT server implementors. The main implication is that a DICT server implementation MUST NOT flush or otherwise lose the contents of the TCP input buffer under any circumstances whatsoever. A DICT client may pipeline several commands and must check the responses to each command individually. If the server has shut down, it is possible that all of the commands will not be processed. For example, a simple DICT client may pipeline a CLIENT, DEFINE, and QUIT command sequence as it is connecting to the server. If the server is shut down, the initial response code sent by the server may be 420 (temporarily unavailable) instead of 220 (banner). In this case, the definition cannot be retrieved, and the client should report and error or retry the command. If the server is working, it may be able to send back the banner, definition, and termination message in a single TCP send operation. 5. URL Specification The DICT URL scheme is used to refer to definitions or word lists available using the DICT protocol:

dict://;@:/d::: dict://;@:/m::::

The "/d" syntax specifies the DEFINE command (section 3.2), whereas the "/m" specifies the MATCH command (section 3.3).

Faith & Martin

Informational

[Page 20]


RFC 2229

A Dictionary Server Protocol

October 1997

Some or all of ";@", ":", "", "", and "" may be omitted. "" will usually be omitted, but nth definition or match of a word. this information from the server is protocol. However, a client using all of the definitions or matches, specified. when included, it specifies the A method for extracting exactly not available using the DICT the URL specification could obtain and then select the one that is

If ";@" is omitted, no authentication is done. If ":" is omitted, the default port (2628) SHOULD be used. If "" is omitted, "!" SHOULD be used (see section 3.2). If "" is omitted, "." SHOULD be used (see section 3.3). ";@" specifies the username and the type of authentication performed. For "", the string "AUTH" indicates that APOP authentication using the AUTH command will be performed, whereas the string "SASLAUTH=" indicates that the SASLAUTH and SASLRESP commands will be used, with "" indicating the type of SASL authentication which will be used. If "" is a star (decimal code 42, "*"), then the client will select some type of authentication. Whenever authentication is required, the client SHOULD request additional information (e.g., a passphrase) from the user. In contrast to [RFC1738], clear text passwords are not permitted in the URL. Trailing colons may be omitted. For example, the following URLs might specify definitions or matches: dict://dict.org/d:shortcake: dict://dict.org/d:shortcake:* dict://dict.org/d:shortcake:wordnet: dict://dict.org/d:shortcake:wordnet:1 dict://dict.org/d:abcdefgh dict://dict.org/d:sun dict://dict.org/d:sun::1 dict://dict.org/m:sun dict://dict.org/m:sun::soundex dict://dict.org/m:sun:wordnet::1 dict://dict.org/m:sun::soundex:1 dict://dict.org/m:sun:::

Faith & Martin

Informational

[Page 21]


RFC 2229

A Dictionary Server Protocol

October 1997

6.

Extensions This protocol was designed so that flat text databases can be used with a server after a minimum of analysis and formatting. Our experience is that merely constructing an index for a database may be sufficient to make it useful with a DICT server. The ability to serve preformatted text is especially important since freelyavailable databases are often distributed as flat text files without any semantic mark-up information (and often contain "ASCII art" which precludes the automation of even simple formatting). However, given a database with sufficient mark-up information, it may be possible to generate output in a variety of different formats (e.g., simple HTML or more sophisticated SGML). The specification of formatting is beyond the scope of this document. The requirements for negotiation of format (including character set and other encodings) is complex and should be examined over time as more experience is gained. We suggest that the use of different formats, as well as other server features, be explored as extensions to the protocol.

6.1.

Experimental Command Syntax

Single-letter commands are reserved for debugging and testing, SHOULD NOT be defined in any future DICT protocol specification, and MUST NOT be used by any client software. Commands beginning with the letter "X" are reserved for experimental extensions, and SHOULD NOT be defined in any future DICT protocol specification. Authors of client software should understand that these commands are not part of the DICT protocol and may not be available on all DICT servers. 6.2. Experimental Commands and Pipelining

Experimental commands should be designed so that a client can pipeline the experimental commands without knowing if a server supports the commands (e.g., instead of using feature negotiation). If the server does not support the commands, then a response code in the 5yz series (usually 500) will be given, notifying the client that the extension is not supported. Of course, depending on the complexity of the extensions added, feature negotiation may be necessary. To help minimize negotiation time, server-supported features may be announced in the banner (code 220) using the optional capabilities parameter.

Faith & Martin

Informational

[Page 22]


RFC 2229

A Dictionary Server Protocol

October 1997

7.

Summary of Response Codes Below is a summary of response codes. A star (*) in the first column indicates the response has defined arguments that must be provided. * 110 n databases present - text follows * 111 n strategies available - text follows 112 database information follows 113 help text follows 114 server information follows 130 challenge follows * 150 n definitions retrieved - definitions follow * 151 word database name - text follows * 152 n matches found - text follows 210 (optional timing and statistical information here) * 220 text msg-id 221 Closing Connection 230 Authentication successful 250 ok (optional timing information here) 330 send response 420 Server temporarily unavailable 421 Server shutting down at operator request 500 Syntax error, command not recognized 501 Syntax error, illegal parameters 502 Command not implemented 503 Command parameter not implemented 530 Access denied 531 Access denied, use "SHOW INFO" for server information 532 Access denied, unknown mechanism 550 Invalid database, use "SHOW DB" for list of databases 551 Invalid strategy, use "SHOW STRAT" for a list of strategies 552 No match 554 No databases present 555 No strategies available

8.

Sample Conversations Theses are samples of the conversations that might be expected with a typical DICT server. The notation "C:" indicates commands set by the client, and "S:" indicates responses sent by the server. Blank lines are included for clarity and do not indicate actual newlines in the transaction.

Faith & Martin

Informational

[Page 23]


RFC 2229

A Dictionary Server Protocol

October 1997

8.1.

Sample 1 - HELP, DEFINE, and QUIT commands

C: [ client initiates connection ] S: 220 dict.org dictd (version 0.9) <27831.860032493@dict.org>

C: HELP S: S: S: S: S: S: 113 Help text follows DEFINE database word look up word in database MATCH database strategy word match word in database using strategy [ more server-dependent help text ] . 250 Command complete

C: DEFINE ! penguin S: S: S: S: S: S: S: 150 1 definitions found: list follows 151 "penguin" wn "WordNet 1.5" : definition text follows penguin 1. n: short-legged flightless birds of cold southern esp. Antarctic regions having webbed feet and wings modified as flippers . 250 Command complete

C: DEFINE * shortcake S: S: S: S: S: S: S: S: S: S: S: S: S: 150 2 definitions found: list follows 151 "shortcake" wn "WordNet 1.5" : text follows shortcake 1. n: very short biscuit spread with sweetened fruit and usu. whipped cream . 151 "Shortcake" web1913 "Webster's Dictionary (1913)" : text follows Shortcake \Short"cake`\, n. An unsweetened breakfast cake shortened with butter or lard, rolled thin, and baked. . 250 Command complete

C: DEFINE abcdefgh S: 552 No match

Faith & Martin

Informational

[Page 24]


RFC 2229

A Dictionary Server Protocol

October 1997

C: quit S: 221 Closing connection 8.2. Sample 2 - SHOW commands, MATCH command

C: SHOW DB S: S: S: S: S: S: 110 3 databases present: list follows wn "WordNet 1.5" foldoc "Free On-Line Dictionary of Computing" jargon "Hacker Jargon File" . 250 Command complete

C: SHOW STRAT S: S: S: S: S: S: S: S: 111 5 strategies present: list follows exact "Match words exactly" prefix "Match word prefixes" substring "Match substrings anywhere in word" regex "Match using regular expressions" reverse "Match words given definition keywords" . 250 Command complete

C: MATCH foldoc regex "s.si" S: S: S: S: S: S: S: S: S: S: 152 7 matches found: list follows foldoc Fast SCSI foldoc SCSI foldoc SCSI-1 foldoc SCSI-2 foldoc SCSI-3 foldoc Ultra-SCSI foldoc Wide SCSI . 250 Command complete

C: MATCH wn substring "abcdefgh" S: 552 No match

Faith & Martin

Informational

[Page 25]


RFC 2229

A Dictionary Server Protocol

October 1997

8.3.

Sample 3 - Server downtime

C: [ client initiates connection ] S: 420 Server temporarily unavailable

C: [ client initiates connection ] S: 421 Server shutting down at operator request

8.4.

Sample 4 - Authentication

C: [ client initiates connection ] S: 220 dict.org dictd (version 0.9) <27831.860032493@dict.org>

C: SHOW DB S: S: S: S: 110 1 database present: list follows free "Free database" . 250 Command complete

C: AUTH joesmith authentication-string S: 230 Authentication successful

C: SHOW DB S: S: S: S: S: 110 2 databases present: list follows free "Free database" licensed "Local licensed database" . 250 Command complete

9.

Security Considerations This RFC raises no security issues.

Faith & Martin

Informational

[Page 26]


RFC 2229

A Dictionary Server Protocol

October 1997

10.

References [ASCII] US-ASCII. Coded Character Set - 7-Bit American Standard Code for Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986. [FOLDOC] Howe, Denis, ed. The Free On-Line Dictionary of Computing, [ISO10646] ISO/IEC 10646-1:1993. International Standard -Information technology -- Universal Multiple-Octet Coded Character Set (UCS) -- Part 1: Architecture and Basic Multilingual Plane. UTF-8 is described in Annex R, adopted but not yet published. UTF-16 is described in Annex Q, adopted but not yet published. [JARGON] The on-line hacker Jargon File, version 4.0.0, 25 JUL 1996, [KNUTH73] Knuth, Donald E. Volume 3: Sorting and Co., 1973, pages 391 method was originally Robert C. Russell [US (1922)]. "The Art of Computer Programming", Searching (Addison-Wesley Publishing and 392). Knuth notes that the soundex described by Margaret K. Odell and Patents 1261167 (1918) and 1435663

[PZ85] Pollock, Joseph J. and Zamora, Antonio, "Automatic spelling correction in scientific and scholarly text," CACM, 27(4): Apr. 1985, 358-368. [RFC640] Postel, J., "Revised FTP Reply Codes", RFC 640, June, 1975. [RFC821] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, August 1982. [RFC822] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, August 1982. [RFC977] Kantor, B., and P. Lapsley, "Network News Transfer Protocol: A Proposed Standard for the Stream-Based Transmission of News", RFC 977, February 1986. [RFC2045] Freed, N., and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.

Faith & Martin

Informational

[Page 27]


RFC 2229

A Dictionary Server Protocol

October 1997

[RFC1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994. [RFC1760] Haller, N., "The S/KEY One-Time Password System", RFC 1760, February 1995. [RFC1985] Freed, N., and A. Cargille, "SMTP Service Extension for Command Pipelining", RFC 1854, October 1995. [RFC1939] Myers, J., and M. Rose, "Post Office Protocol - Version 3", STD 53, RFC 1939, May 1996. [RFC2044] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2044, October 1996. [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, January 1997. [RFC2078] Linn, J., "Generic Security Service Application Program Interface, Version 2", RFC 2078, January 1997. [RFC2222] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [WEB1913] Webster's Revised Unabridged Dictionary (G & C. Merriam Co., 1913, edited by Noah Porter). Online version prepared by MICRA, Inc., Plainfield, N.J. and edited by Patrick Cassidy . For further information, see , and [WORDNET] Miller, G.A. (1990), ed. WordNet: An On-Line Lexical Database. International Journal of Lexicography. Volume 3, Number 4.

Faith & Martin

Informational

[Page 28]


RFC 2229

A Dictionary Server Protocol

October 1997

11.

Acknowledgements Thanks to Arnt Gulbrandsen and Nicolai Langfeldt for many helpful discussions. Thanks to Bennet Yee, Doug Hoffman, Kevin Martin, and Jay Kominek for extensive testing and feedback on the initial implementations of the DICT server. Thanks to Zhong Shao for advice and support. Thanks to Brian Kanto, Phil Lapsley, and Jon Postel for writing exemplary RFCs which were consulted during the preparation of this document. Thanks to Harald T. Alvestrand, whose comments helped improve this document.

12.

Authors' Addresses

Rickard E. Faith EMail: faith@cs.unc.edu (or faith@acm.org)

Bret Martin EMail: bamartin@miranda.org The majority of this work was completed while Bret Martin was a student at Yale University.

Faith & Martin

Informational

[Page 29]


RFC 2229

A Dictionary Server Protocol

October 1997

13.

Full Copyright Statement Copyright (C) The Internet Society (1997). All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published andand distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Faith & Martin

Informational

[Page 30]