Data Stream Interface
The Data Stream Interface (DSI)" is a session layer used to carry Apple Filing Protocol traffic over Transmission Control Protocol.
Overview
DSI is a protocol to transport Apple Filing Protocol traffic over Transmission Control Protocol. It was invented by Apple Computer and is very similiar to the AppleTalk Session Protocol (ASP).
Specification
DSI is never documented separately, and is sufficiently simple and static that older references are suitable for modern implementations. The most recent version is in the "AFP over TCP" section of Apple Filing Protocol Version 2.1 and 2.2.
Protocol
DSI is spoken between a client and a server (typically an AFP server). All DSI communication happens within the following DSI header:
Packet structure
| Bit offset | Bits 0–7 | 8-15 | 15-23 | 24-31 | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Flags | Command | Request ID | |||||||||||||||||||||||||||||
| 32 | Error code/ enclosed data offset | |||||||||||||||||||||||||||||||
| 64 | Total data length | |||||||||||||||||||||||||||||||
| 96 | Reserved | |||||||||||||||||||||||||||||||
| 128 | Payload | |||||||||||||||||||||||||||||||
The fields are:
- Flags: whether the packet is a request (0x00) or a reply (0x01)
- Command: one of 7 possible commands (see below)
- Request ID: a sequential identifier set on the request and copied in the reply
- Error code/ enclosed data offset:
- For requests, this is left as 0, except when using the DSIWrite command.
- For replies, this is an error code.
- Total data length: the entire length of data after the DSI header
- Reserved: for future expansion
- Payload: this is where limited DSI data or more commonly AFP header is placed
Commands
There are seven possible commands[2]:
| Name | Code | Direction | Description |
|---|---|---|---|
| DSICloseSession | 1 | Both | Closes an established session |
| DSICommand | 2 | From client | Attached payload contains an AFP command |
| DSIGetStatus | 3 | From client | Get information about the server |
| DSIOpenSession | 4 | From client | Establish a new session |
| DSITickle | 5 | Both | Ensure the connection is active |
| DSIWrite | 6 | From client | Write data to the server |
| DSIAttention | 8 | From server | Get the attention of the client |
Requests and replies
All DSI requests that are processed are responded to with a reply message. The reply contains:
- the flags field set to 0x01 (reply)
- the command set to the same as the request's
- the same request ID sent in the request (used for the client to find the request being acknowledged)
- optionally, the length of the data and the data itself
Session creation, maintenance and teardown
A session is setup by the client sending a DSIOpenSession, which will include the size of the receive buffer the client have for DSIAttention packages (called the Attention Quantum, typically 1024). The server acknowledges the request and returns the size of its data receive buffer (typically 256k on Mac OS X Leopard).
Session closure can be initiated by either side b sending DSICloseSession. The opposite side should acknowledge this, although frequently the TCP connection is reset immediately after.
Maintaining the connection is done by tickling. DSI provides a mechanism for ensuring that client and server know that the other is still active. Every 30 seconds of inactivity, the server sends a tickle request to the client, which responds with its own tickle. If the client receives no such request, it sends a tickle. Either the client or server can terminate the DSI session if they fail to hear from the other for 120 seconds.
Getting server information with GetStatus
This is the most complex DSI command. It is used by a client to get information from a server it isn't logged into.
The data elements are organized in the packet with a catalog of indices pointing to structured data[3].
The request to a DSIGetStatus request will cause the server to respond with the following information:
- flags for basic server characteristics
- server name (7-bit ASCII and UTF8)
- signature: used to uniquely identify the server for other AFP transactions
- server type: typically "Macintosh" or "Netatalk"
- a list of strings describing AFP versions spoken (eg. "AFP3.2")
- UAM list: a list of strings describing User Authentication Methods (eg. "DHX2")
- a 64x64 pixel icon
- directory server list
DSIGetStatus reply format is identical to AFP's FPGetSrvrParms and ASP's[4].
Error codes
The error codes returned are AFP return codes[5].
Further reading
DSI is never documented separately, and is sufficiently simple and static that older references are suitable for modern implementations. The concepts of DSI are identical to AppleTalk Session Protocol (ASP), and the overview in Inside AppleTalk, Second Edition can be helpful.
The most succinct guide is is the "AFP over TCP" chapter of Apple Filing Protocol Version 2.1 and 2.2.
Footnotes
References
- AppleTalk Filing Protocol Version 2.1 and 2.2
http://www.jammed.com/~jwa/hacks/security/asip/ASAppleTalkFiling2.1_2.2.pdf
- Inside AppleTalk
Sidhu, Gurharan S.; Andrews, Richard F.; Oppenheimer, Alan B. (May 1990), Inside AppleTalk, Second Edition, Addison-Wesley Publishing Company, Inc., ISBN 0-201-55021-0{{citation}}: CS1 maint: date and year (link)
- Apple Filing Protocol Programming Guide, April 4, 2006
http://developer.apple.com/DOCUMENTATION/Networking/Conceptual/AFP/AFP3_1.pdf
- Apple Filing Protocol Reference, May 23, 2006
http://developer.apple.com/DOCUMENTATION/Networking/Reference/AFP_Reference/AFP_Reference.pdf