RFC 1202
Directory Assistance service
RFC 1202: Directory Assistance Service 💖
okay bestie, this one is from February 1991 and it was written by M. Rose at Performance Systems International, Inc. for the Network Working Group 🎀 It's Informational, which the memo itself spells out as "provides information for the Internet community" and "does not specify any standard." It doesn't say it obsoletes or updates any other RFC, so it's a standalone little gem ✨
Status of this Memo
this memo defines a way for a user-interface to talk to a textual DAP-like interface over a TCP/IP connection 🦋 it's a local mechanism, and it's for information only, not a standard. distribution of this memo is unlimited 💅
Table of Contents
Table of Contents
1. Introduction .......................................... 1
1.1 An Aside ............................................ 3
2. Protocol .............................................. 3
2.1 Control Connection .................................. 4
2.1.1 Initialization .................................... 4
2.1.2 Transactions ...................................... 4
2.1.2.1 INTR command .................................... 4
2.1.2.2 STAT command .................................... 5
2.1.2.3 QUIT command .................................... 5
2.2 Data Connection ..................................... 5
2.2.1 Transactions ...................................... 5
2.2.2 Responses ......................................... 6
2.2.2.1 Numeric Responses ............................... 6
2.2.2.2 'm' Response .................................... 6
2.2.2.3 'y' Response .................................... 6
2.2.2.4 'p' Response .................................... 7
2.2.2.5 'e' Response .................................... 7
2.2.2.6 'l' Response .................................... 7
2.2.2.7 'd' Response .................................... 8
2.2.2.8 'P' Response .................................... 8
3. Example Interaction ................................... 9
4. References ............................................ 10
5. Security Considerations............................... 11
6. Author's Address...................................... 111. Introduction ✨
okay so the OSI Directory [1] is a seriously powerful infrastructure for retrieving information objects 🗂️ it can power things like white pages apps, application entity lookup, and so on, e.g. stuff like that 🌸
the Directory service gets to applications through the Directory Access Protocol (DAP), which binds a Directory User Agent (DUA) to a Directory System Agent (DSA) 🧚
| Directory Service
| provided via DAP
|
+-----------+ | +-----------+
| | | | |
| DUA | <----------+----------> | DSA |
| | | | |
+-----------+ | +-----------+
|
Directory User |the DAP is an OSI application layer protocol that uses the rich OSI upper-layer infrastructure 👑 the bad news is that the coding investment to implement the DAP is significant, so it's honestly hard to host Directory-using apps on smaller workstations and personal computers 😭
so this memo details a local mechanism that has been successfully used to split the functionality of the DAP away from the complexity of implementing it 🦋 it's a split-DUA model: the DAP gets implemented on an entity called the "Directory Assistant", which lives on a capable workstation or mainframe and exports a simpler interface, the "Directory Assistance" (DA) protocol, to other end-systems where the user-interface lives. that other side is called the DA-client 💜
since this mechanism helps applications that want to access the Directory, it's called the "Directory Assistance" (DA) service 🎀
| Directory Service
split-DUA | provided via DAP
|
+-----------+ | +-----------+
| | | | |
| Directory | <----------+----------> | DSA |
| Assistant | | | |
| | | +-----------+
+-----------+ |
/|\ |
| |
| DA-service |
| provide via |
| DA-protocol |
| |
------+------ |
| |
| |
| |
| |
| |
\|/ |
+-----------+ |
| | |
| DA-client | |
| | |
+-----------+ |
|
Directory User |1.1. An Aside
this memo documents a protocol that already existed, and it was originally used to give a split-DUA model within the same host 🌈 without a super detailed historical and implementation understanding, some of the mechanisms might look kinda unintuitive, so don't be surprised if they feel weird 🙈
2. Protocol 🌸
the DA service runs over two TCP connections: a control connection and a data connection 💅 the control connection defines the lifetime of an instance of the DA service. during that lifetime, several data connections can be set up. BUT at any given instant there are between zero and one data connections in progress, so it's never more than one at a time ✨
the DA service is provided by the "Directory Assistant", which is made of two entities: a DA-server, which manages the control connection, and a DAP-listener, which responds to commands on the data connection. the DA-server oversees how the DAP-listener behaves 👑
2.1. Control Connection
data over the control connection is a series of transactions 🍓 the wording is expressed in NVT-ASCII. each transaction is the client sending a directive (a line of text ending in CR-LF), and then the DA-server sending back a response (also a line of text ending in CR-LF). every response from a DA-server starts with either +OK or -ERR, depending on whether the transaction worked 🫶
2.1.1. Initialization
a DA-server listens on TCP port 411 for incoming connections 🦋 once a control connection is set up, the DA-server sends back a response that says whether the service has started. if it worked, the response has an IP-address and a TCP port, written in NVT-ASCII and separated by one or more space characters. that info is the TCP-endpoint the DAP-listener will use for the data connection 💖
note that the DA-server and DAP-listener don't have to live at the same IP-address 🌍 down the road, DA-servers might use an internal protocol for load-balancing purposes ✨
if the DA service can't get started, an error response gets sent back and the control connection gets closed 💀
2.1.2. Transactions
every transaction with the DA-server is a command followed by zero or more arguments, separated by the space character 🧚
2.1.2.1. INTR command
the INTR command takes no arguments 💅 it's used to interrupt any DAP transaction that's currently in progress 🔥 and the INTR command always returns success 🎀
2.1.2.2. STAT command
the STAT command takes no arguments 💅 it's used to check that the DAP-listener is available. it returns success only if the DAP-listener is still active 🫶
2.1.2.3. QUIT command
the QUIT command takes no arguments 💅 it's used to terminate the DA service, and it always returns success 👋
2.2. Data Connection
data over a data connection is a single DAP-transaction 🌈 the text is again expressed in NVT-ASCII. the client sends a command (a line of text ending in the LF character), and then the DAP-listener returns zero or more responses, each with a specific termination sequence. every response from a DAP-listener starts with a single identifying character 🍓
here's the deal with that character: if it's a digit (0-9), the termination sequence is closing the data connection. if it's a lower-case letter (a-z), the response is interactive and gets terminated by the LF character 😭
2.2.1. Transactions
every transaction with the DAP-listener is a command followed by zero or more arguments, separated by the space character 💜 double-quotes can be used to stop tokens from being separated 🎀
the command set comes from the DISH program 🦋
add add a new entry
bind connect to the Directory
compare compare entry's attribute
delete delete an entry
fred back-end to FrED
list list children
modify modify an existing entry
modifyrdn modify an entry's name
moveto move to a position
search search for an object
showentry show an entry
showname show an entry's name
squid status of dish
unbind disconnect from the Directorysee [2] for the complete list of commands and arguments 📚
note that commands and arguments are in lower-case, and they may be abbreviated to any unique prefix ✨
2.2.2. Responses
there are two kinds of responses 💖 numeric-responses are made of arbitrary text, and letter-responses are made of brief text and expect further interaction from the client 🫶
2.2.2.1. Numeric Responses
so for numeric responses, here's what each digit means 🔢
1: the DAP-transaction terminated normally 🎉2: the DAP-transaction failed 💀3: the DAP-transaction was a search that returned more than one result, and one of the-hitoneor-listoption was selected for the search 👀4: the DAP-transaction terminated normally, and the rest of this line is the name of an entry (see the'd'Response below) 🦋5: all children of an entry were found by the DAP-transaction 🌳
once the response is completely sent, the DAP-listener closes the data connection 🔒
heads up: even though numeric responses use ASCII, they are not NVT-ASCII. the LF character marks end-of-line here, not the CR-LF line termination sequence that NVT-ASCII uses 🙈
2.2.2.2. 'm' Response
the 'm' response contains a one-line message that should be shown to the user 💬
at this point, the client sends back a response made of 'm' followed by the LF character 🫶 then the client should keep reading from the existing data connection 📖
more of this one comes in part 2 🎀💅
2.2.2.3. 'y' Response ✨
okay so the 'y' response is the DAP-listener asking a yes/no question 🙋♀️ the client should show that question to the user. after they answer, send back either 'y' or 'n', followed by the LF-character, to the DAP-listener. then keep reading from the same data connection like nothing happened 💅
2.2.2.4. 'p' Response 🔐
the 'p' response is a password prompt, and it should be shown to the user too. once the user answers, the client sends back 'p', then the password they typed, then the LF-character. then keep reading from the existing data connection. (the password stays between you and the DAP-listener, bestie 🤫)
2.2.2.5. 'e' Response ✏️
the 'e' response is the DAP-listener asking the user to edit some text, and it's giving very "edit this doc" energy 📝 after the 'e' comes a decimal number written in ASCII, then the LF-character. that number is how many octets should be shown to the user for editing, and those octets are allowed to include LF-characters too (chaotic, I love it 🌈).
next, the client sends back one single character followed by the LF-character. if that character is 'e', the edit is aborted (for example, the text is too big 😭), and the client keeps reading from the existing data connection.
if it's anything else, the DAP-listener sends the indicated number of octets, which is the buffer the user is going to edit. after the user edits it, one of two responses should be sent.
if the user aborted the edit, the response sent to the DAP-listener is a single character 'e', followed by the LF-character.
otherwise, the response consists of any single character other than indicating the number of octets immediately following that resulted from the user-edit.
heads up bestie: the original text literally drops a word right there (it goes straight from "other than" to "indicating"), so I'm keeping it exactly as written so nobody gets confused 🙈
regardless of how it turns out, the client should then continue reading from the existing data connection. ✨
2.2.2.6. 'l' Response 📋
the 'l' response is one entry for a selection list the user gets to browse 👀 the entry is two strings separated by the '$' character, and it ends with the LF-character. the first string is a user-friendly name that's fine to show the user. the second string is a fully-qualified Distinguished Name in textual format.
the client sends back 'l' followed by the LF-character. it should keep collecting selection entries until it hits an LF-character.
at that point, the user should be asked to pick one or more of the entries 💖 once they pick, the client sends back 'L', then one or more decimal numbers in ASCII, then the LF-character. the numbers are separated by spaces and match the entries the user chose. (the entry from the first 'l' response is number 1, and so on 🧚)
then the client keeps reading from the existing data connection.
2.2.2.7. 'd' Response 💌
the 'd' response carries a name the client might be interested in. same vibe as the 'l' entries: two strings separated by the '$' character, ending with the LF-character. the first string is the user-friendly name, and the second is a fully-qualified Distinguished Name in textual format.
the client sends back 'd' followed by the LF-character, then keeps reading from the existing data connection.
2.2.2.8. 'P' Response 📸
the 'P' response is how a picture gets sent to the client, and I'm obsessed 😭 after the 'P' comes a decimal number in ASCII (that's the size of the picture), then a name, then the LF-character. the name has three strings separated by the '$' character. the first is the name of the attribute that goes with the picture, in textual format. the second is a user-friendly name for display. the third is a fully-qualified Distinguished Name in textual format.
at this point, the client sends back one single character followed by the LF-character. if that character is 'P', the picture won't be sent (maybe the image is too large 💀), and the client keeps reading from the existing data connection.
otherwise, the DAP-listener sends the indicated number of octets for the picture. the picture is encoded using the PBM format from the PBMPLUS package 🖼️
regardless of the outcome, the client should then continue reading from the existing data connection. 🫶
3. Example Interaction 🎀
okay so in the stuff that comes next, the prefixes tell you who's talking. "S:" is the DA-server, "L:" is the DAP-listener, "C:" is the client talking to the DA-server, and "I:" is the client talking to the DAP-listener. let's watch the whole thing play out 🍿
S: <wait for connection on TCP port 411>
C: <open connection to DA-server>
L: <wait for connections>
S: +OK 192.33.4.21 32867
I: <open connection to DAP-listener>
I: bind -simple -user "@c=US@cn=Manager"
L: pc=US@cn=Manager
-- client asks user for password for "c=US@cn=Manager"
I: psecret
L: <closes connection, signaling success but no response>
-- since response was null, client verifies that DAP-listener
-- is still operating...
C: STAT
S: +OK
I: <open connection to DAP-listener>
I: fred -expand "@"
L: 5
North America$l=North America
US$c=US
...
L: <closes connection>
I: <open connection to DAP-listener>
I: fred -ufn rose,psi,us
L: 1
<followed by much data>
L: <closes connection>
I: <open connection to DAP-listener>
I: fred -ufn -list,rose,ps,us
L: lHewlett-Packard, US$c=US@o=Hewlett-Packard
I: l
L: lPerformance Systems International, US$c=US@o=Performance...
I: l
L: lRutgers University, US$c=US@o=Rutgers University
I: l
L: Lps
-- client presents selection list to user asking to select
-- matches for 'ps', user selects the 2nd
I: L 2
L: dManager, US$c=US@cn=Manager
I: d
L: 4Marshall Rose, ...$c=US@o=Performance...
<followed by much data>
L: <closes connection>
I: <open connection to DAP-listener>
I: fred -ufn -list,schoffstall,ps,us
L: 33 matches found.
Martin Schoffstall, ...$c=US@o=Performance...
Marvin Schoffstall, ...$c=US@o=Performance...
Steve Schoffstall, ...$c=US@o=Performance...
L: <closes connection>
C: QUIT
L: <stop listening for connections>
S: +OK
C: <close connection>
S: <wait for next connection>and that's the full vibe 🦋 the client quits, the listener stops, and the DA-server goes back to waiting for the next person to show up ✨
4. References 📚
[1] Information Processing - Open Systems Interconnection - The Directory, International Organization for Standardization. International Standard 9594, (1988).
[2] Kille, S., Robbins, C., Roe, M., and A. Turland, "The ISO Development Environment: User's Manual", Volume 5: QUIPU, Performance Systems International, January 1990.
5. Security Considerations 🔥
yikes, the memo itself says security considerations are not discussed in this memo. no cap, that's a whole plot twist 💀
6. Author's Address 💜
Marshall T. Rose
PSI, Inc.
PSI California Office
P.O. Box 391776
Mountain View, CA 94039
Phone: (415) 961-3380
EMail: mrose@psi.comthe end, bestie! 🌈✨💖
📦 where this page comes from
- ietf: rfc1202 1991-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms