DEFCON 12/DEFCON_12_CD-ROM_2004.iso/Arcieri/draft-arcieri-peer-distributed-transfer-protocol.xml

Text File | 2004-07-08 | 53KB | 1,541 lines

<?rfc toc="yes" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc ipr="full2026" docName="draft-arcieri-peer-distributed-transfer-protocol">
  <front>
    <title abbrev="PDTP Protocol Specification">Peer Distributed Transfer Protocol</title>
    <author initials="A." surname="Arcieri" fullname="Anthony Arcieri" role="editor">
      <organization>PDTP.org</organization>
    </author>
    <date day="6" month="July" year="2004" />
    <area>Internet</area>
    <keyword>I-D</keyword>
    <keyword>Internet-Draft</keyword>
    <keyword>PDTP</keyword>
    <abstract>
        <t>The Peer Distributed Transfer Protocol (PDTP) provides a method of transferring files using peers to aid in distribution of content, similar to <eref target="http://www.bitconjurer.org/BitTorrent/">BitTorrent</eref>. PDTP servers export a dynamically changing directory heirarchy, making it somewhat more like HTTP or FTP, and support a number of other features such as metadata rich directory listings and support for file integrity validation through the use of DSS signatures, and large networks designed to replace FTP mirroring.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <section title="Overview">
    <t>
This document describes version 1 of PDTP.  Version 1 currently only allows
for operation on IPv4 networks.  IPv6 support has been planned from the
start, and may or may not make it into version 1 depending on the
additional design complexity of facilitating transfers between
IPv4 and IPv6 hosts.
</t>
    <t>
PDTP is actually a suite of four different protocol formats used by different components of the system:

    <list style="symbols">
    <t><xref target="client-server-protocol">The client/server protocol</xref>, which is used by clients to query the contents of a file repository and manages the file transfer process.  No file data is transferred using this protocol directly.  The PDTP client/server protocol's standard port number is XXXX (pending IANA assignment).</t>
    <t><xref target="hub-protocol">The hub protocol</xref>, used by PDTP servers to talk to PDTP hubs in order to query file repository contents, network mappings, and various transfer regulation functions.  The PDTP hub protocol's standard port number is XXXX (pending IANA assignment).</t>
    <t><xref target="piece-transfer-protocol">The piece transfer protocol</xref>, or "peer protocol", used by  clients
to transfer pieces to/from each other or from PDTP hubs.  The PDTP piece transfer protocol's standard port number is XXXX (pending IANA assignment).</t>
    <t><xref target="proxy-protocol">The proxy protocol</xref>, used by clients behind firewalls to access PDTP servers.  The PDTP proxy protocol's standard port number is XXXX (pending IANA assignment).</t>
    </list>
</t>
      </section>

      <section title="Integer abbreviations">
    <figure>
      <preamble>The following abbreviations will be used to describe various integers:</preamble>
      <artwork>
uint8    Big-endian 8-bit unsigned integer
uint16    Big-endian 16-bit unsigned integer
uint32    Big-endian 32-bit unsigned integer
uint64    Big-endian 64-bit unsigned integer
      </artwork>
    </figure>
      </section>

      <section title="Handshaking">
    <figure>
      <preamble>Handshaking occurs when a PDTP client connects to a PDTP server:</preamble>
      <artwork>
Client sends:
uint32    Magic number (0x50445450, "PDTP")

Server responds:
uint32    Magic number (0x50445450, "PDTP")
uint16  Number of available protocol versions
uint16    Minimum protocol version
uint16    Next available protocol version [Optional]
...
uint16  Maximum available protocol version [Optional]
</artwork>
    </figure>
    <figure>
      <preamble>- OR -</preamble>
      <artwork>
Server rebonds:
uint16    Magic number (0x5244526E, "REDR");
uint16    String length
string    Name of destination host
uint16    Host port
</artwork>
    </figure>
    <figure>
      <preamble>- OR -</preamble>
      <artwork>
Server responds:
uint16    Magic number (0x41555448, "AUTH")
...    Authorization process (See Appendix C)
uint32  Magic number (0x50445450, "PDTP")
uint16  Minimum protocol version
uint16  Maximum protocol version
</artwork>
    </figure>
    <t>
The 'PDTP' response indicates the server has accepted the connection.  An
'AUTH' response may be issued prior to a 'PDTP' response if the server
requires authorization to login.
</t>
    <t>
If the server wishes to redirect the client to a different named server,
it can send a REDR response, followed by the hostname, IPv4 address in
dotted quad format, or IPv6 address of the remote server, and the port
number to redirect to.
</t>
    <t>
The server and client arbitrate which protocol version to use by having
the client pick a version number from an ordered list.  The list consists
of a 16-bit value indicating how many protocol versions are supported,
and an ordered list of 16-bit integers comprising the specific protocol
revisions supported.
</t>
    <t>
Currently the only available protocol version is 1.  Therefore this list
should consist only of two 16-bit integers, each set to 1, the first
to indicate that only one protocol version is available and the
second to indicate that version 1 is the only supported version.
</t>
    <figure>
      <artwork>
Client responds:
uint16    Protocol version
</artwork>
    </figure>
    <t>
The client then selects which protocol version it would like to use.  If
the client selects a protocol version which wasn't in the list, the
client has violated the protocol and the server should terminate the
connection.
</t>
      </section>

      <section title="Transaction format">
    <t>
All communication following the handshake takes the form of transactions.
Transactions may originate from the server as well, in which case the
serial number of the response should be set to zero.  All outstanding
transactions from a client should have a unique serial number so the
client can determine which transaction a particular response is
associated with.
</t>
    <figure>
      <artwork>
Client or server sends: [Required]
uint32  Transaction length
uint32  Transaction serial number
uint16    Transaction ID
uint16  Object count
</artwork>
    </figure>
    <t>
Each transaction begins with a length field, which is the length of the entire
remainder of the transaction in bytes (i.e. the 4 bytes for the transaction
length value itself are not included)  Thus the smallest possible value for
the transaction length is 8 bytes: 4 bytes for the serial number, 2 for the
transaction ID, and two for the object count.  The entire transaction would
be 12 bytes, counting 4 extra bytes for the transaction length value.
</t>
    <t>
Every transaction has a type, which is specified in the "Transaction ID" field.
This transaction ID actually consists of a 1-bit boolean value which indicates
whether the transaction is 0: a command or 1: a reply.  The remaining 15 bits
in the field comprise a big endian integer identifier for the transaction.
Specific types of transactions will be enumerated below.  This value is set to
zero to indicate an error when responding to a client's transaction.  Otherwise,
all server responses will have the same ID and serial number as the original
client's transaction.
</t>
    <figure>
      <preamble>
Transactions may or may not have a number of parameters known as "objects".
The number of objects contained within a transaction are stored in the
"Object count" field of the transaction header.  The length of all the objects
and the object headers is counted in the "Transaction length" value.
Objects take the following format:
</preamble>
      <artwork>
uint32  Object length
uint16    Object ID
string    Object payload of specified length
</artwork>
    </figure>
    <t>
What follows is a description of all transactions and associated objects used
by the various protocols in the PDTP suite.  All objects are mandatory unless
stated otherwise.  Objects should be arranged in order of their respective
numerical object identifiers from least to greatest.  This document arranges
its object lists in such a manner; transactions should be constructed in the
same order presented in this document in order to be valid.
    </t>
      </section>
    </section>
    <section anchor="client-server-protocol" title="Client/Server Protocol">
      <section title="Control transactions">

    <section title="Command 0x1: Download File">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to file

Object ID:    0x6 (Piece List) [Optional]
Payload:    string    Piece list
</artwork>
      </figure>
      <t>
This transaction requests a download from the server.  The piece list consists
of a list of uint32 pairs, which are the start and end of ranges of piece
indices we still need.  So, for example, if we are beginning a new download
of a file with 2000 pieces, piece list would be 8 bytes long and contain two
uint32 values, 0 and 1999.  If we are getting the same file but have pieces
1000-1500, we would send 16 bytes which contain 4 uint32 values, 0, 999,
1501, and 1999.  If we have everything but the first piece, we would send
8 bytes which contain two uint32 values, 0 and 0.
</t>
      <t>
The piece list object may be optionally omitted, which indicates that
the client does not possess any pieces of the given file.
</t>
      <figure>
        <preamble>
If the file handle and piece list are valid, the server will respond with:
</preamble>
        <artwork>
Object ID:      0x1 (File Handle)
Payload:        uint32  File handle ID
</artwork>
      </figure>
      <t>
File transfers are stateful and server regulated.  The server will
asynchronously send transfer management transactions for the given
file handle until the client sends the 0x2: End Download transaction
or the server sends the 0x17: End Transfer transaction.
</t>
      <figure>
        <preamble>
In the event of an error, the server will respond with the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x2: End Download">
      <figure>
        <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID
</artwork>
      </figure>
      <t>
This transaction is sent by clients to terminate a transfer.  It should not
be confused with transaction 0x16 (Terminate Transfer) which is used by
the server to inform clients that a download has been terminated.  This
transaction should be sent by clients when they are satisfied with the
set of pieces they have received.  Otherwise, even after a client has
successfully transferred all the pieces of a file, the server will
continue to include this file in the piece selection process for uploaders,
and if the client attempts to download another file they can upload
pieces from a file they've already received successfully in order to
earn the right to transfer more pieces from a different file.
</t>
      <figure>
        <preamble>
On success the server will respond with a transaction with no objects, or on
error it should respond with the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x3: Retrieve Server Certificate">
      <figure>
        <preamble>
This transaction takes no objects from the client.  The server responds with:
</preamble>
        <artwork>
Object ID:    0x40 (X.509 Certificate)
Payload:    uint32    Server certificate containing DSA key
</artwork>
      </figure>
      <t>
Administrators of PDTP servers may elect to allow the authenticity of certain
files to be verified using a DSS cryptographic signature.  This transaction
allows retrieval of an X.509 certificate containing the DSA key used to
sign files on the server.
</t>
      <t>
More information on X.509 can be found in <xref target="RFC2459">RFC2459</xref>.
</t>
    </section>

    <section title="Command 0x4: Change Listener Port">
      <figure>
        <artwork>
[Objects:]

Object ID:    0x12 (Port Number) [Optional]
Payload:    uint16    New listener port number
</artwork>
      </figure>
      <t>
This transaction allows a client to dynamically reassign their listener
port.  By default, the PDTP server will assume the client is capable of
receiving connections on port 4045 unless specified otherwise by this
transaction.  If a 0x12 (Port Number) object is not passed in this
transaction, then the client is set to passive mode.
</t>
      <figure>
        <preamble>
If the port number is valid, the server will respond with a transaction without
any objects.  In the event of an error, the server will respond with the
following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x5: Set Maximum Download Concurrency">
      <figure>
        <artwork>
[Objects:]

Object ID:    0x7 (Concurrency Value)
Payload:    uint16    New maximum concurrent connections
</artwork>
      </figure>
      <t>
By default clients will be assigned a server side default for the maximum
number of concurrent piece downloads they wish to perform.  Clients may
specify this value explicitly using this transaction.  A value of zero
is not allowed, and servers may elect to set a ceiling for this value.
</t>
      <figure>
        <preamble>
If the concurrency value is valid, the server will respond with a transaction
without any objects.  In the event of an error, the server will respond with
the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x6: Set Maximum Upload Concurrency">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x7 (Concurrency Value)
Payload:        uint16  New maximum concurrent connections
</artwork>
      </figure>
      <t>
By default clients will be assigned a server side default for the maximum
number of concurrent piece uploads they wish to perform.  Clients may
specify this value explicity using this transaction.  A value of zero
is not allowed, and servers may elect to set a ceiling for this value.
</t>
      <figure>
        <preamble>
If the concurrency value is valid, the server will respond with a transaction
without any objects.  In the event of an error, the server will respond with
the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x100: Directory Status">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to directory
</artwork>
      </figure>
      <figure>
        <preamble>
This transaction requests the status of the specified directory.  The server
returns a transaction with the following object:
</preamble>
        <artwork>
Object ID:      0x102 (Entry Timestamp)
Payload:        string  48-bit timestamp value
</artwork>
      </figure>
      <figure>
        <preamble>
The timestamp is a 48-bit string which can be broken down as follows:
</preamble>
        <artwork>
uint16          Year
uint32          Year seconds
</artwork>
      </figure>
      <t>
The timestamp format consists of an 16-bit integer year and a 32-bit value
representing the number of seconds since the beginning of that year.
</t>
      <figure>
        <preamble>
In the event of an error, the server will return the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x101: File Status">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to file
</artwork>
      </figure>
      <figure>
        <preamble>
This transaction requests the status of the specified file.  The server
returns a transaction with the following object:
</preamble>
        <artwork>
Object ID:      0x102 (Entry Timestamp)
Payload:        string  48-bit timestamp value
</artwork>
      </figure>
      <figure>
        <preamble>
The timestamp is a 48-bit string which can be broken down as follows:
</preamble>
        <artwork>
uint16          Year
uint32          Year seconds
</artwork>
      </figure>
      <t>
The timestamp format consists of an 16-bit integer year and a 32-bit value
representing the number of seconds since the beginning of that year.
</t>
      <figure>
        <preamble>
In the event of an error, the server will return the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
    </section>

    <section title="Command 0x102: Directory Listing">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to directory
</artwork>
      </figure>
      <figure>
        <preamble>
The transaction requests a listing of the specified directory.  The server
returns an arbitrary number of the following objects:
</preamble>
        <artwork>
Object ID:      0x100 (Subdirectory Entry)
Payload:        string  Subdirectory information

Object ID:    0x101 (File Entry)
Payload:    string    File information
</artwork>
      </figure>
      <figure>
        <preamble>
The subdirectory information string (0x100) should consist of the following:
</preamble>
        <artwork>
uint16          Modification timestamp: year
uint32          Modification timestamp: year seconds
uint16          Length of directory name
string          Directory name
</artwork>
      </figure>
      <figure>
        <preamble>
The file information string (0x101) should consist of the following:
</preamble>
        <artwork>
uint16        Modification timestamp: year
uint32        Modification timestamp: year seconds
uint64        File length in bytes
uint16        Length of filename
string        Filename
</artwork>
      </figure>
      <t>
The timestamp format consists of an 16-bit integer year and a 32-bit value
representing the number of seconds since the beginning of that year.
</t>
      <t>
In the event of an error, the server will return the following:
</t>
      <t>
        <list style="hanging" hangIndent="16">
          <t hangText="Object ID:">0x500 (Error Message)</t>
          <t hangText="Payload:">string  Error message</t>
        </list>
      </t>
    </section>

    <section title="Command 0x103: File Information">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to file
</artwork>
      </figure>
      <figure>
        <preamble>
This transaction requests the information required to complete the download
process.  The server responds with the following objects:
</preamble>
        <artwork>
Object ID:      0x3 (File Length)
Payload:        uint64  File length

Object ID:      0x4 (Piece Length)
Payload:        uint32  Piece length
</artwork>
      </figure>
      <figure>
        <preamble>
And either of the following objects:
</preamble>
        <artwork>
Object ID:      0x20 (MD5 Hashes)
Payload:        string  Buffer of MD5 hashes for all pieces in file
</artwork>
      </figure>
      <t>- OR - </t>
      <figure>
        <artwork>
Object ID:      0x21 (SHA1 Hashes)
Payload:        string  Buffer of SHA1 hashes for all pieces in file
</artwork>
      </figure>
      <figure>
        <preamble>
If a cryptographic signature is available for a given file it should
be included in the transaction as well:
</preamble>
        <artwork>
Object ID:    0x41 (DSS Signature) [Optional]
Payload:    string  DSS signature of file
</artwork>
      </figure>
      <figure>
        <preamble>
Or in the event of an error, the server responds with an error transaction
containing only the following object:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
      <t>
The 0x20 or 0x21 object is a list of hashes for each piece in the file.
The number of bytes in the 0x20 or 0x21 object will be the number of
bytes in a single hash digest * ceiling(file length / piece length).
So, for 0x20 (MD5) with a piece length of 8 and a file length of 17
the length of the 0x20 object will be 48 bytes, which is the length
of a single MD5 hash (16 bytes) * 3.
</t>
      <t>
Currently MD5 and SHA1 are the only supported hash ciphers, but the protocol
is designed so objects 0x22, 0x23, etc. are reserved for future hash ciphers.
</t>
      <t>
After receiving a list of hashes, the client should then compute hashes
for each piece in any pre-existing copy of the file and compare them
to the server-provided list to determine what pieces of the file remain
to be transferred.  This list should be passed as the 0x6 (Piece List) object
of the 0x1 (Download File) transaction.
</t>
      <t>
The optional 0x41 (DSS Signature) object is the SHA1 hash of the file encrypted
with the DSA key contained within the server's certificate, which may be
retrieved with the 0x3 (Retrieve Server Certificate) transaction.  This
is used to ensure that files on the server have not been tampered with
prior to downloading.
</t>
      <t>
For detailed information about the MD5 cipher, please see <xref target="RFC1321">RFC1321</xref>.
For detailed information about the SHA1 cipher, please see <xref target="RFC3174">RFC3174</xref>.
For more information on the DSS, please see <xref target="FIPS.186-1.1998">FIPS186</xref> and <xref target="RFC2802">RFC2802</xref>.
</t>
    </section>

    <section title="Command 0x104: RDL Directory Listing">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to directory
</artwork>
      </figure>
      <figure>
        <preamble>
This transaction requests a Rich Directory Listing.  The server responds:
</preamble>
        <artwork>
Object ID:    0x104 (RDL response)
Payload:    string    XML document containing RDL response
</artwork>
      </figure>
      <figure>
        <preamble>
Or in the event of an error, the server responds with the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
      <t>
RDL is an XML directory listing format which may be used secondarily to the
0x102 (Directory Listing) transaction in order to obtain a metadata rich
directory listing with extended file attributes.  The format of these
results is not specified in this document, but may be found at:
</t>
      <t>
<eref target="http://pdtp.org/rdl.php">http://pdtp.org/rdl.php</eref>
</t>
    </section>

    <section title="Command 0x105: RDL File Information">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to file
</artwork>
      </figure>
      <figure>
        <preamble>
This transaction requests RDL attributes for a file.  The server responds:
</preamble>
        <artwork>
Object ID:      0x104 (RDL response)
Payload:        string  XML document containing RDL response
</artwork>
      </figure>
      <figure>
        <preamble>
Or in the event of an error, the server responds with the following:
</preamble>
        <artwork>
Object ID:      0x500 (Error Message)
Payload:        string  Error message
</artwork>
      </figure>
      <t>
This is a counterpart to transaction 0x103 (File Information) only also
returning extended file attributes from the 0x104 (RDL Directory Listing)
transaction.
</t>
    </section>
      </section>

      <section title="Transfer management">
    <section title="Transfer management transactions (originating from server)">
      <section title="Command 0x10: Send Piece to Peer">
        <figure>
          <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID

Object ID:    0x6 (Piece ID)
Payload:    uint32    Piece number

Object ID:    0x10 (IPv4 Address)
Payload:    uint32    Address of remote peer

Object ID:    0x12 (Port Number)
Payload:    uint16    Port number of remote peer
</artwork>
        </figure>
        <t>
This transaction instructs one peer to connect to another and send the
specified piece from the specified file.
</t>
      </section>

      <section title="Command 0x11: Receive Piece from Peer">
        <figure>
          <artwork>
[Objects:]

Object ID:      0x1 (File Handle)
Payload:        uint32  File handle ID

Object ID:      0x6 (Piece ID)
Payload:        uint32  Piece number

Object ID:      0x10 (IPv4 Address)
Payload:        uint32  Address of remote peer

Object ID:      0x12 (Port Number)
Payload:        uint16  Port number of remote peer
</artwork>
        </figure>
        <t>
This transaction instructs one peer to connect to another and
receive the specified piece from the specified file.
</t>
      </section>

      <section title="Command 0x16: Terminate Piece Transfer">
        <figure>
          <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID

Object ID:    0x6 (Piece ID)
Payload:    uint32    Piece number

Object ID:    0x10 (IPv4 Address)
Payload:    uint32    Address of remote peer
</artwork>
        </figure>
        <t>
This transaction instructs a client which is uploading a piece to one of its
peers to terminate its upload.  No response from the client doing the uploading
is expected.  Instead, the server should wait for a 0x15 (Report failed piece
transfer) transaction originating from the client which is downloading the
piece.  This command should not be sent to the client which is downloading
a piece; this is a protocol violation and should be ignored (or noted in
a log as a protocol violation)
</t>
      </section>

      <section title="Command 0x17: Terminate File Transfer">
        <figure>
          <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID
</artwork>
        </figure>
        <t>
This transaction informs a client that the file associated with the given
handle is no longer being offered by the server, and that the client should
terminate all attempts to receive that particular file.
</t>
      </section>
    </section>

    <section title="Transfer management transactions (originating from client)">
      <section title="Command 0x12: Authorize Piece Upload Attempt">
        <figure>
          <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID

Object ID:    0x6 (Piece ID)
Payload:    uint32    Piece number

Object ID:    0x10 (IPv4 Address)
Payload:    uint32    Address of remote peer
</artwork>
        </figure>
        <t>
This transaction informs the server that a peer has connected and is requesting
to upload the specified piece (using an opcode of 0x10).  The listening peer
then and asks for server authorization for the transfer to continue.  The
server will always respond with a transaction without any objects.  If the
connection attempt is authorized the response transaction will have its
transaction ID set to 0x12, or if the connection is unauthorized the server
will send an error response, that is that the transaction ID will be set to 0.
</t>
      </section>

      <section title="Command 0x13: Authorize Piece Download Attempt">
        <figure>
          <artwork>
[Objects:]

Object ID:      0x1 (File Handle)
Payload:        uint32  File handle ID

Object ID:      0x6 (Piece ID)
Payload:        uint32  Piece number

Object ID:      0x10 (IPv4 Address)
Payload:        uint32  Address of remote peer
</artwork>
        </figure>
        <t>
This transaction is identical to the one above (0x12) except it is used
when the remote peer requests a piece download (using opcode 0x11)
</t>
      </section>

      <section title="Command 0x14: Report Successful Piece Transfer">
        <figure>
          <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID

Object ID:    0x6 (Piece ID)
Payload:    uint32    Piece number

Object ID:    0x10 (IPv4 Address)
Payload:    uint32    Address of remote peer
</artwork>
        </figure>
        <t>
This transaction informs the server that a piece transfer has completed
successfully.  It should be sent by both peers involved in a transfer
every time a piece transfer completes successfully.  The server does
not send a response to this transaction; it is used only for the
server's internal bookkeeping.
</t>
      </section>

      <section title="Command 0x15: Report Failed Piece Transfer">
        <figure>
          <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID

Object ID:    0x6 (Piece ID)
Payload:    uint32    Piece number

Object ID:    0x10 (IPv4 Address)
Payload:    uint32    Address of remote peer
</artwork>
        </figure>
        <t>
This transaction is functionally equivalent to the one above (0x14) except
it is used to report a failed piece transfer.  The server sends no response.
</t>
      </section>
    </section>
      </section>
    </section>

    <section anchor="piece-transfer-protocol" title="Piece Transfer Protocol">
      <t>
In PDTP, pieces are transferred between a peer listening on a TCP
port, which we will hereafter refer to as the 'listener', and a peer
connecting to this TCP port, which we will hereafter refer to as the
'connecting peer'.
</t>
      <figure>
    <preamble>
The piece transfer protocol is very simple by design.  The connecting peer
begins the exchange by sending the following:
</preamble>
    <artwork>
Connecting peer sends:
uint32    Magic number    (0x50545050, "PTPP")

Listener responds:
uint32    Magic number    (0x50545050, "PTPP")
uint16    Minimum protocol version
uint16    Maximum protocol version
</artwork>
      </figure>
      <t>
Both the minimum and maximum protocol version should currently be 1.  In the
future these values will be the lowest and highest protocol versions supported
by the server.
</t>
      <figure>
    <preamble>
In the future, the response from the connecting peer will vary depending
on the protocol versions supported by the listener and the underlying
transport protocol.  However, at the current time the connecting
peer will always respond with the following:
</preamble>
    <artwork>
uint16  Protocol version
uint16    Operation code
</artwork>
      </figure>
      <t>
The connecting peer selects which protocol version it would like to use.  This
value must be greater than or equal to the lowest version supported and less
than or equal to the highest protocol version supported by the server.  Any
values which don't meet this criteria are a protocol violation, and the
connection should be terminated by the server.  At this point in time, this
value should always be 1.
</t>
      <figure>
    <preamble>
The operation code will be one of the following values (note that these
correspond directly to the transaction IDs from the server originated
transactions to begin a piece transfer):
</preamble>
    <artwork>
0x10:    Piece upload request (connecting peer => listener)
0x11:    Piece download request (listener => connecting peer)
</artwork>
      </figure>
      <figure>
    <preamble>
After the protocol version and operation code, the connecting peer will send
the following values which describe exactly what piece from what server is
to be transferred:
</preamble>
    <artwork>
uint32  IPv4 address of coordinating server in network byte order
uint16    Port of coordinating server
uint32  File handle ID
uint32  Piece ID
</artwork>
      </figure>
      <t>
The listener should then report the connecting peer's request to the
coordinating server using the proper transaction from the
"Transfer Management Transactions" section above: either 0x12 for a
piece upload request or 0x13 for a piece download request.
</t>
      <figure>
    <preamble>
If the connecting peer requests a piece upload, then then listener should
first authorize the connection with the server.  If the server does not
give authorization for this transfer the listener should close the connection.
Otherwise if authorization is received it should send the following:
</preamble>
    <artwork>
uint32    Piece offset
uint32  Bytes to transfer
</artwork>
      </figure>
      <t>
This allows the listener, which is downloading the piece, to resume the
transfer of a piece which has already been partially received by specifying
an offset (in bytes) from the beginning of the piece from which to begin
the transfer.  If this value is equal to or greater than the piece size,
or if the offset plus the bytes to transfer exceeds the piece size,
then the connecting peer should disconnect and report a failed transfer
due to a protocol violation.  Otherwise it should begin sending the piece
from the specified offset.  The bytes to transfer field allows clients
to grab the beginning portion of a piece if they believe that portion
to have been "tainted" by a malicious client.
</t>
      <figure>
    <preamble>
If the connecting peer is requesting a piece download, then in addition
to the header already enumerated above it should send:
</preamble>
    <artwork>
uint32    Piece offset
uint32    Bytes to transfer
</artwork>
      </figure>
      <t>
The listener should then request authorization from the server, and if the
server does not authorize the transfer the listener should close the connection.
Otherwise the listener should begin sending the piece from the specified offset.
</t>
      <t>
If the connection is lost before the piece transfer completes, this
should be reported to the server using the appropriate transaction from the
"Transfer Management Transactions" section, 0x15 (Report failed transfer).
</t>
      <t>
If the piece transfer succeeds, both the connecting peer and listener
should report so to the server using the appropriate transaction from the
"Transfer Management Transactions" section, 0x14 (Report successful transfer).
</t>
      <figure>
    <preamble>
After a successful piece transfer, both the connecting peer and listener
have the option of closing the connection.  Otherwise, the listener can
wait for the following:
</preamble>
    <artwork>
uint16    Operation code
</artwork>
    <postamble>
and the two peers can then begin another piece transfer if so desired.
</postamble>
      </figure>
    </section>

    <section anchor="hub-protocol" title="Hub Protocol">
      <t>
Unlike the client/server protocol, communication between servers and
hubs allows fully synchronous, bidirectional communication.  Consequently,
both the server and hub will use serial numbers to keep track of
outstanding transactions.  Serial numbers used by the server and hub
are distinct, and the server and hub distinguish requests from replies
by transaction types alone.
</t>

      <section title="Handshaking">
    <t>
PDTP hubs provide directory structure information to a PDTP server
or cluster of PDTP servers.  In order to function, a PDTP server must be
connected to a hub.  A PDTP server should connect to one and only one
PDTP hub at a single time.  The connection is made via TCP.
</t>
    <t>
After connecting the server initiates the handshaking process.
</t>
    <figure>
      <artwork>
Server sends:
uint32  Magic number    (0x50445350, "PDSP")

Hub responds:
uint32  Magic number (0x50445450, "PDSP")
uint16  Minimum protocol version
uint16  Maximum protocol version
</artwork>
    </figure>
    <t>- OR -</t>
    <figure>
      <artwork>
Hub responds:
uint16  Magic number (0x41555448, "AUTH")
...     Authorization process (See Appendix C)
uint32  Magic number (0x50445450, "PDSP")
uint16  Minimum protocol version
uint16  Maximum protocol version
</artwork>
    </figure>
    <t>
The 'PDSP' response indicates the hub has accepted the connection.  An
'AUTH' response may be issued prior to a 'PDSP' response if the hub
requires authorization to allow a server to connect.
</t>
    <t>
Both the minimum and maximum protocol version should currently be 1.  In the
future these values will be the lowest and highest protocol versions supported
by the hub.
</t>
    <figure>
      <preamble>
The server should respond with the following:
</preamble>
      <artwork>
uint16  Protocol version
</artwork>
    </figure>
    <t>
The server selects which protocol version it would like to use.  This value
must be greater than or equal to the lowest version supported and less than or
equal to the highest protocol version supported by the server.  Any values
which don't meet this criteria are a protocol violation, and the connection
should be terminated by the hub.  At this point in time, this value should
always be 1.
</t>
    <t>
After handshaking, the hub and server communicate using the standard
transaction format.  The following transactions are supported:
</t>
      </section>

      <section title="Transactions originating from hub">
    <section title="Command 0x4: Change Listener Port">
      <t>
This transaction is documented in section 2.1.  It is used to inform the server
that the hub's piece server is listening on a port other than the one
to which the server connected.
</t>
    </section>

    <section title="Command 0x13: Authorize Piece Download Attempt">
      <t>
This transaction is documented in section 2.2.2.  It is used when a client
connects to the hub's piece server and is requesting a particular piece.
The hub requests authorization from the server, and the server can either
grant or deny the connecting client's request for a particular piece.
</t>
    </section>

    <section title="Command 0x200: Add Handle">
      <figure>
        <artwork>
[Objects:]

Object ID:    0x1 (File Handle)
Payload:    uint32    File handle ID

Object ID:      0x2 (Path) [See Appendix A for format]
Payload:        string  Path to file

Object ID:    0x6 (Piece ID)
Payload:    uint16    Number of pieces in file
</artwork>
      </figure>
      <t>
This transaction informs the server that the given handle is now valid
and consists of the given number of pieces.  This transaction should
be sent with a serial number of zero, and no response is returned.
</t>
    </section>

    <section title="Command 0x201: Remove Handle">
      <figure>
        <artwork>
[Objects:]

Object ID:      0x1 (File Handle)
Payload:        uint32  File handle ID
</artwork>
      </figure>
      <t>
This transaction informs the server that the given handle is no longer valid.
The server should terminate all transfers associated with the given handle.
This transaction should be sent with a serial number of zero, and no response
is returned.
</t>
    </section>
      </section>

      <section title="Transactions originating from server">
    <t>
PDTP hubs also implement all directory listing transactions implemented
by servers and used by clients for querying directories.  The expected behavior
of a PDTP server is that requests for directory or file information sent
to the server are redirected to the hub, but that the 0x100 and 0x101 status
queries can be used to implement a caching behavior within the server, to
mitigate the amount of bandwidth used by the hub for handling these
queries.  Hubs should therefore be able to answer the following queries
authoritatively for the files and directory maps they are serving:
</t>
    <figure>
      <artwork>
Command 0x100:  Directory Status
Command 0x101:  File Status
Command 0x102:  Directory Listing
Command 0x103:  File Information
Command 0x104:  RDL Directory Listing
Command 0x105:    RDL File Information
</artwork>
    </figure>
     </section>
    </section>

    <section anchor="proxy-protocol" title="Proxy Protocol">
      <t>
PDTP supports making outgoing server and peer connections as well as redirection
of incoming peer connections through a proxy server.  This is accomplished
partially through dynamic protocol translation within the proxy server
and partially through special protocol constructions for making outgoing
connections.  The PDTP proxy server also listens on port 4045.
</t>
      <figure>
    <preamble>
Requesting a connection through a proxy server is accomplished as follows:</preamble>
    <artwork>
Client sends:
uint32  Magic number    (0x50786350, "PXCP")

Proxy server responds:
uint32  Magic number    (0x50786350, "PXCP")
uint16  Minimum protocol version
uint16  Maximum protocol version
</artwork>
      </figure>
      <t>
Both the minimum and maximum protocol version should currently be 1.  In the
future these values will be the lowest and highest protocol versions supported
by the server.
</t>
      <figure>
    <artwork>
Client responds:
uint16  Protocol version
</artwork>
      </figure>
      <t>
The client then selects which protocol version it would like to use.  This
value must be greater than or equal to the lowest version supported and less
than or equal to the highest protocol version supported by the server.  Any
values which don't meet this criteria are a protocol violation, and the
connection should be terminated by the server.
</t>
      <figure>
    <preamble>
After selecting the protocol version it would like to use, the client sends
the address and port of the remote system to connect to:
</preamble>
    <artwork>
uint32  Host IP address in network byte order
uint16  Host port
</artwork>
      </figure>
      <t>
