RFC 2229
A Dictionary Server Protocol
RFC 2229: A Dictionary Server Protocol 📖✨
Okay bestie, let's talk about RFC 2229 🎀. It's called A Dictionary Server Protocol and it came out in October 1997. It's from the Network Working Group, and the two authors are R. Faith (U. North Carolina, Chapel Hill) and B. Martin (Miranda Productions). It's Informational 🧚, so it's giving "here's some useful info" and not "this is an Internet standard." The title block doesn't list anything it obsoletes or updates, so it's a clean, standalone doc 💅.
Status of this Memo 🌸
This memo gives information to 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). All Rights Reserved.
Abstract 💜
The Dictionary Server Protocol (DICT) is a TCP transaction based query/response protocol. It lets a client pull dictionary definitions out of a set of natural language dictionary databases, and it's honestly so useful ✨.
Table of Contents 📑
1. Introduction ......................................... 2
1.1. Requirements ......................................... 3
2. Protocol Overview .................................... 3
2.1. Link Level ........................................... 3
2.2. Lexical Tokens ....................................... 3
2.3. Commands ............................................. 4
2.4. Responses ............................................ 5
2.4.1. Status Responses ..................................... 5
2.4.2. General Status Responses ............................. 6
2.4.3. Text Responses ....................................... 6
3. Command and Response Details ......................... 7
3.1. Initial Connection ................................... 7
3.2. The DEFINE Command ................................... 9
3.3. The MATCH Command .................................... 10
3.4. A Note on Virtual Databases .......................... 12
3.5. The SHOW Command ..................................... 13
3.5.1. SHOW DB .............................................. 13
3.5.2. SHOW STRAT ........................................... 13
3.5.3. SHOW INFO ............................................ 14
3.5.4. SHOW SERVER .......................................... 14
3.6. The CLIENT Command ................................... 15
3.7. The STATUS Command ................................... 15
3.8. The HELP Command ..................................... 15
3.9. The QUIT Command ..................................... 16
3.10. The OPTION Command ................................... 16
3.10.1. OPTION MIME .......................................... 16
3.11. The AUTH Command ..................................... 18
3.12. The SASLAUTH Command ................................. 18
4. Command Pipelining ................................... 20
5. URL Specification .................................... 20
6. Extensions ........................................... 22
6.1. Experimental Command Syntax .......................... 22
6.2. Experimental Commands and Pipelining ................. 22
7. Summary of Response Codes ............................ 23
8. Sample Conversations ................................. 23
8.1. Sample 1 - HELP, DEFINE, and QUIT commands ........... 24
8.2. Sample 2 - SHOW commands, MATCH command .............. 25
8.3. Sample 3 - Server downtime ........................... 26
8.4. Sample 4 - Authentication ............................ 26
9. Security Considerations .............................. 26
10. References ........................................... 27
11. Acknowledgements ..................................... 29
12. Authors' Addresses ................................... 29
13. Full Copyright Statement ............................. 301. Introduction ✨
For years, the Internet community relied on the "webster" protocol for natural language definitions 📚. webster supports access to a single dictionary and, optionally, a single thesaurus. Lately, the number of publicly available webster servers on the Internet has dropped a lot 😭.
Thankfully, several freely-distributable dictionaries and lexicons have shown up online 🎉. The problem is they aren't reachable through one uniform interface, and they aren't all on a single site. They're often small and incomplete on their own, but together they'd make an awesome 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]. Translated and non-English dictionaries are also popping up (for example, the FOLDOC dictionary is being translated into Spanish 🌈).
The webster protocol isn't built for lots of separate dictionary databases, and extending it wasn't felt to be a clean fix for the dictionary database problem 🙈.
So the DICT protocol is designed to access multiple databases 💅. You can request word definitions, search the word index (using an easily extended set of algorithms), get information about the server (for example, which index search strategies are supported, or which databases are available), and get information about a database (for example, copyright, citation, or distribution information). The DICT protocol also 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], which uses 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. "MAY" (or "OPTIONAL") means that this item is optional, and may be omitted without careful consideration.
2. Protocol Overview 🦋
2.1. Link Level 🔗
The DICT protocol assumes a reliable data stream, such as the one 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 doesn't do any user interaction or presentation-level functions, so no drama there 💖.
2.2. Lexical Tokens 🧩
Commands and replies are made of characters from the UCS character set [ISO10646], using the UTF-8 [RFC2044] encoding. More specifically, the grammar conventions from [RFC822] are used:
; ( Octal, Decimal.)
CHAR = <any UTF-8 character (1 to 6 octets)>
CTL = <any ASCII control ; ( 0- 37, 0.- 31.)
character and DEL> ; ( 177, 127.)
CR = <ASCII CR, carriage return> ; ( 15, 13.)
LF = <ASCII LF, linefeed> ; ( 12, 10.)
SPACE = <ASCII SP, space> ; ( 40, 32.)
HTAB = <ASCII HT, horizontal-tab> ; ( 11, 9.)
<"> = <ASCII quote mark> ; ( 42, 34.)
<'> = <ASCII single quote mark> ; ( 47, 39.)
CRLF = CR LF
WS = 1*(SPACE / HTAB)
dqstring = <"> *(dqtext/quoted-pair) <">
dqtext = <any CHAR except <">, "\", and CTLs>
sqstring = <'> *(dqtext/quoted-pair) <'>
sqtext = <any CHAR except <'>, "\", and CTLs>
quoted-pair = "\" CHAR
atom = 1*<any CHAR except SPACE, CTLs, <'>, <">, and "\">
string = *<dqstring / sqstring / quoted-pair>
word = *<atom / string>
description = *<word / WS>
text = *<word / WS>2.3. Commands ⌨️
Commands are a command word followed by zero or more parameters. Commands with parameters must separate those 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 *<WS cmd-param>
cmd-word = atom
cmd-param = database / strategy / word
database = atom
strategy = atomCommands are not case sensitive 🙌.
Command lines MUST NOT exceed 1024 characters in length. That counts 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.
Heads up: command lines have a hard cap, so count everything, spaces and the CRLF included 🫣.
2.4. Responses 💬
Responses come in two kinds: status and textual.
2.4.1. Status Responses 🚦
Status responses show the server's response to the last command the client sent 📮.
Status response lines begin with a 3 digit numeric code, which is enough to tell every response apart. Some of these codes herald the transmission of text that comes next.
The first digit broadly tells you the success, failure, or progress of the previous command (based generally on [RFC640,RFC821]):
1yz - Positive Preliminary reply
2yz - Positive Completion reply
3yz - Positive Intermediate reply
4yz - Transient Negative Completion reply
5yz - Permanent Negative Completion replyThe next digit indicates the response category:
x0z - Syntax
x1z - Information (e.g., help)
x2z - Connections
x3z - Authentication
x4z - Unspecified as yet
x5z - 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) extensionsThe exact response codes that should be expected from each command are detailed in the description of that command 🔍.
Certain status responses contain parameters, like numbers and strings. The number and type of those parameters is fixed for each response code, which keeps the response easy to interpret ✨. Other status responses don't need specific text identifiers. Parameter requirements are detailed in the description of the relevant commands. Apart from specifically detailed parameters, the text after a response code 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 that are 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 💅
okay so no matter what command you send, these general status responses are always on the table 🫶
500 Syntax error, command not recognized
501 Syntax error, illegal parameters
502 Command not implemented
503 Command parameter not implemented
420 Server temporarily unavailable
421 Server shutting down at operator request2.4.3. Text Responses 📝
before any actual text gets sent, the server sends a numeric status line with a 1yz code to say "hey, text is coming" ✨ then the text comes in as a bunch of successive lines, and every single line ends with a CRLF 🎀 to mark the end, a line containing only a period (decimal code 46, ".") shows up. so the server sends a CRLF at the end of the last line of text, then a period, then another CRLF. bestie, that's the closing ceremony 🌸
now here's the plot twist 🙈 if a line of original text starts with a period, the DICT server doubles that first period. so the client MUST NOT... wait, sorry, the original says the client "must" examine the first character of each line it gets. so it checks each line: if it starts with two periods, it collapses them into one period. and if it's just a single period followed by a CRLF, that's the end of the text response. it's giving detective energy 🕵️♀️
if the OPTION MIME command has been given, every textual response gets a MIME header [RFC2045] first, followed by one single blank line (CRLF). see section 3.10.1 for the full tea on OPTION MIME 🍓
after a text response, a 2yz response code gets sent. ✨
okay now the rules that are NOT up for debate 🔥
- Text lines MUST NOT exceed 1024 characters in length, and that counts EVERYTHING: spaces, separators, punctuation, the extra initial period (if it's needed), and the trailing CRLF. no sneaking extra characters in 🙅♀️
- since UTF-8 can use up to 6 octets for a single character, the text line input buffer MUST be able to accept up to 6144 octets. that's 1024 times 6, so the math checks out 💖
- by default, the text of the definitions MUST be made of characters from the UCS character set [ISO10644], encoded with UTF-8 [RFC2044]. the big win with UTF-8 is that it keeps the full range of 7-bit US ASCII [USASCII] values intact 🦋
- clients and servers MUST support UTF-8, even if it's only in some minimal fashion. no skipping this one, periodt 💜
3. Command and Response Details 🎀
okay this is the part where we go command by command 🧚 each command and its responses get broken down below. each command is shown in upper case so it's easy to read, but the DICT server is case-insensitive, so lowercase works too 🌈
except for the AUTH and SASLAUTH commands, every command in this section MUST be implemented by all DICT servers. the two exceptions are the only ones that get a pass 👑
3.1. Initial Connection 🔌
when a client first connects to a DICT server, the server sends a code 220 as long as the client's IP is allowed to connect:
220 text capabilities msg-idthe code 220 is a banner. it usually has the host name and DICT server version info in it 💅
the second-to-last sequence of characters in the banner is the optional capabilities string. this is how servers announce that they support extensions to the DICT protocol ✨ here's how the capabilities string is defined:
capabilities = ["<" msg-atom *("." msg-atom) ">"]
msg-atom = 1*<any CHAR except SPACE, CTLs,
"<", ">", ".", and "\">each individual capability is described by a single msg-atom. for example, the string <html.gzip> might describe a server that supports extensions for HTML or compressed output 🍓 capability names that begin with "x" or "X" are reserved for experimental extensions, and they SHOULD NOT be defined in any future DICT protocol specification. so hands off the x's, they're for experiments only 🧪 some of these capabilities can tell the client that certain functionality is available or can be requested. the following capabilities are currently defined:
mime The OPTION MIME command is supported
auth The AUTH command is supported
kerberos_v4 The SASL Kerberos version 4 mechanism is supported
gssapi The SASL GSSAPI [RFC2078] mechanism is supported
skey The SASL S/Key [RFC1760] mechanism is supported
external The SASL external mechanism is supportedthe last sequence of characters in the banner is a msg-id, which is similar to the format in [RFC822]. the simplified version looks like this:
msg-id = "<" spec ">" ; Unique message id
spec = local-part "@" domain
local-part = msg-atom *("." msg-atom)
domain = msg-atom *("." msg-atom)note that, unlike [RFC822], spaces and quoted pairs are NOT allowed in the msg-id. wait, careful, I mean they are not allowed, full stop 🙅♀️ this restriction makes the msg-id way easier for the client to find and parse, and it doesn't meaningfully reduce any security benefits, since the msg-id can be arbitrarily long (as bounded by the response length limits set forth elsewhere in this document) 🦋
also, the open and close brackets are part of the msg-id, and they should be included in the string used to compute the MD5 checksum. the brackets are NOT optional extras, they're part of the deal 💀
this message id is what the client uses when it formulates the authentication string for the AUTH command 🔐
if the client's IP is NOT allowed to connect, the server sends a code 530 instead:
530 Access deniedtransient failure responses are possible too:
420 Server temporarily unavailable
421 Server shutting down at operator requestfor example, response code 420 should be used if the server can't fork a server process right now (or can't currently get other resources needed for a usable connection), but expects to be able to fork or get those resources soon 🌸
response code 421 should be used when the server has been shut down at operator request, or when conditions show that the ability to service more requests in the near future will be impossible. this can be used for a graceful, operator-managed temporary shutdown, or to say that a well known server has been permanently removed from service (in which case the text message might give more info) 😭
3.2. The DEFINE Command 📖
DEFINE database word3.2.1. Description 💭
this command looks up the specified word in the specified database ✨ all DICT servers MUST implement this command. no exceptions, it's a core one 👑
if the database name is an exclamation point (decimal code 33, "!"), then all of the databases get searched until a match is found, and all matches in that database get displayed. if the database name is a star (decimal code 42, "*"), then all the matches in all available databases get displayed. in both of these special cases, the databases are searched in the same order that "SHOW DB" prints them in 🌈
if the word wasn't found, status code 552 gets sent 💔
if the word was found, status code 150 gets sent, which tells the client that one or more definitions follow 🎉
for each definition, status code 151 gets sent, followed by the textual body of the definition. the first three space-delimited parameters after status code 151 give the word retrieved, the name of the database (same as the first column of the SHOW DB command), and a short description for the database (same as the second column of the SHOW DB command). the short name is suitable for printing as:
From name:before the definition gets printed. this gives the user source info, so they know where the definition came from 🧠
the textual body of each definition ends with a CRLF period CRLF sequence 🎀
after all the definitions have been sent, status code 250 gets sent. this command can also give optional timing info (which is server dependent and is NOT meant to be parsed by the client). this extra info is handy when you're debugging and tuning the server 🔧
3.2.2. Responses 📬
550 Invalid database, use "SHOW DB" for list of databases
552 No match
150 n definitions retrieved - definitions follow
151 word database name - text follows
250 ok (optional timing information here)response codes 150 and 151 need special parameters as part of their text. the client can use those parameters to show info on the user's terminal ✨
for code 150, parameter 1 is 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") that the definition was retrieved from, and parameter 3 is the short database description (the second column of the "SHOW DB" command) 🦋
3.3. The MATCH Command 🔍
MATCH database strategy word3.3.1. Description 🌸
this command searches an index for the dictionary and reports words that were found using a particular strategy. not all strategies are useful for all dictionaries, and some dictionaries may support extra search strategies (like reverse lookup) 🧩 all DICT servers MUST implement the MATCH command, and they MUST support the "exact" and "prefix" strategies. these are easy to implement and generally the most useful, so they're the MVPs 🏆 other strategies are server dependent.
the "exact" strategy matches a word exactly, although different servers may treat non-alphanumeric data differently. the original authors found that a case-insensitive comparison which ignores non-alphanumeric characters and folds whitespace works well for English-language dictionaries 🇬🇧 other comparisons may be a better fit for other languages or when extended character sets are in play 🌍
the "prefix" strategy is similar to "exact", except it only compares the first part of the word 🫶
different servers may implement these algorithms differently. the requirement is just that strategies named "exact" and "prefix" exist, so a simple client can use them 💖
other strategies a server implementor might consider are matches based on substring, suffix, regular expressions, soundex [KNUTH73], and Levenshtein [PZ85] algorithms. the last two are especially useful for correcting spelling errors 🙈 other useful strategies do some sort of "reverse" lookup (i.e., searching definitions to find the word the query is hinting at) 🕵️♀️
if the database name is an exclamation point (decimal code 33, "!"), then all of the databases get searched until a match is found, and all matches in that database get displayed. if the database name is a star (decimal code 42, "*"), then all the matches in all available databases get displayed. in both special cases, the databases are searched in the same order as "SHOW DB" prints them 🌈
if the strategy is a period (decimal code 46, "."), then the word gets matched using a server-dependent default strategy, which should be the best strategy available for interactive spell checking. this is usually a derivative of the Levenshtein algorithm [PZ85] 🧠✨
if no matches are found in any of the searched databases, status code 552 gets returned 💀
otherwise, status code 152 gets returned, followed by a list of matched words, one per line, in this form:
database wordthis makes the responses directly useful in a DEFINE command 🎀
the textual body of the match list ends with a CRLF period CRLF sequence 🔚
following the list, status code 250 is sent. it may include server-specific timing and statistical info, as discussed in the section on the DEFINE command ⭐
3.3.2. Responses ✨
Okay, here are the codes the server can throw back at you after a MATCH 💅
550 Invalid database, use "SHOW DB" for list of databases
551 Invalid strategy, use "SHOW STRAT" for a list of strategies
552 No match
152 n matches found - text follows
250 ok (optional timing information here)Response code 152 needs a special parameter tucked into its text 🎀 Parameter 1 must be the number of matches retrieved.
3.4. A Note on Virtual Databases 🧚
Okay, so the "*" and "!" databases are the special ones that let you search everything with one single command 🌈
But sometimes you don't want everything. Maybe you only want some of the databases a server offers 🍓 One option is for the client to run SHOW DB to get the list of databases and their descriptions, then (maybe with a human helping) pick a subset for an interactive search. Once you've made that pick one time, you can save it, for example, in a client configuration file 💖
Another option is for the server to offer "virtual" databases that merge several regular databases into one 🦋 For example, a virtual database could include all of the translating dictionaries, but leave out the regular dictionaries and thesauri. The special "*" and "!" databases can be thought of as names of virtual databases that give you 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 only give you info that's already 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 don't need to be listed.)
Virtual databases are an implementation-specific detail, and they have absolutely no impact on the DICT protocol 💅 The DICT protocol views virtual and non-virtual databases the exact same way.
We're bringing up virtual databases anyway, though, because they solve a database selection problem that could also have been solved by changing the protocol 🫶 For example, each dictionary could be given attributes, and the protocol could be extended to search only databases with certain attributes. But that would needlessly complicate the parsing and analysis the implementation has to do 😭 Also, unless the classification system is extremely general, there's a risk it would restrict the types of databases that can be used with the DICT protocol. (The protocol was designed with human-language databases in mind, but it's applicable to any read-only database application, especially ones with a single semi-unique alphanumeric key and textual data 🌸)
3.5. The SHOW Command 🎀
3.5.1. SHOW DB
SHOW DB
SHOW DATABASES3.5.1.1. Description
Displays the list of currently accessible databases, one per line, in the form:
database descriptionThe 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 because of the client's domain or a lack of user authentication (see the AUTH and SASLAUTH commands in sections 3.11 and 3.12). Information about these databases isn't available until authentication happens. Until then, the client interacts with the server as if those extra databases didn't exist 👀
3.5.1.2. Responses
110 n databases present - text follows
554 No databases presentResponse 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 STRATEGIES3.5.2.1. Description
Displays the list of currently supported search strategies, one per line, in the form:
strategy descriptionThe 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 availableResponse code 111 requires a special parameter. Parameter 1 must be the number of strategies available.
3.5.3. SHOW INFO
SHOW INFO database3.5.3.1. Description
Displays the source, copyright, and licensing information about the specified database. The information is free-form text and is meant to be shown to the user the same way as a definition. The textual body of the information is terminated with a CRLF period CRLF sequence. All DICT servers MUST implement this command 🧾
3.5.3.2. Responses
550 Invalid database, use "SHOW DB" for list of databases
112 database information followsThese response codes require no special parameters.
3.5.4. SHOW SERVER
SHOW SERVER3.5.4.1. Description
Displays local server information written by the local administrator 🏠 This could include info about local databases or strategies, or administrative stuff like who to contact for access to databases that require authentication. All DICT servers MUST implement this command 🫶
3.5.4.2. Responses
114 server information followsThis response code requires no special parameters.
3.6. The CLIENT Command 🧚
CLIENT text3.6.1. Description
This command lets the client share info about itself for possible logging and statistical purposes 📊 All clients SHOULD send this command after connecting to the server. All DICT servers MUST implement this command (but the server doesn't have to do anything with the info the client provides, so no pressure 😌).
3.6.2. Responses
250 ok (optional timing information here)This response code requires no special parameters.
3.7. The STATUS Command 🔥
STATUS3.7.1. Description
Displays some server-specific timing or debugging information. This info may be useful for debugging or tuning a DICT server 🛠️ All DICT servers MUST implement this command (but the text part of the response isn't specified and may be left out 🤷♀️).
3.7.2. Responses
210 (optional timing and statistical information here)This response code requires no special parameters.
3.8. The HELP Command 🌸
HELP3.8.1. Description
Gives a short summary of the commands this DICT server implementation understands 📝 The help text comes back as a textual response, ended by a single period on a line by itself. All DICT servers MUST implement this command.
3.8.2. Responses
113 help text followsThis response code requires no special parameters.
3.9. The QUIT Command 👋
QUIT3.9.1. Description
The client uses this command to cleanly exit the server 🚪 All DICT servers MUST implement this command.
3.9.2. Responses
221 Closing ConnectionThis response code requires no special parameters.
3.10. The OPTION Command 🎀
3.10.1. OPTION MIME
OPTION MIME3.10.1.1. Description
This one requests that all text responses get 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 that have an unsupported content or encoding. A client MUST support the UTF-8 encoding [RFC2044], which minimally means the client MUST recognize UTF-8 multi-octet encodings and convert them into some symbol the client can print 🌈
If a client requests this option, then the server will provide a MIME header. If the header is empty, the text response starts with a single blank line (CRLF), and in that case a client MUST interpret this as a default header. The default header for SASL authentication is:
Content-type: application/octet-stream
Content-transfer-encoding: base64The default header for all other textual responses is:
Content-type: text/plain; charset=utf-8
Content-transfer-encoding: 8bitIf OPTION MIME is not specified by the client, then the server may restrict the information content it gives the client. For example, a definition could come with an image and an audio clip, but the server can't send that info unless the client can parse MIME format headers 🖼️🔊
Note that, because of the line length restrictions and end-of-response semantics, the "binary" content-transfer-encoding MUST NOT be used 🚫 In the future, extensions to the protocol may be provided that let a client request binary encodings. But the default SHOULD always be that the client can look for a "CRLF . CRLF" sequence to find the end of the current text response. This lets clients easily skip over text responses that have unsupported types or encodings 🦋
Later on, after lots of experience with large databases in various languages has been gained, and after evaluating the need to specify character sets and other encodings (for example, compressed or BASE64 encoding), standard extensions to this protocol should be proposed that let the client request certain content types or encodings. Care should be taken that these extensions don't require a handshake that defeats pipelining 🧐 In the meantime, private extensions should be used to explore the parameter space and figure out 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 isn't implemented. Clients SHOULD be able to accept this behavior by making default assumptions. Clients may also look at the capabilities string in the status code 220 header to figure out whether a server supports this capability 🔍
3.11. The AUTH Command 🔐
AUTH username authentication-string3.11.1. Description
The client can authenticate itself to the server with a username and password 🗝️ The authentication-string is computed the same way 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" stored in the server and client configuration files. Since the user doesn't have to type this shared secret to access the server, the shared secret can be an arbitrarily long passphrase. Because computing an MD5 checksum is computationally easy, 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, plus other private databases only available 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. The AUTH command MAY be implemented by a DICT server ✨
3.11.2. Responses
230 Authentication successful
531 Access denied, use "SHOW INFO" for server informationThese response codes require no special parameters.
3.12. The SASLAUTH Command 🔐
SASLAUTH mechanism initial-response
SASLRESP response3.12.1. Description 💖
okay so SASL (Simple Authentication and Security Layer) is still being developed over at [RFC2222] 🧁. DICT reserves the SASLAUTH and SASLRESP commands for this method of authentication. If SASLAUTH works, you get the same results as a successful AUTH login: more dictionary databases may become available for your current session 📚✨.
The initial-response is an optional parameter for SASLAUTH, encoded using BASE64 encoding [RFC2045]. Some SASL mechanisms may allow it to be used. If SASL authentication is supported by a DICT server, then this parameter MUST also be supported 🫶.
A typical SASL authentication starts with the client sending the SASLAUTH command. The server replies with status code 130, followed by a challenge. The challenge is then followed by status code 330, which means the client now has to send a response back to the server 🦋.
Depending on which SASL mechanism is in use, the server will either keep the exchange going with status code 130, a challenge, and status code 330 again, or it will use status code 230 or 531 to say whether authentication worked or failed 💅.
The challenges from the server are defined by the mechanisms as binary tokens of arbitrary length, and they should be sent using a standard DICT textual response, as described in section 2.4.3. If OPTION MIME is not set, then BASE64 encoding MUST be used. If OPTION MIME is set, then BASE64 is the default encoding, as specified in section 3.10.1 🎀.
The client sends all of its responses using the SASLRESP command and a BASE64-encoded parameter. These responses are also binary tokens of arbitrary length, as defined by the mechanisms. Remember that DICT command lines can only be 1024 characters long, so the response a DICT client can provide is limited 🙈.
If the mechanism named in the SASLAUTH command isn't supported, then status code 532 gets returned 💀.
Authentication is an optional server capability. The SASLAUTH command MAY be implemented by a DICT server 🌸.
3.12.2. Responses 📋
130 challenge follows
330 send response
230 Authentication successful
531 Access denied, use "SHOW INFO" for server information
532 Access denied, unknown mechanismThese response codes require no special parameters 💜.
4. Command Pipelining 🚀
All DICT servers MUST be able to accept multiple commands in a single TCP send operation. Sending several commands in one TCP send operation can improve DICT performance significantly, especially when you're dealing with high-latency network links. It's giving speed 🏎️💨.
The implementation problems that could stop a DICT server from pipelining commands are similar to the ones that stop pipelining in an SMTP server. These problems are covered in detail in [RFC1854], which every DICT server implementor should read 🤓📖.
The main takeaway is that a DICT server implementation MUST NOT flush or otherwise lose the contents of the TCP input buffer under any circumstances whatsoever. Not even a little bit 😭🚫.
A DICT client may pipeline several commands, but it must check the responses to each command individually 🧐. If the server has shut down, it's possible that not all of the commands will get processed. For example, a simple DICT client might pipeline a CLIENT, DEFINE, and QUIT command sequence as it connects to the server. If the server is shut down, the initial response code from the server might be 420 (temporarily unavailable) instead of 220 (banner). In that case the definition can't be retrieved, so the client should report an error or retry the command 🥲. If the server is working, it may be able to send back the banner, the definition, and the termination message all in a single TCP send operation 🎉.
5. URL Specification 🔗
The DICT URL scheme is used to refer to definitions or word lists that are available through the DICT protocol 📚🦋:
dict://<user>;<auth>@<host>:<port>/d:<word>:<database>:<n>
dict://<user>;<auth>@<host>:<port>/m:<word>:<database>:<strat>:<n>The /d syntax specifies the DEFINE command (section 3.2), whereas /m specifies the MATCH command (section 3.3) 💅.
Some or all of <user>;<auth>@, :<port>, <database>, <strat>, and <n> may be omitted 🌈.
<n> will usually be left out, but when it's included, it specifies the nth definition or match of a word. The DICT protocol doesn't have a way to pull out exactly this information from the server. However, a client using the URL specification could grab all of the definitions or matches, and then pick out the one that was specified 🧚.
If <user>;<auth>@ is omitted, no authentication is done. If :<port> is omitted, the default port (2628) SHOULD be used. If <database> is omitted, ! SHOULD be used (see section 3.2). If <strat> is omitted, . SHOULD be used (see section 3.3) 🍓.
<user>;<auth>@ specifies the username and the type of authentication performed. For <auth>, the string AUTH means APOP authentication using the AUTH command will be performed. The string SASLAUTH=<auth_type> means the SASLAUTH and SASLRESP commands will be used, with <auth_type> naming the type of SASL authentication that will be used. If <auth_type> is a star (decimal code 42, *), then the client gets to pick some type of authentication 🔥.
Whenever authentication is required, the client SHOULD request additional information (e.g., a passphrase) from the user 🫶. Unlike [RFC1738], clear text passwords are not permitted in the URL 🙅♀️. Absolutely not, bestie 💀.
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:::6. Extensions 🌈
This protocol was designed so that flat text databases can be used with a server after a minimum of analysis and formatting. From experience, just building an index for a database may be enough to make it useful with a DICT server 📂✨. Being able to serve preformatted text matters a lot, since freely-available databases are often shared as flat text files with no semantic mark-up (and they often contain "ASCII art" that makes even simple automatic formatting impossible) 🎨.
However, if a database has enough mark-up information, it may be possible to generate output in a variety of formats (e.g., simple HTML or more sophisticated SGML) 👑. Specifying formatting is beyond the scope of this document. The requirements for negotiating format (including character set and other encodings) are complex and should be examined over time as more experience is gained 🤔. We suggest that 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. They SHOULD NOT be defined in any future DICT protocol specification, and they MUST NOT be used by any client software 🚫.
Commands that begin with the letter "X" are reserved for experimental extensions, and they 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 them without knowing whether a server supports them (for example, instead of using feature negotiation). If the server doesn't support the commands, then a response code in the 5yz series (usually 500) will be given, which tells the client the extension isn't supported 🙃. Of course, depending on how complex the added extensions are, feature negotiation may be necessary. To help cut down on negotiation time, server-supported features may be announced in the banner (code 220) using the optional capabilities parameter ⭐.
7. Summary of Response Codes 📝
Here's a summary of response codes. A star (*) in the first column means 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 available8. Sample Conversations 🎬
These are samples of the conversations you might expect with a typical DICT server 🍿. The notation "C:" means commands set by the client, and "S:" means responses sent by the server. Blank lines are included for clarity and do not indicate actual newlines in the transaction ✨.
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: 113 Help text follows
S: DEFINE database word look up word in database
S: MATCH database strategy word match word in database using strategy
S: [ more server-dependent help text ]
S: .
S: 250 Command complete
C: DEFINE ! penguin
S: 150 1 definitions found: list follows
S: 151 "penguin" wn "WordNet 1.5" : definition text follows
S: penguin
S: 1. n: short-legged flightless birds of cold southern esp. Antarctic
S: regions having webbed feet and wings modified as flippers
S: .
S: 250 Command complete
C: DEFINE * shortcake
S: 150 2 definitions found: list follows
S: 151 "shortcake" wn "WordNet 1.5" : text follows
S: shortcake
S: 1. n: very short biscuit spread with sweetened fruit and usu.
S: whipped cream
S: .
S: 151 "Shortcake" web1913 "Webster's Dictionary (1913)" : text follows
S: Shortcake
S: \Short"cake`\, n.
S: An unsweetened breakfast cake shortened with butter or lard,
S: rolled thin, and baked.
S: .
S: 250 Command complete
C: DEFINE abcdefgh
S: 552 No match
C: quit
S: 221 Closing connection8.2. Sample 2 - SHOW commands, MATCH command 🧁
C: SHOW DBokay bestie, we're picking up right where the SHOW DB sample left off 🎀
S: 110 3 databases present: list follows
S: wn "WordNet 1.5"
S: foldoc "Free On-Line Dictionary of Computing"
S: jargon "Hacker Jargon File"
S: .
S: 250 Command complete
C: SHOW STRAT
S: 111 5 strategies present: list follows
S: exact "Match words exactly"
S: prefix "Match word prefixes"
S: substring "Match substrings anywhere in word"
S: regex "Match using regular expressions"
S: reverse "Match words given definition keywords"
S: .
S: 250 Command complete
C: MATCH foldoc regex "s.si"
S: 152 7 matches found: list follows
S: foldoc Fast SCSI
S: foldoc SCSI
S: foldoc SCSI-1
S: foldoc SCSI-2
S: foldoc SCSI-3
S: foldoc Ultra-SCSI
S: foldoc Wide SCSI
S: .
S: 250 Command complete
C: MATCH wn substring "abcdefgh"
S: 552 No match8.3. Sample 3 - Server downtime ⏰
this one's the sad little sample 🥺 the server is just... not vibing right now. first the client tries to connect and gets told the server is temporarily unavailable 😭 then the client tries again and the server is like "nah, shutting down because the operator said so" 💀
C: [ client initiates connection ]
S: 420 Server temporarily unavailable
C: [ client initiates connection ]
S: 421 Server shutting down at operator request8.4. Sample 4 - Authentication 🔐
and finally, the glow-up sample ✨ the client connects, peeks at what databases exist, logs in with AUTH, and suddenly there's a whole extra database showing up. main character energy 👑
C: [ client initiates connection ]
S: 220 dict.org dictd (version 0.9) <27831.860032493@dict.org>
C: SHOW DB
S: 110 1 database present: list follows
S: free "Free database"
S: .
S: 250 Command complete
C: AUTH joesmith authentication-string
S: 230 Authentication successful
C: SHOW DB
S: 110 2 databases present: list follows
S: free "Free database"
S: licensed "Local licensed database"
S: .
S: 250 Command complete9. Security Considerations 🔒
okay so this section is short and sweet 🍓 this RFC raises no security issues. that's the whole tea ☕ nothing new to worry about from this document itself, periodt 💅
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,
<URL:http://wombat.doc.ic.ac.uk/> - [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,
<URL:http://www.ccil.org/jargon/> - [KNUTH73] Knuth, Donald E. "The Art of Computer Programming", Volume 3: Sorting and Searching (Addison-Wesley Publishing Co., 1973, pages 391 and 392). Knuth notes that the soundex method was originally described by Margaret K. Odell and Robert C. Russell [US Patents 1261167 (1918) and 1435663 (1922)].
- [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.
- [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 <cassidy@micra.com>. For further information, see
<URL:ftp://uiarchive.cso.uiuc.edu/pub/etext/gutenberg/etext96/pgw*>, and<URL:http://humanities.uchicago.edu/forms_unrest/webster.form.html> - [WORDNET] Miller, G.A. (1990), ed. WordNet: An On-Line Lexical Database. International Journal of Lexicography. Volume 3, Number 4.
<URL:http://www.cogsci.princeton.edu/~wn/>
11. Acknowledgements 🫶
huge thank-yous time 🌈 first, Arnt Gulbrandsen and Nicolai Langfeldt for all the helpful discussions 💜 then Bennet Yee, Doug Hoffman, Kevin Martin, and Jay Kominek, who did extensive testing and gave feedback on the first DICT server implementations 🙌 also Zhong Shao, for advice and support ✨
and a big shoutout to Brian Kanto, Phil Lapsley, and Jon Postel for writing exemplary RFCs that got consulted while this document was being put together 📖 and to Harald T. Alvestrand, whose comments helped make this document better 🦋
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 done while Bret Martin was a student at Yale University 🎓
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 implementation may be prepared, copied, published and 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. 💖
📦 where this page comes from
- ietf: rfc2229 1997-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms