DIXIE Protocol Specification
A lightweight UDP and TCP gateway that lets small hosts query and edit the OSI X.500 Directory.
Howes, T., Smith, M., and B. Beecher, "DIXIE Protocol Specification", RFC 1249, DOI 10.17487/RFC1249, August 1991, <https://www.rfc-editor.org/info/rfc1249>.
@misc{rfc1249,
series = {Request for Comments},
number = 1249,
howpublished = {RFC 1249},
publisher = {RFC Editor},
doi = {10.17487/RFC1249},
url = {https://www.rfc-editor.org/info/rfc1249},
author = {T. Howes and M. Smith and B. Beecher},
title = {{DIXIE Protocol Specification}},
pagetotal = 10,
year = 1991,
month = aug,
} RFC text
Contents
Network Working Group T. Howes
Request for Comments: 1249 M. Smith
B. Beecher
University of Michigan
August 1991
DIXIE Protocol Specification
Status of this Memo
This RFC defines a mechanism by which TCP/UDP based clients can
access OSI Directory Service without the overhead of the ISO
transport and presentation protocols required to implement full-blown
DAP. This memo provides information for the Internet community. It
does not specify any standard. Distribution of this memo is
unlimited.
Table of Contents
1. Introduction .............................................. 2
1.1 History .................................................. 2
2. Protocol .................................................. 2
2.1 Header ................................................... 3
2.2 Operations ............................................... 4
2.2.1 Read ................................................... 4
2.2.1.1 Read Request ......................................... 4
2.2.1.2 Read Reply ........................................... 4
2.2.2 Search ................................................. 5
2.2.2.1 Search Request ....................................... 5
2.2.2.2 Search Reply ......................................... 5
2.2.3 List ................................................... 5
2.2.3.1 List Request ......................................... 5
2.2.3.2 List Reply ........................................... 5
2.2.4 Modify ................................................. 5
2.2.4.1 Modify Request ....................................... 6
2.2.4.2 Modify Reply ......................................... 6
2.2.5 Modify RDN ............................................. 6
2.2.5.1 Modify RDN Request ................................... 6
2.2.5.2 Modify RDN Reply ..................................... 6
2.2.6 Add .................................................... 6
2.2.6.1 Add Request .......................................... 7
2.2.6.2 Add Reply ............................................ 7
2.2.7 Remove ................................................. 7
2.2.7.1 Remove Request ....................................... 7
2.2.7.2 Remove Reply ......................................... 7
2.2.8 Bind ................................................... 7
2.2.8.1 Bind Request ......................................... 7
2.2.8.2 Bind Reply ........................................... 8
2.3 Operation Code Summary ................................... 8
2.4 Return Code Summary ...................................... 8
3. References ................................................ 9
4. Available Implementations ................................. 9
5. Security Considerations.................................... 9
6. Authors' Addresses ........................................ 10
1. Introduction
OSI Directory Service defines a powerful mechanism for storing and
retrieving information about objects, and for arranging those objects
in a hierarchical structure. Many types of objects and information
can be stored in The Directory, including white pages information,
application information, service information, etc. The OSI protocol
defined to allow access to this information is the Directory Access
Protocol (DAP). The DAP, being an OSI application-layer program, is
fairly heavy-weight and requires a substantial amount of computing
power and coding investment to implement.
The DIXIE protocol is designed for use by smaller hosts (e.g.,
Macintoshes and PCs) that do not have the computing power or
necessary software to implement a full OSI protocol stack. The DIXIE
protocol is also useful for any Internet application that wants a
simple interface to X.500 that requires very little coding
investment.
The basic idea behind DIXIE is the same as that described in RFC 1202
for the Directory Assistance Protocol. DIXIE offers both UDP and TCP
access to The Directory. While the Directory Assistance Protocol
exports something of a user interface, DIXIE provides a more direct
protocol translation.
1.1 History
The DIXIE protocol has evolved over time, slowly growing into the
protocol described by this document. Without an understanding of the
circumstances surrounding this evolution, the wisdom of some of the
DIXIE design decisions may not be apparent.
2. Protocol
This section describes the DIXIE protocol in detail. DIXIE follows a
client-server request and response paradigm. Clients send request
packets to a DIXIE server, and the server sends reply packets in
return. Communication may be over UDP or TCP, depending upon the
needs of the client. All modification operations (ADD, REMOVE,
MODIFY, MODIFYRDN) must be performed over a TCP connection, which
provides some level of authentication.
Whichever method of communication is used, the general packet format
is the same. Each packet consists of a sixteen octet header followed
by some data. The format of the header and data for each kind of
request is described below.
The representation used for all X.500 data passed between the server
and the client is the QUIPU EDB format. So, for example, a
Distinguished Name might look something like "c=US@o=University of
Michigan". For a complete description of this format, see volume 5
of the ISODE Manual.
The DIXIE server listens on port 96 for both UDP packets and TCP
connections.
2.1 Header
The DIXIE packet header is sixteen octets long. For requests, the
header is described by the following:
Start Length Description
0 1 An opcode specifying one of the operations
described below. (see section 2.3 for a summary)
1 2 A request identifier to be included in the reply.
This number should be unique to a request.
3 4 The total length of the request packet, excluding
the header.
7 2 Unused.
9 1 Options. Currently, there are only three options.
If bit 0 is set, "large" attributes will be
included in the response. The choice of what
constitutes large is up to the implementation.
If bit 1 is set, the dereference aliases service
control will be set for the X.500 operation. If
bit 2 is set, aliases will NOT be dereferenced and
searched during a search operation.
10 1 Protocol version. The current version is 1.
11 1 For the search operation, this byte specifies the
scope of the search. (see section 2.2.2.1)
12 2 Timelimit in seconds for the operation.
14 2 Sizelimit for the operation (search and list).
For replies, the header is described by the following:
Start Length Description
0 1 A return code specifying either success or
describing any error that occurred. (see
section 2.4 for a description of each code)
1 2 The identifier included in the corresponding
request packet.
3 4 The total length of the response packet, excluding
the header.
7 3 Unused.
10 1 Protocol version. The current version is 1.
11 5 Unused.
All unused fields should be set to null octets and are reserved for
future expansion.
2.2 Operations
This section describes the DIXIE operations, which closely parallel
the X.500 DAP operations.
2.2.1 Read
The DIXIE read operation corresponds to an X.500 DAP READ operation.
2.2.1.1 Read Request
The header opcode should be set to 0x01. The data portion of the
packet consists of the DN of the entry to read, a null octet, and
then a null-octet separated list of attributes whose values are to be
returned from the read. If no attributes to return are listed, all
attributes are returned. The packet is terminated by two null octets
in a row.
2.2.1.2 Read Reply
The reply data for the read operation consists of the entry read,
followed by a null octet. An entry consists of the DN of the entry,
followed by the octet 0x02, followed by a 0x02-octet separated list
of attribute values. An attribute value consists of an attribute
type, followed by the octet 0x01, followed by a 0x01-octet separated
list of values. Each attribute type, attribute value and
distinguished name has the form defined by the QUIPU EDB format.
2.2.2 Search
The DIXIE search operation corresponds to an X.500 DAP SEARCH
operation.
2.2.2.1 Search Request
The header opcode should be set to 0x0f. Octet 11 in the header
should be set to 0x01, 0x02, or 0x03, for a search scope of base
object, one level, or whole subtree, respectively. The data portion
of the packet consists of the DN of the entry from which to start the
search, a null octet, a string containing the search filter (dish-
style), a null-octet, and then a null-octet separated list of
attributes whose values are to be returned from the search. If no
attributes to return are listed, all attributes are returned. The
packet is terminated by two null octets in a row.
2.2.2.2 Search Reply
The reply data to the search operation consists of two octets in
network byte order specifying the number of matches returned. Next
comes this number of sequences of the form: one 0x03 octet followed
by one entry. Each entry is as described above in section 2.2.1.2.
2.2.3 List
The DIXIE list operation corresponds to an X.500 DAP LIST operation.
2.2.3.1 List Request
The header opcode should be set to 0x10. The data portion of the
packet consists of the DN of the entry on which to perform the list,
followed by a null octet.
2.2.3.2 List Reply
The reply data to the list operation consists of two octets in
network byte order specifying the number of subordinates returned,
followed by this number of sequences of the form: one 0x03 octet
followed by a Relative Distinguished Name of a subordinate.
2.2.4 Modify
The DIXIE modify operation corresponds to an X.500 DAP MODIFY
operation.
2.2.4.1 Modify Request
The header opcode should be set to 0x02. The data portion of the
packet consists of the DN of the entry to modify, followed by a null
octet, followed by a null-separated list of modify operations to
perform. Each modify operation is one of the following:
type remove attribute type
type=value make value the sole value for attribute type
type+=value add value to attribute type
type-=value remove value from attribute type
The second form will see to it that existing values (if any) are
deleted before the new ones are added. The third form will add the
attribute type if it does not already exist. Note that the QUIPU EDB
format, used to specify value, allows multiple values to be specified
separated by the "&" character. This operation is only allowed over
TCP.
2.2.4.2 Modify Reply
There is no reply data for the modify operation. The only indication
of success or failure is the return code in the header.
2.2.5 Modify RDN
The DIXIE modify RDN operation corresponds to an X.500 DAP MODIFYRDN
operation.
2.2.5.1 Modify RDN Request
The header opcode should be set to 0x13. The data portion of the
packet consists of the DN of the entry to modify, followed by a null
octet, followed by the new RDN the entry should have, followed by a
final null octet. The old value of the RDN is never kept as an
attribute of the entry. This operation is only allowed over TCP.
2.2.5.2 Modify RDN Reply
There is no reply data to the modify RDN operation. The only
indication of success or failure is the return code in the header.
2.2.6 Add
The DIXIE add operation corresponds to an X.500 DAP ADD operation.
2.2.6.1 Add Request
The header opcode should be set to 0x11. The data portion of the
packet consists of the DN of the entry to add, followed by a null
octet, followed by a null-separated list of the entry's attributes.
Each attribute in this list has the form:
type=value
where value can consist of a single value, or multiple values
separated by the "&" character. The request is terminated by two
null octets in a row. This operation is only allowed over TCP.
2.2.6.2 Add Reply
There is no reply data to the add operation. The only indication of
success or failure is the return code in the header.
2.2.7 Remove
The DIXIE remove operation corresponds to an X.500 DAP REMOVE
operation.
2.2.7.1 Remove Request
The header opcode should be set to 0x12. The data portion of the
packet consists of the DN of the entry to remove, followed by a null
octet. This operation is only allowed over TCP.
2.2.7.2 Remove Reply
There is no reply data for the remove operation. The only indication
of success or failure is the return code in the header.
2.2.8 Bind
The DIXIE bind operation corresponds to an X.500 DAP BIND operation
using simple authentication as defined in Recommendation X.509.
2.2.8.1 Bind Request
The header opcode should be set to 0x04. The data portion of the
packet consists of the DN of the entry as which to bind, followed by
a null octet, followed by the password of the entry as which to bind,
followed by a final null octet. A null DN corresponds causes a bind
as NULLDN to occur.
2.2.8.2 Bind Reply
The format of the bind reply packet depends on whether the operation
was invoked over TCP or UDP. If the operation was invoked over TCP,
there is no reply data. Success or failure of the operation is
indicated by the return code in the packet header.
If the bind operation was invoked over UDP, the data portion of the
reply packet consists of an Internet address in standard dot
notation, followed by a 0x01 octet, followed by a decimal number (in
text form), followed by a null octet. The address and number should
be taken to be the IP address and port number to which the client
should connect to obtain an authenticated TCP connection, bound as
the entity specified in the request packet.
2.3 Operation Code Summary
This section describes the possible values for the DIXIE header
operation code. There are currently 8 possible values:
0x01 Read
0x02 Modify
0x04 Bind
0x0f Search
0x10 List
0x11 Add
0x12 Remove
0x13 Modify RDN
2.4 Return Code Summary
This section describes the possible values for the the DIXIE header
return code. There are currently 17 possible values:
0x01 The request was successful.
0x02 The search did not find any matches.
0x03 Some unknown, generic DIXIE error has occurred.
0x04 The DIXIE opcode was not recognized by the DIXIE server.
0x05 Insufficient access to perform a modification.
0x06 A malformed DN was supplied.
0x07 Some time limit or size limit was reached.
Partial results will be returned.
0x08 A modify was attempted before a bind.
0x09 A fragment requested was not found.
0x0a An attribute type specified is invalid.
0x0b An attribute specified does not exist in the entry.
0x0c An attribute value specification is invalid.
0x0d An attribute value does not exist (as for removal of the
value).
0x0e A modification of an entry's RDN was attempted via a modify
operation. This is not allowed (use modrdn instead).
0x0f A supplied DN references an invalid portion of the tree.
0x10 The DSA has passed back a referral to another DSA (as for a
modification to a non-local entry), and the DIXIE server was
unable to follow it.
0x11 The DSA is down or unreachable.
3. 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.
[3] Rose, M., "Directory Assistance Service", RFC 1202, Performance
Systems International, February 1991.
4. Available Implementations
This section is not meant as an endorsement of any
implementation, it is provided merely as information for the
Internet community. A full Un*x-based implementation of the
DIXIE protocol in the form of a DIXIE server and DIXIE
application library is freely available for anonymous FTP from
the host terminator.cc.umich.edu in the ~ftp/x500 directory.
Un*x and Macintosh clients that use the DIXIE protocol have also
been implemented and are available from the same location.
There is also a discussion list for DIXIE-related topics called
dixie@terminator.cc.umich.edu. To join, send mail to dixie-
request@terminator.cc.umich.edu.
5. Security Considerations
Security issues are not discussed in this memo.
6. Authors' Addresses
Tim Howes
University of Michigan
Information Technology Division
535 West William St.
Ann Arbor, MI 48103-4943
Phone: +1 313 764-2278
EMail: tim@umich.edu
Mark Smith
University of Michigan
Information Technology Division
535 West William St.
Ann Arbor, MI 48103-4943
Phone: +1 313 764-2277
EMail: mcs@umich.edu
Bryan Beecher
University of Michigan
Information Technology Division
535 West William St.
Ann Arbor, MI 48103-4943
Phone: +1 313 764-4050
EMail: bryan@umich.edu
ISO Plain Language
On this page
§1Why DIXIE Exists
The OSI Directory Service defines a powerful mechanism for storing and retrieving information about objects, and for arranging those objects in a hierarchical structure. Many types of objects and information can be stored in the directory, including white pages information, application information and service information. The OSI protocol defined to allow access to this information is the Directory Access Protocol. The DAP, being an OSI application-layer program, is fairly heavy-weight and requires a substantial amount of computing power and coding investment to implement.
The DIXIE protocol is designed for use by smaller hosts, such as Macintoshes and PCs, that do not have the computing power or the necessary software to implement a full OSI protocol stack. It is also useful for any Internet application that wants a simple interface to X.500 that requires very little coding investment.
The basic idea behind DIXIE is the same as that described in RFC 1202 for the Directory Assistance Protocol. DIXIE offers both UDP and TCP access to the directory. While the Directory Assistance Protocol exports something of a user interface, DIXIE provides a more direct protocol translation.
DIXIE follows a client-server request and response paradigm. Clients send request packets to a DIXIE server, and the server sends reply packets in return. Communication may be over UDP or TCP, depending on the needs of the client. All modification operations, that is ADD, REMOVE, MODIFY and MODIFYRDN, must be performed over a TCP connection, which provides some level of authentication.
Whichever method of communication is used, the general packet format is the same. Each packet consists of a sixteen octet header followed by some data. The representation used for all X.500 data passed between the server and the client is the QUIPU EDB format, so a Distinguished Name might look something like c=US@o=University of Michigan. The DIXIE server listens on port 96 for both UDP packets and TCP connections. The RFC notes that the protocol has evolved over time and that, without an understanding of the circumstances surrounding that evolution, the wisdom of some of the design decisions may not be apparent.
The idea is the same as for the Directory Assistance service, but sharper: instead of exporting a user interface, DIXIE exports the directory operations themselves, with a small fixed-size header in front of each one.
§2.1The Sixteen-Octet Header
The DIXIE packet header is sixteen octets long. For requests it is laid out as follows. At offset 0, one octet holds an opcode specifying one of the operations. At offset 1, two octets hold a request identifier to be included in the reply, which should be unique to a request. At offset 3, four octets hold the total length of the request packet, excluding the header. Offset 7 has two unused octets. At offset 9, one octet holds options, of which there are currently only three: if bit 0 is set, large attributes will be included in the response, and the choice of what constitutes large is up to the implementation; if bit 1 is set, the dereference aliases service control will be set for the X.500 operation; and if bit 2 is set, aliases will not be dereferenced and searched during a search operation. At offset 10, one octet holds the protocol version, currently 1. At offset 11, one octet specifies the scope of a search. At offset 12, two octets hold a time limit in seconds for the operation, and at offset 14, two octets hold a size limit for the operation, used by search and list.
The reply header has the same length but a different arrangement. Offset 0 holds a return code specifying either success or describing any error that occurred. Offset 1 holds the two octets of the identifier included in the corresponding request packet. Offset 3 holds the four octets of the total length of the response packet, excluding the header. Offset 7 has three unused octets, offset 10 holds the protocol version, and offset 11 has five unused octets. All unused fields should be set to null octets and are reserved for future expansion.
Every request and reply starts with the same sixteen bytes: what to do, which request this is, how long the answer will be, and a few switches. The bytes in between are the directory data itself.
| Field | Name | Size | Value | Description |
|---|---|---|---|---|
OPCODE | Opcode | 1 byte | 0x01 | Which operation to perform. |
REQUEST-ID | Request ID | 2 bytes | Identifier included in the reply; should be unique to a request. | |
LENGTH | Length | 4 bytes | Total length of the request packet, excluding the header. | |
UNUSED | Unused | 2 bytes | Reserved for future expansion; set to null octets. | |
OPTIONS | Options | 1 byte | Bit 0 asks for large attributes, bit 1 sets dereference aliases, bit 2 suppresses dereferencing aliases in a search. | |
VERSION | Protocol Version | 1 byte | 1 | The protocol version in use. The current version is 1. |
SCOPE | Search Scope | 1 byte | For a search: base object, one level, or whole subtree. | |
TIMELIMIT | Timelimit | 2 bytes | Time limit in seconds for the operation. | |
SIZELIMIT | Sizelimit | 2 bytes | Size limit for the operation, used by search and list. |
§2.2The Eight Operations
The DIXIE operations closely parallel the X.500 DAP operations, and there are eight of them.
Read, opcode 0x01, asks for one entry. The data is the distinguished name of the entry to read, a null octet, and then a null-octet separated list of attributes whose values are to be returned. If no attributes are listed, all are returned, and the packet is terminated by two null octets in a row. The reply data is the entry read followed by a null octet: an entry consists of the distinguished name, the octet 0x02, and a list of attribute values separated by 0x02 octets, where an attribute value consists of an attribute type, the octet 0x01, and a list of values separated by 0x01 octets.
Search, opcode 0x0f, looks for entries under a given one. Octet 11 of the header gives the scope: 0x01 for a base object, 0x02 for one level, or 0x03 for the whole subtree. The data is the distinguished name of the entry to start from, a null octet, a string containing the search filter in dish-style, a null octet, and then a null-octet separated list of attributes to return. The reply begins with two octets in network byte order giving the number of matches, followed by that many sequences of one 0x03 octet and one entry.
List, opcode 0x10, names the subordinates of an entry. The request data is the distinguished name of the entry followed by a null octet, and the reply gives the number of subordinates returned and then that many sequences of a 0x03 octet and a relative distinguished name.
Modify, opcode 0x02, changes an entry. The data is the distinguished name of the entry, a null octet, and a null-separated list of modify operations: type removes an attribute type; type=value makes the value the sole value for the attribute type, deleting any existing values first; type+=value adds a value to the attribute type, creating the type if it does not already exist; and type-=value removes a value from the attribute type. The QUIPU EDB format used to specify the value allows multiple values separated by the ampersand character. This operation is only allowed over TCP, and there is no reply data, so the return code in the header is the only indication of success or failure.
Modify RDN, opcode 0x13, renames an entry. The data is the distinguished name of the entry to modify, a null octet, the new relative distinguished name, and a final null octet. The old value is never kept as an attribute of the entry. This operation is only allowed over TCP and again has no reply data.
Add, opcode 0x11, creates an entry. The data is the distinguished name of the new entry, a null octet, and a null-separated list of its attributes, each of the form type=value where the value can be a single value or several separated by the ampersand character. The request is terminated by two null octets. This operation is only allowed over TCP, with no reply data.
Remove, opcode 0x12, deletes an entry. The data is the distinguished name of the entry to remove followed by a null octet. This operation is only allowed over TCP, with no reply data.
Bind, opcode 0x04, corresponds to a DAP BIND using simple authentication as defined in Recommendation X.509. The data is the distinguished name of the entry as which to bind, a null octet, the password of that entry, and a final null octet. A null distinguished name causes a bind as NULLDN. The reply depends on the transport: over TCP there is no reply data and the return code alone says whether it worked, while over UDP the reply data is an Internet address in dot notation, the octet 0x01, a decimal number in text form, and a null octet, giving the address and port the client should connect to for an authenticated TCP connection bound as the entity named in the request.
Eight verbs, matching the directory's own: read one entry, search, list what is underneath, change an entry, rename it, add one, delete one, and log in. Anything that changes the directory has to go over TCP.
- 0x01Read — Return one entry and its attributes.
- 0x02Modify — Change the attributes of an entry. Only over TCP.
- 0x04Bind — Authenticate as an entry, with a name and a password.
- 0x0fSearch — Find entries under a given entry, with a filter and a scope.
- 0x10List — Name the subordinates of an entry.
- 0x11Add — Create a new entry. Only over TCP.
- 0x12Remove — Delete an entry. Only over TCP.
- 0x13Modify RDN — Rename an entry. Only over TCP.
§2.4Return Codes
The return code in the reply header says whether the request succeeded or describes the error. There are seventeen values. 0x01 means the request was successful, and 0x02 that the search did not find any matches. 0x03 is some unknown, generic DIXIE error, and 0x04 that the opcode was not recognized by the DIXIE server. 0x05 means insufficient access to perform a modification, and 0x06 that a malformed distinguished name was supplied. 0x07 means some time limit or size limit was reached, in which case partial results will be returned. 0x08 means a modify was attempted before a bind. 0x09 means a fragment requested was not found, and 0x0a that an attribute type specified is invalid. 0x0b means an attribute specified does not exist in the entry, and 0x0c that an attribute value specification is invalid. 0x0d means an attribute value does not exist, as for removal of the value. 0x0e means a modification of an entry's relative distinguished name was attempted via a modify operation, which is not allowed, and modrdn should be used instead. 0x0f means a supplied distinguished name references an invalid portion of the tree. 0x10 means the Directory System Agent has passed back a referral to another DSA, as for a modification to a non-local entry, and the DIXIE server was unable to follow it. 0x11 means the DSA is down or unreachable.
Most of the codes say something practical: you have not logged in yet, that attribute is not there, the address you gave is not in the tree, or the directory server on the far side is down.
- 0x01Success — The request was successful.
- 0x02No matches — The search did not find any matches.
- 0x03Generic error — Some unknown, generic DIXIE error has occurred.
- 0x04Unknown opcode — The opcode was not recognized by the DIXIE server.
- 0x05Insufficient access — Insufficient access to perform a modification.
- 0x06Malformed DN — A malformed distinguished name was supplied.
- 0x07Limit reached — A time limit or size limit was reached; partial results are returned.
- 0x08Modify before bind — A modify was attempted before a bind.
- 0x09Fragment not found — A fragment requested was not found.
- 0x0aInvalid attribute type — An attribute type specified is invalid.
- 0x0bNo such attribute — An attribute specified does not exist in the entry.
- 0x0cInvalid value — An attribute value specification is invalid.
- 0x0dNo such value — An attribute value does not exist, as for removal of the value.
- 0x0eWrong operation — A modification of an entry's relative distinguished name was attempted via a modify operation.
- 0x0fInvalid tree portion — A supplied distinguished name references an invalid portion of the tree.
- 0x10Referral not followed — The DSA passed back a referral to another DSA and the DIXIE server could not follow it.
- 0x11DSA unreachable — The DSA is down or unreachable.
§5Security Considerations
The memo says in one line that security issues are not discussed in it. It notes only that the modification operations have to be performed over a TCP connection, which provides some level of authentication, and that the bind operation carries a password in the simple form defined by Recommendation X.509.
The memo does not analyse security. It does insist that changes travel over TCP, and that a client identifies itself with a name and a password.