The client may then issue a PDTP or PTPP connection request.  If the connection
to the remote system fails the proxy should simply terminate the connection.
Otherwise it should connect to the requested system and repeat the PDTP or
PTPP connection requests made by the client.
</t>
    </section>

    <section title="Acknowledgments">
      <t>Thanks to Marshall Rose for his conversion tools from the
      <xref target="RFC2629">RFC-2629</xref> XML format to HTML and RFC.</t>
    </section>
  </middle>

  <back>
    <references title="References">
      <reference anchor='RFC1321'>
      <front>
      <title abbrev='MD5 Message-Digest Algorithm'>The MD5 Message-Digest Algorithm</title>
      <author initials='R.' surname='Rivest' fullname='Ronald L. Rivest'>
      <organization>Massachusetts Institute of Technology, (MIT) Laboratory for Computer Science</organization>
      <address>
      <postal>
      <street>545 Technology Square</street>
      <street>NE43-324</street>
      <city>Cambridge</city>
      <region>MA</region>
      <code>02139-1986</code>
      <country>US</country></postal>
      <phone>[phone]</phone>
      <email>[e-mail]</email></address></author>
      <date year='1992' month='April' /></front>
      <seriesInfo name='RFC' value='1321' />
      <format type='TXT' octets='35222' target='ftp://ftp.isi.edu/in-notes/rfc1321.txt' />
      </reference>

<reference anchor='RFC2104'>
<front>
<title abbrev='HMAC'>HMAC: Keyed-Hashing for Message Authentication</title>
<author initials='H.' surname='Krawczyk' fullname='Hugo Krawczyk'>
<organization>IBM, T.J. Watson Research Center</organization>
<address>
<postal>
<street>P.O.Box 704</street>
<city>Yorktown Heights</city>
<region>NY</region>
<code>10598</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<author initials='M.' surname='Bellare' fullname='Mihir Bellare'>
<organization>University of California at San Diego, Dept of Computer Science and Engineering</organization>
<address>
<postal>
<street>9500 Gilman Drive</street>
<street>Mail Code 0114</street>
<city>La Jolla</city>
<region>CA</region>
<code>92093</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<author initials='R.' surname='Canetti' fullname='Ran Canetti'>
<organization>IBM T.J. Watson Research Center</organization>
<address>
<postal>
<street>P.O.Box 704</street>
<city>Yorktown Heights</city>
<region>NY</region>
<code>10598</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<date year='1997' month='February' />
<abstract>
<t>This document describes HMAC, a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative cryptographic hash function, e.g., MD5, SHA-1, in combination with a secret shared key.  The cryptographic strength of HMAC depends on the properties of the underlying hash function.</t></abstract></front>
<seriesInfo name='RFC' value='2104' />
<format type='TXT' octets='22297' target='ftp://ftp.isi.edu/in-notes/rfc2104.txt' />
</reference>

<reference anchor='RFC2279'>
<front>
<title abbrev='UTF-8'>UTF-8, a transformation format of ISO 10646</title>
<author initials='F.' surname='Yergeau' fullname='Francois Yergeau'>
<organization>Alis Technologies</organization>
<address>
<postal>
<street>100, boul. Alexis-Nihon</street>
<street>Suite 600</street>
<city>Montreal</city>
<region>Quebec</region>
<code>H4M 2P2</code>
<country>CA</country></postal>
<phone>[phone]</phone>
<facsimile>[phone]</facsimile>
<email>[e-mail]</email></address></author>
<date year='1998' month='January' />
<abstract>
<t>ISO/IEC 10646-1 defines a multi-octet character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. Multi-octet characters, however, are not compatible with many current applications and protocols, and this has led to the development of a few so-called UCS transformation formats (UTF), each with different characteristics.  UTF-8, the object of this memo, has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo updates and replaces RFC 2044, in particular addressing the question of versions of the relevant standards.</t></abstract></front>
<seriesInfo name='RFC' value='2279' />
<format type='TXT' octets='21634' target='ftp://ftp.isi.edu/in-notes/rfc2279.txt' />
</reference>

<reference anchor='RFC2459'>

<front>
<title abbrev='Internet X.509 Public Key Infrastructure'>Internet X.509 Public Key Infrastructure Certificate and CRL Profile</title>
<author initials='R.' surname='Housley' fullname='Russell Housley'>
<organization>SPYRUS</organization>
<address>
<postal>
<street>381 Elden Street</street>
<street>Suite 1120</street>
<city>Herndon</city>
<region>VA</region>
<code>20170</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<author initials='W.' surname='Ford' fullname='Warwick Ford'>
<organization>VeriSign, Inc.</organization>
<address>
<postal>
<street>One Alewife Center</street>
<city>Cambridge</city>
<region>MA</region>
<code>02140</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<author initials='T.' surname='Polk' fullname='Tim Polk'>
<organization>NIST</organization>
<address>
<postal>
<street />
<city>Gaithersburg</city>
<region>MD</region>
<code>20899</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<author initials='D.' surname='Solo' fullname='David Solo'>
<organization>Citicorp</organization>
<address>
<postal>
<street>666 Fifth Ave</street>
<street>3rd Floor</street>
<city>New York</city>
<region>NY</region>
<code>10103</code>
<country>US</country></postal>
<email>[e-mail]</email></address></author>
<date year='1999' month='January' />
<abstract>
<t>This memo profiles the X.509 v3 certificate and  X.509 v2 CRL for use in the Internet.  An overview of the approach and model are provided  as an introduction.  The .509 v3 certificate format is described in detail, with additional information regarding the format and semantics of Internet name forms (e.g., IP addresses).  Standard certificate extensions are described and one new Internet-specific extension is defined.  A required set of certificate extensions is specified.  The X.509 v2 CRL format is described and a required extension set is defined as well.  An algorithm for X.509 certificate path validation is described. Supplemental information is provided describing the format of public keys and digital signatures in X.509 certificates for common Internet public key encryption algorithms (i.e., RSA, DSA, and Diffie-Hellman).  ASN.1 modules and examples are provided in the appendices.</t>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",  "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.</t>
<t>Please send comments on this document to the [e-mail] mail list.</t></abstract></front>

<seriesInfo name='RFC' value='2459' />
<format type='TXT' octets='278438' target='ftp://ftp.isi.edu/in-notes/rfc2459.txt' />
</reference>

      <reference anchor="RFC2629">
        <front>
          <title>Writing I-Ds and RFCs using XML</title>
          <author initials="M.T." surname="Rose" fullname="Marshall T. Rose">
            <organization>Invisible Worlds, Inc.</organization>
            <address>
              <postal>
                <street>660 York Street</street>
                <city>San Francisco</city>
                <region>CA</region>
                <code>94110</code>
                <country>US</country>
              </postal>
              <phone>[phone]</phone>
              <email>[e-mail]</email>
              <uri>http://invisible.net/</uri>
            </address>
          </author>
        <date month="June" year="1999"/>
        </front>
        <seriesInfo name="RFC" value="2629"/>
      </reference>

<reference anchor='RFC2802'>

<front>
<title>Digital Signatures for the v1.0 Internet Open Trading Protocol (IOTP)</title>
<author initials='K.' surname='Davidson' fullname='K. Davidson'>
<organization /></author>
<author initials='Y.' surname='Kawatsura' fullname='Y. Kawatsura'>
<organization /></author>
<date year='2000' month='April' /></front>

<seriesInfo name='RFC' value='2802' />
<format type='TXT' octets='52756' target='ftp://ftp.isi.edu/in-notes/rfc2802.txt' />
</reference>

<reference anchor='RFC3174'>
<front>
<title>US Secure Hash Algorithm 1 (SHA1)</title>
<author initials='D.' surname='Eastlake' fullname='D. Eastlake'>
<organization /></author>
<author initials='P.' surname='Jones' fullname='P. Jones'>
<organization /></author>
<date year='2001' month='September' /></front>
<seriesInfo name='RFC' value='3174' />
<format type='TXT' octets='35525' target='ftp://ftp.isi.edu/in-notes/rfc3174.txt' />
</reference>

      <reference anchor="FIPS.186-1.1998" target="http://csrc.nist.gov/fips/fips1861.pdf">
        <front>
          <title>Digital Signature Standard</title>
          <author>
            <organization>National Institute of Standards and Technology</organization>
          </author>
          <date month="December" year="1998" />
        </front>
        <seriesInfo name="FIPS" value="PUB 186-1" />
      </reference>

    </references>

    <section title="Path format">
      <t>
All paths used by PDTP are canonical Unix format absolute paths, given in the
UTF-8 character set (see <xref target="RFC2279">RFC2279</xref>).
</t>
      <t>
Entities in a path are either directories are files.  Every directory name
should be postfixed with a '/' character, with a degenerate form of "/" for the
root directory.  Therefore, all paths should begin with a '/' character, and
when the last entity in a path is a directory, the entire path should also end
with a '/' character.
</t>
      <t>
(Note: The traditional symbolic directory names '.' for the current directory
 and '..' for the current directory's parent are not allowed)
</t>
      <t>
Files always come at the end of a list of directories.  This directory list
must contain at least one element, the root directory '/'.  So, in order
to reference a file named 'foo' in the root directory, a client would
pass a path of '/foo'.
</t>
      <t>
The maximum length of a path is 1024 bytes.  Paths longer than this limit
are a protocol violation and an appropriate error should be returned.
</t>
    </section>

    <section title="Authorization mechanisms">
      <figure>
    <preamble>
The authorization process by the server sending the authorization magic number:
</preamble>
    <artwork>
uint32    Magic number    (0x41555448, "AUTH")
</artwork>
      </figure>
      <t>
The client then sends a 16-bit integer indicating the authorization mechanism
index to utilize.
</t>
      <figure>
    <artwork>
uint16    Authorization mechanism

The server responds:

uint8    ACK (0x1) or NACK (0x0)
</artwork>
      </figure>
      <t>
A response of ACK indicates the use of this mechanism is allowed, and NACK
rejects it.  If the server responds NACK, the client may either issue another
authorization mechanism to try, or disconnect.
</t>
      <t>
If the server responds ACK, the specified authorization process is performed.
At the end of the process, the server responds ACK (0x1) if the authorization
succeeded or NACK (0x0) if it failed.  If an authorization attempt fails,
the client may send another authorization mechanism index to attempt, or
disconnect if it has exhausted the mechanisms it wishes to use.
</t>
      <t>
* Authorization mechanism 0x0: HMAC-SHA1
</t>
      <figure>
    <preamble>
This mechanism utilizes <xref target="RFC2104">RFC2104</xref> HMAC hashing,
using SHA1 (<xref target="RFC3174">RFC3174</xref>) as the underlying hash
cipher.  The authentication proceeds as follows:
</preamble>
    <artwork>
Server sends:
string    160-bits (20 bytes) of random challenge data
</artwork>
      </figure>
      <figure>
    <preamble>
The message to be encrypted is 20 bytes of random challenge data which is
sent to the client by the server.  An HMAC-style hash should be applied
to this message with an arbitrary length key common to both parties.
The authentication proceeds as follows:
</preamble>
    <artwork>
Client responds:
string    160-bits of SHA1 digest resulting from HMAC hashing
</artwork>
      </figure>
      <t>
The server should then check the hash and send ACK or NACK accordingly
depending on if the digest matches or not.
</t>
    </section>
  </back>
</rfc>