home *** CD-ROM | disk | FTP | other *** search
/ DEFCON 12 / DEFCON_12_CD-ROM_2004.iso / Arcieri / draft-arcieri-peer-distributed-transfer-protocol.txt < prev    next >
Text File  |  2004-07-08  |  51KB  |  1,681 lines
  1.  
  2.  
  3. Network Working Group                                    A. Arcieri, Ed.
  4. Internet-Draft                                                  PDTP.org
  5. Expires: January 4, 2005                                    July 6, 2004
  6.  
  7.  
  8.                    Peer Distributed Transfer Protocol
  9.             draft-arcieri-peer-distributed-transfer-protocol
  10.  
  11. Status of this Memo
  12.  
  13.    This document is an Internet-Draft and is in full conformance with
  14.    all provisions of Section 10 of RFC2026.
  15.  
  16.    Internet-Drafts are working documents of the Internet Engineering
  17.    Task Force (IETF), its areas, and its working groups. Note that other
  18.    groups may also distribute working documents as Internet-Drafts.
  19.  
  20.    Internet-Drafts are draft documents valid for a maximum of six months
  21.    and may be updated, replaced, or obsoleted by other documents at any
  22.    time. It is inappropriate to use Internet-Drafts as reference
  23.    material or to cite them other than as "work in progress."
  24.  
  25.    The list of current Internet-Drafts can be accessed at http://
  26.    www.ietf.org/ietf/1id-abstracts.txt.
  27.  
  28.    The list of Internet-Draft Shadow Directories can be accessed at
  29.    http://www.ietf.org/shadow.html.
  30.  
  31.    This Internet-Draft will expire on January 4, 2005.
  32.  
  33. Copyright Notice
  34.  
  35.    Copyright (C) The Internet Society (2004). All Rights Reserved.
  36.  
  37. Abstract
  38.  
  39.    The Peer Distributed Transfer Protocol (PDTP) provides a method of
  40.    transferring files using peers to aid in distribution of content,
  41.    similar to <http://www.bitconjurer.org/BitTorrent/>. PDTP servers
  42.    export a dynamically changing directory heirarchy, making it somewhat
  43.    more like HTTP or FTP, and support a number of other features such as
  44.    metadata rich directory listings and support for file integrity
  45.    validation through the use of DSS signatures, and large networks
  46.    designed to replace FTP mirroring.
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55. Arcieri                 Expires January 4, 2005                 [Page 1]
  56.  
  57. Internet-Draft        PDTP Protocol Specification              July 2004
  58.  
  59.  
  60. Table of Contents
  61.  
  62.    1.     Introduction . . . . . . . . . . . . . . . . . . . . . . .   3
  63.    1.1    Overview . . . . . . . . . . . . . . . . . . . . . . . . .   3
  64.    1.2    Integer abbreviations  . . . . . . . . . . . . . . . . . .   3
  65.    1.3    Handshaking  . . . . . . . . . . . . . . . . . . . . . . .   4
  66.    1.4    Transaction format . . . . . . . . . . . . . . . . . . . .   5
  67.    2.     Client/Server Protocol . . . . . . . . . . . . . . . . . .   7
  68.    2.1    Control transactions . . . . . . . . . . . . . . . . . . .   7
  69.    2.1.1  Command 0x1: Download File . . . . . . . . . . . . . . . .   7
  70.    2.1.2  Command 0x2: End Download  . . . . . . . . . . . . . . . .   8
  71.    2.1.3  Command 0x3: Retrieve Server Certificate . . . . . . . . .   8
  72.    2.1.4  Command 0x4: Change Listener Port  . . . . . . . . . . . .   8
  73.    2.1.5  Command 0x5: Set Maximum Download Concurrency  . . . . . .   9
  74.    2.1.6  Command 0x6: Set Maximum Upload Concurrency  . . . . . . .   9
  75.    2.1.7  Command 0x100: Directory Status  . . . . . . . . . . . . .  10
  76.    2.1.8  Command 0x101: File Status . . . . . . . . . . . . . . . .  10
  77.    2.1.9  Command 0x102: Directory Listing . . . . . . . . . . . . .  11
  78.    2.1.10 Command 0x103: File Information  . . . . . . . . . . . . .  12
  79.    2.1.11 Command 0x104: RDL Directory Listing . . . . . . . . . . .  13
  80.    2.1.12 Command 0x105: RDL File Information  . . . . . . . . . . .  14
  81.    2.2    Transfer management  . . . . . . . . . . . . . . . . . . .  14
  82.    2.2.1  Transfer management transactions (originating from
  83.           server)  . . . . . . . . . . . . . . . . . . . . . . . . .  14
  84.    2.2.2  Transfer management transactions (originating from
  85.           client)  . . . . . . . . . . . . . . . . . . . . . . . . .  16
  86.    3.     Piece Transfer Protocol  . . . . . . . . . . . . . . . . .  18
  87.    4.     Hub Protocol . . . . . . . . . . . . . . . . . . . . . . .  21
  88.    4.1    Handshaking  . . . . . . . . . . . . . . . . . . . . . . .  21
  89.    4.2    Transactions originating from hub  . . . . . . . . . . . .  22
  90.    4.2.1  Command 0x4: Change Listener Port  . . . . . . . . . . . .  22
  91.    4.2.2  Command 0x13: Authorize Piece Download Attempt . . . . . .  22
  92.    4.2.3  Command 0x200: Add Handle  . . . . . . . . . . . . . . . .  22
  93.    4.2.4  Command 0x201: Remove Handle . . . . . . . . . . . . . . .  23
  94.    4.3    Transactions originating from server . . . . . . . . . . .  23
  95.    5.     Proxy Protocol . . . . . . . . . . . . . . . . . . . . . .  24
  96.    6.     Acknowledgments  . . . . . . . . . . . . . . . . . . . . .  25
  97.           References . . . . . . . . . . . . . . . . . . . . . . . .  26
  98.           Author's Address . . . . . . . . . . . . . . . . . . . . .  26
  99.    A.     Path format  . . . . . . . . . . . . . . . . . . . . . . .  27
  100.    B.     Authorization mechanisms . . . . . . . . . . . . . . . . .  28
  101.           Intellectual Property and Copyright Statements . . . . . .  29
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111. Arcieri                 Expires January 4, 2005                 [Page 2]
  112.  
  113. Internet-Draft        PDTP Protocol Specification              July 2004
  114.  
  115.  
  116. 1. Introduction
  117.  
  118. 1.1 Overview
  119.  
  120.    This document describes version 1 of PDTP.  Version 1 currently only
  121.    allows for operation on IPv4 networks.  IPv6 support has been planned
  122.    from the start, and may or may not make it into version 1 depending
  123.    on the additional design complexity of facilitating transfers between
  124.    IPv4 and IPv6 hosts.
  125.  
  126.    PDTP is actually a suite of four different protocol formats used by
  127.    different components of the system:
  128.  
  129.    o  The client/server protocol (Section 2), which is used by clients
  130.       to query the contents of a file repository and manages the file
  131.       transfer process.  No file data is transferred using this protocol
  132.       directly.  The PDTP client/server protocol's standard port number
  133.       is XXXX (pending IANA assignment).
  134.  
  135.    o  The hub protocol (Section 4), used by PDTP servers to talk to PDTP
  136.       hubs in order to query file repository contents, network mappings,
  137.       and various transfer regulation functions.  The PDTP hub
  138.       protocol's standard port number is XXXX (pending IANA assignment).
  139.  
  140.    o  The piece transfer protocol (Section 3), or "peer protocol", used
  141.       by  clients to transfer pieces to/from each other or from PDTP
  142.       hubs.  The PDTP piece transfer protocol's standard port number is
  143.       XXXX (pending IANA assignment).
  144.  
  145.    o  The proxy protocol (Section 5), used by clients behind firewalls
  146.       to access PDTP servers.  The PDTP proxy protocol's standard port
  147.       number is XXXX (pending IANA assignment).
  148.  
  149.  
  150. 1.2 Integer abbreviations
  151.  
  152.    The following abbreviations will be used to describe various
  153.    integers:
  154.  
  155.    uint8    Big-endian 8-bit unsigned integer
  156.    uint16    Big-endian 16-bit unsigned integer
  157.    uint32    Big-endian 32-bit unsigned integer
  158.    uint64    Big-endian 64-bit unsigned integer
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167. Arcieri                 Expires January 4, 2005                 [Page 3]
  168.  
  169. Internet-Draft        PDTP Protocol Specification              July 2004
  170.  
  171.  
  172. 1.3 Handshaking
  173.  
  174.    Handshaking occurs when a PDTP client connects to a PDTP server:
  175.  
  176.    Client sends:
  177.    uint32    Magic number (0x50445450, "PDTP")
  178.  
  179.    Server responds:
  180.    uint32    Magic number (0x50445450, "PDTP")
  181.    uint16  Number of available protocol versions
  182.    uint16    Minimum protocol version
  183.    uint16    Next available protocol version [Optional]
  184.    ...
  185.    uint16  Maximum available protocol version [Optional]
  186.  
  187.    - OR -
  188.  
  189.    Server rebonds:
  190.    uint16    Magic number (0x5244526E, "REDR");
  191.    uint16    String length
  192.    string    Name of destination host
  193.    uint16    Host port
  194.  
  195.    - OR -
  196.  
  197.    Server responds:
  198.    uint16    Magic number (0x41555448, "AUTH")
  199.    ...    Authorization process (See Appendix C)
  200.    uint32  Magic number (0x50445450, "PDTP")
  201.    uint16  Minimum protocol version
  202.    uint16  Maximum protocol version
  203.  
  204.    The 'PDTP' response indicates the server has accepted the connection.
  205.    An 'AUTH' response may be issued prior to a 'PDTP' response if the
  206.    server requires authorization to login.
  207.  
  208.    If the server wishes to redirect the client to a different named
  209.    server, it can send a REDR response, followed by the hostname, IPv4
  210.    address in dotted quad format, or IPv6 address of the remote server,
  211.    and the port number to redirect to.
  212.  
  213.    The server and client arbitrate which protocol version to use by
  214.    having the client pick a version number from an ordered list.  The
  215.    list consists of a 16-bit value indicating how many protocol versions
  216.    are supported, and an ordered list of 16-bit integers comprising the
  217.    specific protocol revisions supported.
  218.  
  219.    Currently the only available protocol version is 1.  Therefore this
  220.  
  221.  
  222.  
  223. Arcieri                 Expires January 4, 2005                 [Page 4]
  224.  
  225. Internet-Draft        PDTP Protocol Specification              July 2004
  226.  
  227.  
  228.    list should consist only of two 16-bit integers, each set to 1, the
  229.    first to indicate that only one protocol version is available and the
  230.    second to indicate that version 1 is the only supported version.
  231.  
  232.    Client responds:
  233.    uint16    Protocol version
  234.  
  235.    The client then selects which protocol version it would like to use.
  236.    If the client selects a protocol version which wasn't in the list,
  237.    the client has violated the protocol and the server should terminate
  238.    the connection.
  239.  
  240. 1.4 Transaction format
  241.  
  242.    All communication following the handshake takes the form of
  243.    transactions. Transactions may originate from the server as well, in
  244.    which case the serial number of the response should be set to zero.
  245.    All outstanding transactions from a client should have a unique
  246.    serial number so the client can determine which transaction a
  247.    particular response is associated with.
  248.  
  249.    Client or server sends: [Required]
  250.    uint32  Transaction length
  251.    uint32  Transaction serial number
  252.    uint16    Transaction ID
  253.    uint16  Object count
  254.  
  255.    Each transaction begins with a length field, which is the length of
  256.    the entire remainder of the transaction in bytes (i.e. the 4 bytes
  257.    for the transaction length value itself are not included)  Thus the
  258.    smallest possible value for the transaction length is 8 bytes: 4
  259.    bytes for the serial number, 2 for the transaction ID, and two for
  260.    the object count.  The entire transaction would be 12 bytes, counting
  261.    4 extra bytes for the transaction length value.
  262.  
  263.    Every transaction has a type, which is specified in the "Transaction
  264.    ID" field. This transaction ID actually consists of a 1-bit boolean
  265.    value which indicates whether the transaction is 0: a command or 1: a
  266.    reply.  The remaining 15 bits in the field comprise a big endian
  267.    integer identifier for the transaction. Specific types of
  268.    transactions will be enumerated below.  This value is set to zero to
  269.    indicate an error when responding to a client's transaction.
  270.    Otherwise, all server responses will have the same ID and serial
  271.    number as the original client's transaction.
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279. Arcieri                 Expires January 4, 2005                 [Page 5]
  280.  
  281. Internet-Draft        PDTP Protocol Specification              July 2004
  282.  
  283.  
  284.    Transactions may or may not have a number of parameters known as
  285.    "objects". The number of objects contained within a transaction are
  286.    stored in the "Object count" field of the transaction header.  The
  287.    length of all the objects and the object headers is counted in the
  288.    "Transaction length" value. Objects take the following format:
  289.  
  290.    uint32  Object length
  291.    uint16    Object ID
  292.    string    Object payload of specified length
  293.  
  294.    What follows is a description of all transactions and associated
  295.    objects used by the various protocols in the PDTP suite.  All objects
  296.    are mandatory unless stated otherwise.  Objects should be arranged in
  297.    order of their respective numerical object identifiers from least to
  298.    greatest.  This document arranges its object lists in such a manner;
  299.    transactions should be constructed in the same order presented in
  300.    this document in order to be valid.
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335. Arcieri                 Expires January 4, 2005                 [Page 6]
  336.  
  337. Internet-Draft        PDTP Protocol Specification              July 2004
  338.  
  339.  
  340. 2. Client/Server Protocol
  341.  
  342. 2.1 Control transactions
  343.  
  344. 2.1.1 Command 0x1: Download File
  345.  
  346.    [Objects:]
  347.  
  348.    Object ID:      0x2 (Path) [See Appendix A for format]
  349.    Payload:        string  Path to file
  350.  
  351.    Object ID:    0x6 (Piece List) [Optional]
  352.    Payload:    string    Piece list
  353.  
  354.    This transaction requests a download from the server.  The piece list
  355.    consists of a list of uint32 pairs, which are the start and end of
  356.    ranges of piece indices we still need.  So, for example, if we are
  357.    beginning a new download of a file with 2000 pieces, piece list would
  358.    be 8 bytes long and contain two uint32 values, 0 and 1999.  If we are
  359.    getting the same file but have pieces 1000-1500, we would send 16
  360.    bytes which contain 4 uint32 values, 0, 999, 1501, and 1999.  If we
  361.    have everything but the first piece, we would send 8 bytes which
  362.    contain two uint32 values, 0 and 0.
  363.  
  364.    The piece list object may be optionally omitted, which indicates that
  365.    the client does not possess any pieces of the given file.
  366.  
  367.    If the file handle and piece list are valid, the server will respond
  368.    with:
  369.  
  370.    Object ID:      0x1 (File Handle)
  371.    Payload:        uint32  File handle ID
  372.  
  373.    File transfers are stateful and server regulated.  The server will
  374.    asynchronously send transfer management transactions for the given
  375.    file handle until the client sends the 0x2: End Download transaction
  376.    or the server sends the 0x17: End Transfer transaction.
  377.  
  378.    In the event of an error, the server will respond with the following:
  379.  
  380.    Object ID:      0x500 (Error message)
  381.    Payload:        string  Error message
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391. Arcieri                 Expires January 4, 2005                 [Page 7]
  392.  
  393. Internet-Draft        PDTP Protocol Specification              July 2004
  394.  
  395.  
  396. 2.1.2 Command 0x2: End Download
  397.  
  398.    [Objects:]
  399.  
  400.    Object ID:    0x1 (File Handle)
  401.    Payload:    uint32    File handle ID
  402.  
  403.    This transaction is sent by clients to terminate a transfer.  It
  404.    should not be confused with transaction 0x16 (Terminate Transfer)
  405.    which is used by the server to inform clients that a download has
  406.    been terminated.  This transaction should be sent by clients when
  407.    they are satisfied with the set of pieces they have received.
  408.    Otherwise, even after a client has successfully transferred all the
  409.    pieces of a file, the server will continue to include this file in
  410.    the piece selection process for uploaders, and if the client attempts
  411.    to download another file they can upload pieces from a file they've
  412.    already received successfully in order to earn the right to transfer
  413.    more pieces from a different file.
  414.  
  415.    On success the server will respond with a transaction with no
  416.    objects, or on error it should respond with the following:
  417.  
  418.    Object ID:      0x500 (Error message)
  419.    Payload:        string  Error message
  420.  
  421.  
  422. 2.1.3 Command 0x3: Retrieve Server Certificate
  423.  
  424.    This transaction takes no objects from the client.  The server
  425.    responds with:
  426.  
  427.    Object ID:    0x40 (X.509 Certificate)
  428.    Payload:    uint32    Server certificate containing DSA key
  429.  
  430.    Administrators of PDTP servers may elect to allow the authenticity of
  431.    certain files to be verified using a DSS cryptographic signature.
  432.    This transaction allows retrieval of an X.509 certificate containing
  433.    the DSA key used to sign files on the server.
  434.  
  435.    More information on X.509 can be found in RFC2459 [4].
  436.  
  437. 2.1.4 Command 0x4: Change Listener Port
  438.  
  439.    [Objects:]
  440.  
  441.    Object ID:    0x12 (Port Number) [Optional]
  442.    Payload:    uint16    New listener port number
  443.  
  444.  
  445.  
  446.  
  447. Arcieri                 Expires January 4, 2005                 [Page 8]
  448.  
  449. Internet-Draft        PDTP Protocol Specification              July 2004
  450.  
  451.  
  452.    This transaction allows a client to dynamically reassign their
  453.    listener port.  By default, the PDTP server will assume the client is
  454.    capable of receiving connections on port 4045 unless specified
  455.    otherwise by this transaction.  If a 0x12 (Port Number) object is not
  456.    passed in this transaction, then the client is set to passive mode.
  457.  
  458.    If the port number is valid, the server will respond with a
  459.    transaction without any objects.  In the event of an error, the
  460.    server will respond with the following:
  461.  
  462.    Object ID:      0x500 (Error Message)
  463.    Payload:        string  Error message
  464.  
  465.  
  466. 2.1.5 Command 0x5: Set Maximum Download Concurrency
  467.  
  468.    [Objects:]
  469.  
  470.    Object ID:    0x7 (Concurrency Value)
  471.    Payload:    uint16    New maximum concurrent connections
  472.  
  473.    By default clients will be assigned a server side default for the
  474.    maximum number of concurrent piece downloads they wish to perform.
  475.    Clients may specify this value explicitly using this transaction.  A
  476.    value of zero is not allowed, and servers may elect to set a ceiling
  477.    for this value.
  478.  
  479.    If the concurrency value is valid, the server will respond with a
  480.    transaction without any objects.  In the event of an error, the
  481.    server will respond with the following:
  482.  
  483.    Object ID:      0x500 (Error Message)
  484.    Payload:        string  Error message
  485.  
  486.  
  487. 2.1.6 Command 0x6: Set Maximum Upload Concurrency
  488.  
  489.    [Objects:]
  490.  
  491.    Object ID:      0x7 (Concurrency Value)
  492.    Payload:        uint16  New maximum concurrent connections
  493.  
  494.    By default clients will be assigned a server side default for the
  495.    maximum number of concurrent piece uploads they wish to perform.
  496.    Clients may specify this value explicity using this transaction.  A
  497.    value of zero is not allowed, and servers may elect to set a ceiling
  498.    for this value.
  499.  
  500.  
  501.  
  502.  
  503. Arcieri                 Expires January 4, 2005                 [Page 9]
  504.  
  505. Internet-Draft        PDTP Protocol Specification              July 2004
  506.  
  507.  
  508.    If the concurrency value is valid, the server will respond with a
  509.    transaction without any objects.  In the event of an error, the
  510.    server will respond with the following:
  511.  
  512.    Object ID:      0x500 (Error Message)
  513.    Payload:        string  Error message
  514.  
  515.  
  516. 2.1.7 Command 0x100: Directory Status
  517.  
  518.    [Objects:]
  519.  
  520.    Object ID:      0x2 (Path) [See Appendix A for format]
  521.    Payload:        string  Path to directory
  522.  
  523.    This transaction requests the status of the specified directory.  The
  524.    server returns a transaction with the following object:
  525.  
  526.    Object ID:      0x102 (Entry Timestamp)
  527.    Payload:        string  48-bit timestamp value
  528.  
  529.    The timestamp is a 48-bit string which can be broken down as follows:
  530.  
  531.    uint16          Year
  532.    uint32          Year seconds
  533.  
  534.    The timestamp format consists of an 16-bit integer year and a 32-bit
  535.    value representing the number of seconds since the beginning of that
  536.    year.
  537.  
  538.    In the event of an error, the server will return the following:
  539.  
  540.    Object ID:      0x500 (Error Message)
  541.    Payload:        string  Error message
  542.  
  543.  
  544. 2.1.8 Command 0x101: File Status
  545.  
  546.    [Objects:]
  547.  
  548.    Object ID:      0x2 (Path) [See Appendix A for format]
  549.    Payload:        string  Path to file
  550.  
  551.    This transaction requests the status of the specified file.  The
  552.    server returns a transaction with the following object:
  553.  
  554.    Object ID:      0x102 (Entry Timestamp)
  555.    Payload:        string  48-bit timestamp value
  556.  
  557.  
  558.  
  559. Arcieri                 Expires January 4, 2005                [Page 10]
  560.  
  561. Internet-Draft        PDTP Protocol Specification              July 2004
  562.  
  563.  
  564.    The timestamp is a 48-bit string which can be broken down as follows:
  565.  
  566.    uint16          Year
  567.    uint32          Year seconds
  568.  
  569.    The timestamp format consists of an 16-bit integer year and a 32-bit
  570.    value representing the number of seconds since the beginning of that
  571.    year.
  572.  
  573.    In the event of an error, the server will return the following:
  574.  
  575.    Object ID:      0x500 (Error Message)
  576.    Payload:        string  Error message
  577.  
  578.  
  579. 2.1.9 Command 0x102: Directory Listing
  580.  
  581.    [Objects:]
  582.  
  583.    Object ID:      0x2 (Path) [See Appendix A for format]
  584.    Payload:        string  Path to directory
  585.  
  586.    The transaction requests a listing of the specified directory.  The
  587.    server returns an arbitrary number of the following objects:
  588.  
  589.    Object ID:      0x100 (Subdirectory Entry)
  590.    Payload:        string  Subdirectory information
  591.  
  592.    Object ID:    0x101 (File Entry)
  593.    Payload:    string    File information
  594.  
  595.    The subdirectory information string (0x100) should consist of the
  596.    following:
  597.  
  598.    uint16          Modification timestamp: year
  599.    uint32          Modification timestamp: year seconds
  600.    uint16          Length of directory name
  601.    string          Directory name
  602.  
  603.    The file information string (0x101) should consist of the following:
  604.  
  605.    uint16        Modification timestamp: year
  606.    uint32        Modification timestamp: year seconds
  607.    uint64        File length in bytes
  608.    uint16        Length of filename
  609.    string        Filename
  610.  
  611.    The timestamp format consists of an 16-bit integer year and a 32-bit
  612.  
  613.  
  614.  
  615. Arcieri                 Expires January 4, 2005                [Page 11]
  616.  
  617. Internet-Draft        PDTP Protocol Specification              July 2004
  618.  
  619.  
  620.    value representing the number of seconds since the beginning of that
  621.    year.
  622.  
  623.    In the event of an error, the server will return the following:
  624.  
  625.    Object ID:      0x500 (Error Message)
  626.  
  627.    Payload:        string  Error message
  628.  
  629.  
  630. 2.1.10 Command 0x103: File Information
  631.  
  632.    [Objects:]
  633.  
  634.    Object ID:      0x2 (Path) [See Appendix A for format]
  635.    Payload:        string  Path to file
  636.  
  637.    This transaction requests the information required to complete the
  638.    download process.  The server responds with the following objects:
  639.  
  640.    Object ID:      0x3 (File Length)
  641.    Payload:        uint64  File length
  642.  
  643.    Object ID:      0x4 (Piece Length)
  644.    Payload:        uint32  Piece length
  645.  
  646.    And either of the following objects:
  647.  
  648.    Object ID:      0x20 (MD5 Hashes)
  649.    Payload:        string  Buffer of MD5 hashes for all pieces in file
  650.  
  651.    - OR -
  652.  
  653.    Object ID:      0x21 (SHA1 Hashes)
  654.    Payload:        string  Buffer of SHA1 hashes for all pieces in file
  655.  
  656.    If a cryptographic signature is available for a given file it should
  657.    be included in the transaction as well:
  658.  
  659.    Object ID:    0x41 (DSS Signature) [Optional]
  660.    Payload:    string  DSS signature of file
  661.  
  662.    Or in the event of an error, the server responds with an error
  663.    transaction containing only the following object:
  664.  
  665.    Object ID:      0x500 (Error Message)
  666.    Payload:        string  Error message
  667.  
  668.  
  669.  
  670.  
  671. Arcieri                 Expires January 4, 2005                [Page 12]
  672.  
  673. Internet-Draft        PDTP Protocol Specification              July 2004
  674.  
  675.  
  676.    The 0x20 or 0x21 object is a list of hashes for each piece in the
  677.    file. The number of bytes in the 0x20 or 0x21 object will be the
  678.    number of bytes in a single hash digest * ceiling(file length / piece
  679.    length). So, for 0x20 (MD5) with a piece length of 8 and a file
  680.    length of 17 the length of the 0x20 object will be 48 bytes, which is
  681.    the length of a single MD5 hash (16 bytes) * 3.
  682.  
  683.    Currently MD5 and SHA1 are the only supported hash ciphers, but the
  684.    protocol is designed so objects 0x22, 0x23, etc. are reserved for
  685.    future hash ciphers.
  686.  
  687.    After receiving a list of hashes, the client should then compute
  688.    hashes for each piece in any pre-existing copy of the file and
  689.    compare them to the server-provided list to determine what pieces of
  690.    the file remain to be transferred.  This list should be passed as the
  691.    0x6 (Piece List) object of the 0x1 (Download File) transaction.
  692.  
  693.    The optional 0x41 (DSS Signature) object is the SHA1 hash of the file
  694.    encrypted with the DSA key contained within the server's certificate,
  695.    which may be retrieved with the 0x3 (Retrieve Server Certificate)
  696.    transaction.  This is used to ensure that files on the server have
  697.    not been tampered with prior to downloading.
  698.  
  699.    For detailed information about the MD5 cipher, please see RFC1321
  700.    [1]. For detailed information about the SHA1 cipher, please see
  701.    RFC3174 [7]. For more information on the DSS, please see FIPS186 [8]
  702.    and RFC2802 [6].
  703.  
  704. 2.1.11 Command 0x104: RDL Directory Listing
  705.  
  706.    [Objects:]
  707.  
  708.    Object ID:      0x2 (Path) [See Appendix A for format]
  709.    Payload:        string  Path to directory
  710.  
  711.    This transaction requests a Rich Directory Listing.  The server
  712.    responds:
  713.  
  714.    Object ID:    0x104 (RDL response)
  715.    Payload:    string    XML document containing RDL response
  716.  
  717.    Or in the event of an error, the server responds with the following:
  718.  
  719.    Object ID:      0x500 (Error Message)
  720.    Payload:        string  Error message
  721.  
  722.    RDL is an XML directory listing format which may be used secondarily
  723.    to the 0x102 (Directory Listing) transaction in order to obtain a
  724.  
  725.  
  726.  
  727. Arcieri                 Expires January 4, 2005                [Page 13]
  728.  
  729. Internet-Draft        PDTP Protocol Specification              July 2004
  730.  
  731.  
  732.    metadata rich directory listing with extended file attributes.  The
  733.    format of these results is not specified in this document, but may be
  734.    found at:
  735.  
  736.    <http://pdtp.org/rdl.php>
  737.  
  738. 2.1.12 Command 0x105: RDL File Information
  739.  
  740.    [Objects:]
  741.  
  742.    Object ID:      0x2 (Path) [See Appendix A for format]
  743.    Payload:        string  Path to file
  744.  
  745.    This transaction requests RDL attributes for a file.  The server
  746.    responds:
  747.  
  748.    Object ID:      0x104 (RDL response)
  749.    Payload:        string  XML document containing RDL response
  750.  
  751.    Or in the event of an error, the server responds with the following:
  752.  
  753.    Object ID:      0x500 (Error Message)
  754.    Payload:        string  Error message
  755.  
  756.    This is a counterpart to transaction 0x103 (File Information) only
  757.    also returning extended file attributes from the 0x104 (RDL Directory
  758.    Listing) transaction.
  759.  
  760. 2.2 Transfer management
  761.  
  762. 2.2.1 Transfer management transactions (originating from server)
  763.  
  764. 2.2.1.1 Command 0x10: Send Piece to Peer
  765.  
  766.    [Objects:]
  767.  
  768.    Object ID:    0x1 (File Handle)
  769.    Payload:    uint32    File handle ID
  770.  
  771.    Object ID:    0x6 (Piece ID)
  772.    Payload:    uint32    Piece number
  773.  
  774.    Object ID:    0x10 (IPv4 Address)
  775.    Payload:    uint32    Address of remote peer
  776.  
  777.    Object ID:    0x12 (Port Number)
  778.    Payload:    uint16    Port number of remote peer
  779.  
  780.  
  781.  
  782.  
  783. Arcieri                 Expires January 4, 2005                [Page 14]
  784.  
  785. Internet-Draft        PDTP Protocol Specification              July 2004
  786.  
  787.  
  788.    This transaction instructs one peer to connect to another and send
  789.    the specified piece from the specified file.
  790.  
  791. 2.2.1.2 Command 0x11: Receive Piece from Peer
  792.  
  793.    [Objects:]
  794.  
  795.    Object ID:      0x1 (File Handle)
  796.    Payload:        uint32  File handle ID
  797.  
  798.    Object ID:      0x6 (Piece ID)
  799.    Payload:        uint32  Piece number
  800.  
  801.    Object ID:      0x10 (IPv4 Address)
  802.    Payload:        uint32  Address of remote peer
  803.  
  804.    Object ID:      0x12 (Port Number)
  805.    Payload:        uint16  Port number of remote peer
  806.  
  807.    This transaction instructs one peer to connect to another and receive
  808.    the specified piece from the specified file.
  809.  
  810. 2.2.1.3 Command 0x16: Terminate Piece Transfer
  811.  
  812.    [Objects:]
  813.  
  814.    Object ID:    0x1 (File Handle)
  815.    Payload:    uint32    File handle ID
  816.  
  817.    Object ID:    0x6 (Piece ID)
  818.    Payload:    uint32    Piece number
  819.  
  820.    Object ID:    0x10 (IPv4 Address)
  821.    Payload:    uint32    Address of remote peer
  822.  
  823.    This transaction instructs a client which is uploading a piece to one
  824.    of its peers to terminate its upload.  No response from the client
  825.    doing the uploading is expected.  Instead, the server should wait for
  826.    a 0x15 (Report failed piece transfer) transaction originating from
  827.    the client which is downloading the piece.  This command should not
  828.    be sent to the client which is downloading a piece; this is a
  829.    protocol violation and should be ignored (or noted in a log as a
  830.    protocol violation)
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839. Arcieri                 Expires January 4, 2005                [Page 15]
  840.  
  841. Internet-Draft        PDTP Protocol Specification              July 2004
  842.  
  843.  
  844. 2.2.1.4 Command 0x17: Terminate File Transfer
  845.  
  846.    [Objects:]
  847.  
  848.    Object ID:    0x1 (File Handle)
  849.    Payload:    uint32    File handle ID
  850.  
  851.    This transaction informs a client that the file associated with the
  852.    given handle is no longer being offered by the server, and that the
  853.    client should terminate all attempts to receive that particular file.
  854.  
  855. 2.2.2 Transfer management transactions (originating from client)
  856.  
  857. 2.2.2.1 Command 0x12: Authorize Piece Upload Attempt
  858.  
  859.    [Objects:]
  860.  
  861.    Object ID:    0x1 (File Handle)
  862.    Payload:    uint32    File handle ID
  863.  
  864.    Object ID:    0x6 (Piece ID)
  865.    Payload:    uint32    Piece number
  866.  
  867.    Object ID:    0x10 (IPv4 Address)
  868.    Payload:    uint32    Address of remote peer
  869.  
  870.    This transaction informs the server that a peer has connected and is
  871.    requesting to upload the specified piece (using an opcode of 0x10).
  872.    The listening peer then and asks for server authorization for the
  873.    transfer to continue.  The server will always respond with a
  874.    transaction without any objects.  If the connection attempt is
  875.    authorized the response transaction will have its transaction ID set
  876.    to 0x12, or if the connection is unauthorized the server will send an
  877.    error response, that is that the transaction ID will be set to 0.
  878.  
  879. 2.2.2.2 Command 0x13: Authorize Piece Download Attempt
  880.  
  881.    [Objects:]
  882.  
  883.    Object ID:      0x1 (File Handle)
  884.    Payload:        uint32  File handle ID
  885.  
  886.    Object ID:      0x6 (Piece ID)
  887.    Payload:        uint32  Piece number
  888.  
  889.    Object ID:      0x10 (IPv4 Address)
  890.    Payload:        uint32  Address of remote peer
  891.  
  892.  
  893.  
  894.  
  895. Arcieri                 Expires January 4, 2005                [Page 16]
  896.  
  897. Internet-Draft        PDTP Protocol Specification              July 2004
  898.  
  899.  
  900.    This transaction is identical to the one above (0x12) except it is
  901.    used when the remote peer requests a piece download (using opcode
  902.    0x11)
  903.  
  904. 2.2.2.3 Command 0x14: Report Successful Piece Transfer
  905.  
  906.    [Objects:]
  907.  
  908.    Object ID:    0x1 (File Handle)
  909.    Payload:    uint32    File handle ID
  910.  
  911.    Object ID:    0x6 (Piece ID)
  912.    Payload:    uint32    Piece number
  913.  
  914.    Object ID:    0x10 (IPv4 Address)
  915.    Payload:    uint32    Address of remote peer
  916.  
  917.    This transaction informs the server that a piece transfer has
  918.    completed successfully.  It should be sent by both peers involved in
  919.    a transfer every time a piece transfer completes successfully.  The
  920.    server does not send a response to this transaction; it is used only
  921.    for the server's internal bookkeeping.
  922.  
  923. 2.2.2.4 Command 0x15: Report Failed Piece Transfer
  924.  
  925.    [Objects:]
  926.  
  927.    Object ID:    0x1 (File Handle)
  928.    Payload:    uint32    File handle ID
  929.  
  930.    Object ID:    0x6 (Piece ID)
  931.    Payload:    uint32    Piece number
  932.  
  933.    Object ID:    0x10 (IPv4 Address)
  934.    Payload:    uint32    Address of remote peer
  935.  
  936.    This transaction is functionally equivalent to the one above (0x14)
  937.    except it is used to report a failed piece transfer.  The server
  938.    sends no response.
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951. Arcieri                 Expires January 4, 2005                [Page 17]
  952.  
  953. Internet-Draft        PDTP Protocol Specification              July 2004
  954.  
  955.  
  956. 3. Piece Transfer Protocol
  957.  
  958.    In PDTP, pieces are transferred between a peer listening on a TCP
  959.    port, which we will hereafter refer to as the 'listener', and a peer
  960.    connecting to this TCP port, which we will hereafter refer to as the
  961.    'connecting peer'.
  962.  
  963.    The piece transfer protocol is very simple by design.  The connecting
  964.    peer begins the exchange by sending the following:
  965.  
  966.    Connecting peer sends:
  967.    uint32    Magic number    (0x50545050, "PTPP")
  968.  
  969.    Listener responds:
  970.    uint32    Magic number    (0x50545050, "PTPP")
  971.    uint16    Minimum protocol version
  972.    uint16    Maximum protocol version
  973.  
  974.    Both the minimum and maximum protocol version should currently be 1.
  975.    In the future these values will be the lowest and highest protocol
  976.    versions supported by the server.
  977.  
  978.    In the future, the response from the connecting peer will vary
  979.    depending on the protocol versions supported by the listener and the
  980.    underlying transport protocol.  However, at the current time the
  981.    connecting peer will always respond with the following:
  982.  
  983.    uint16  Protocol version
  984.    uint16    Operation code
  985.  
  986.    The connecting peer selects which protocol version it would like to
  987.    use.  This value must be greater than or equal to the lowest version
  988.    supported and less than or equal to the highest protocol version
  989.    supported by the server.  Any values which don't meet this criteria
  990.    are a protocol violation, and the connection should be terminated by
  991.    the server.  At this point in time, this value should always be 1.
  992.  
  993.    The operation code will be one of the following values (note that
  994.    these correspond directly to the transaction IDs from the server
  995.    originated transactions to begin a piece transfer):
  996.  
  997.    0x10:    Piece upload request (connecting peer => listener)
  998.    0x11:    Piece download request (listener => connecting peer)
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007. Arcieri                 Expires January 4, 2005                [Page 18]
  1008.  
  1009. Internet-Draft        PDTP Protocol Specification              July 2004
  1010.  
  1011.  
  1012.    After the protocol version and operation code, the connecting peer
  1013.    will send the following values which describe exactly what piece from
  1014.    what server is to be transferred:
  1015.  
  1016.    uint32  IPv4 address of coordinating server in network byte order
  1017.    uint16    Port of coordinating server
  1018.    uint32  File handle ID
  1019.    uint32  Piece ID
  1020.  
  1021.    The listener should then report the connecting peer's request to the
  1022.    coordinating server using the proper transaction from the "Transfer
  1023.    Management Transactions" section above: either 0x12 for a piece
  1024.    upload request or 0x13 for a piece download request.
  1025.  
  1026.    If the connecting peer requests a piece upload, then then listener
  1027.    should first authorize the connection with the server.  If the server
  1028.    does not give authorization for this transfer the listener should
  1029.    close the connection. Otherwise if authorization is received it
  1030.    should send the following:
  1031.  
  1032.    uint32    Piece offset
  1033.    uint32  Bytes to transfer
  1034.  
  1035.    This allows the listener, which is downloading the piece, to resume
  1036.    the transfer of a piece which has already been partially received by
  1037.    specifying an offset (in bytes) from the beginning of the piece from
  1038.    which to begin the transfer.  If this value is equal to or greater
  1039.    than the piece size, or if the offset plus the bytes to transfer
  1040.    exceeds the piece size, then the connecting peer should disconnect
  1041.    and report a failed transfer due to a protocol violation.  Otherwise
  1042.    it should begin sending the piece from the specified offset.  The
  1043.    bytes to transfer field allows clients to grab the beginning portion
  1044.    of a piece if they believe that portion to have been "tainted" by a
  1045.    malicious client.
  1046.  
  1047.    If the connecting peer is requesting a piece download, then in
  1048.    addition to the header already enumerated above it should send:
  1049.  
  1050.    uint32    Piece offset
  1051.    uint32    Bytes to transfer
  1052.  
  1053.    The listener should then request authorization from the server, and
  1054.    if the server does not authorize the transfer the listener should
  1055.    close the connection. Otherwise the listener should begin sending the
  1056.    piece from the specified offset.
  1057.  
  1058.    If the connection is lost before the piece transfer completes, this
  1059.    should be reported to the server using the appropriate transaction
  1060.  
  1061.  
  1062.  
  1063. Arcieri                 Expires January 4, 2005                [Page 19]
  1064.  
  1065. Internet-Draft        PDTP Protocol Specification              July 2004
  1066.  
  1067.  
  1068.    from the "Transfer Management Transactions" section, 0x15 (Report
  1069.    failed transfer).
  1070.  
  1071.    If the piece transfer succeeds, both the connecting peer and listener
  1072.    should report so to the server using the appropriate transaction from
  1073.    the "Transfer Management Transactions" section, 0x14 (Report
  1074.    successful transfer).
  1075.  
  1076.    After a successful piece transfer, both the connecting peer and
  1077.    listener have the option of closing the connection.  Otherwise, the
  1078.    listener can wait for the following:
  1079.  
  1080.    uint16    Operation code
  1081.  
  1082.    and the two peers can then begin another piece transfer if so
  1083.    desired.
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119. Arcieri                 Expires January 4, 2005                [Page 20]
  1120.  
  1121. Internet-Draft        PDTP Protocol Specification              July 2004
  1122.  
  1123.  
  1124. 4. Hub Protocol
  1125.  
  1126.    Unlike the client/server protocol, communication between servers and
  1127.    hubs allows fully synchronous, bidirectional communication.
  1128.    Consequently, both the server and hub will use serial numbers to keep
  1129.    track of outstanding transactions.  Serial numbers used by the server
  1130.    and hub are distinct, and the server and hub distinguish requests
  1131.    from replies by transaction types alone.
  1132.  
  1133. 4.1 Handshaking
  1134.  
  1135.    PDTP hubs provide directory structure information to a PDTP server or
  1136.    cluster of PDTP servers.  In order to function, a PDTP server must be
  1137.    connected to a hub.  A PDTP server should connect to one and only one
  1138.    PDTP hub at a single time.  The connection is made via TCP.
  1139.  
  1140.    After connecting the server initiates the handshaking process.
  1141.  
  1142.    Server sends:
  1143.    uint32  Magic number    (0x50445350, "PDSP")
  1144.  
  1145.    Hub responds:
  1146.    uint32  Magic number (0x50445450, "PDSP")
  1147.    uint16  Minimum protocol version
  1148.    uint16  Maximum protocol version
  1149.  
  1150.    - OR -
  1151.  
  1152.    Hub responds:
  1153.    uint16  Magic number (0x41555448, "AUTH")
  1154.    ...     Authorization process (See Appendix C)
  1155.    uint32  Magic number (0x50445450, "PDSP")
  1156.    uint16  Minimum protocol version
  1157.    uint16  Maximum protocol version
  1158.  
  1159.    The 'PDSP' response indicates the hub has accepted the connection.
  1160.    An 'AUTH' response may be issued prior to a 'PDSP' response if the
  1161.    hub requires authorization to allow a server to connect.
  1162.  
  1163.    Both the minimum and maximum protocol version should currently be 1.
  1164.    In the future these values will be the lowest and highest protocol
  1165.    versions supported by the hub.
  1166.  
  1167.    The server should respond with the following:
  1168.  
  1169.    uint16  Protocol version
  1170.  
  1171.    The server selects which protocol version it would like to use.  This
  1172.  
  1173.  
  1174.  
  1175. Arcieri                 Expires January 4, 2005                [Page 21]
  1176.  
  1177. Internet-Draft        PDTP Protocol Specification              July 2004
  1178.  
  1179.  
  1180.    value must be greater than or equal to the lowest version supported
  1181.    and less than or equal to the highest protocol version supported by
  1182.    the server.  Any values which don't meet this criteria are a protocol
  1183.    violation, and the connection should be terminated by the hub.  At
  1184.    this point in time, this value should always be 1.
  1185.  
  1186.    After handshaking, the hub and server communicate using the standard
  1187.    transaction format.  The following transactions are supported:
  1188.  
  1189. 4.2 Transactions originating from hub
  1190.  
  1191. 4.2.1 Command 0x4: Change Listener Port
  1192.  
  1193.    This transaction is documented in section 2.1.  It is used to inform
  1194.    the server that the hub's piece server is listening on a port other
  1195.    than the one to which the server connected.
  1196.  
  1197. 4.2.2 Command 0x13: Authorize Piece Download Attempt
  1198.  
  1199.    This transaction is documented in section 2.2.2.  It is used when a
  1200.    client connects to the hub's piece server and is requesting a
  1201.    particular piece. The hub requests authorization from the server, and
  1202.    the server can either grant or deny the connecting client's request
  1203.    for a particular piece.
  1204.  
  1205. 4.2.3 Command 0x200: Add Handle
  1206.  
  1207.    [Objects:]
  1208.  
  1209.    Object ID:    0x1 (File Handle)
  1210.    Payload:    uint32    File handle ID
  1211.  
  1212.    Object ID:      0x2 (Path) [See Appendix A for format]
  1213.    Payload:        string  Path to file
  1214.  
  1215.    Object ID:    0x6 (Piece ID)
  1216.    Payload:    uint16    Number of pieces in file
  1217.  
  1218.    This transaction informs the server that the given handle is now
  1219.    valid and consists of the given number of pieces.  This transaction
  1220.    should be sent with a serial number of zero, and no response is
  1221.    returned.
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231. Arcieri                 Expires January 4, 2005                [Page 22]
  1232.  
  1233. Internet-Draft        PDTP Protocol Specification              July 2004
  1234.  
  1235.  
  1236. 4.2.4 Command 0x201: Remove Handle
  1237.  
  1238.    [Objects:]
  1239.  
  1240.    Object ID:      0x1 (File Handle)
  1241.    Payload:        uint32  File handle ID
  1242.  
  1243.    This transaction informs the server that the given handle is no
  1244.    longer valid. The server should terminate all transfers associated
  1245.    with the given handle. This transaction should be sent with a serial
  1246.    number of zero, and no response is returned.
  1247.  
  1248. 4.3 Transactions originating from server
  1249.  
  1250.    PDTP hubs also implement all directory listing transactions
  1251.    implemented by servers and used by clients for querying directories.
  1252.    The expected behavior of a PDTP server is that requests for directory
  1253.    or file information sent to the server are redirected to the hub, but
  1254.    that the 0x100 and 0x101 status queries can be used to implement a
  1255.    caching behavior within the server, to mitigate the amount of
  1256.    bandwidth used by the hub for handling these queries.  Hubs should
  1257.    therefore be able to answer the following queries authoritatively for
  1258.    the files and directory maps they are serving:
  1259.  
  1260.    Command 0x100:  Directory Status
  1261.    Command 0x101:  File Status
  1262.    Command 0x102:  Directory Listing
  1263.    Command 0x103:  File Information
  1264.    Command 0x104:  RDL Directory Listing
  1265.    Command 0x105:    RDL File Information
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287. Arcieri                 Expires January 4, 2005                [Page 23]
  1288.  
  1289. Internet-Draft        PDTP Protocol Specification              July 2004
  1290.  
  1291.  
  1292. 5. Proxy Protocol
  1293.  
  1294.    PDTP supports making outgoing server and peer connections as well as
  1295.    redirection of incoming peer connections through a proxy server.
  1296.    This is accomplished partially through dynamic protocol translation
  1297.    within the proxy server and partially through special protocol
  1298.    constructions for making outgoing connections.  The PDTP proxy server
  1299.    also listens on port 4045.
  1300.  
  1301.    Requesting a connection through a proxy server is accomplished as
  1302.    follows:
  1303.  
  1304.    Client sends:
  1305.    uint32  Magic number    (0x50786350, "PXCP")
  1306.  
  1307.    Proxy server responds:
  1308.    uint32  Magic number    (0x50786350, "PXCP")
  1309.    uint16  Minimum protocol version
  1310.    uint16  Maximum protocol version
  1311.  
  1312.    Both the minimum and maximum protocol version should currently be 1.
  1313.    In the future these values will be the lowest and highest protocol
  1314.    versions supported by the server.
  1315.  
  1316.    Client responds:
  1317.    uint16  Protocol version
  1318.  
  1319.    The client then selects which protocol version it would like to use.
  1320.    This value must be greater than or equal to the lowest version
  1321.    supported and less than or equal to the highest protocol version
  1322.    supported by the server.  Any values which don't meet this criteria
  1323.    are a protocol violation, and the connection should be terminated by
  1324.    the server.
  1325.  
  1326.    After selecting the protocol version it would like to use, the client
  1327.    sends the address and port of the remote system to connect to:
  1328.  
  1329.    uint32  Host IP address in network byte order
  1330.    uint16  Host port
  1331.  
  1332.    The client may then issue a PDTP or PTPP connection request.  If the
  1333.    connection to the remote system fails the proxy should simply
  1334.    terminate the connection. Otherwise it should connect to the
  1335.    requested system and repeat the PDTP or PTPP connection requests made
  1336.    by the client.
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343. Arcieri                 Expires January 4, 2005                [Page 24]
  1344.  
  1345. Internet-Draft        PDTP Protocol Specification              July 2004
  1346.  
  1347.  
  1348. 6. Acknowledgments
  1349.  
  1350.    Thanks to Marshall Rose for his conversion tools from the RFC-2629
  1351.    [5] XML format to HTML and RFC.
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399. Arcieri                 Expires January 4, 2005                [Page 25]
  1400.  
  1401. Internet-Draft        PDTP Protocol Specification              July 2004
  1402.  
  1403.  
  1404. References
  1405.  
  1406.    [1]  Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April
  1407.         1992.
  1408.  
  1409.    [2]  Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing
  1410.         for Message Authentication", RFC 2104, February 1997.
  1411.  
  1412.    [3]  Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
  1413.         2279, January 1998.
  1414.  
  1415.    [4]  Housley, R., Ford, W., Polk, T. and D. Solo, "Internet X.509
  1416.         Public Key Infrastructure Certificate and CRL Profile", RFC
  1417.         2459, January 1999.
  1418.  
  1419.    [5]  Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June
  1420.         1999.
  1421.  
  1422.    [6]  Davidson, K. and Y. Kawatsura, "Digital Signatures for the v1.0
  1423.         Internet Open Trading Protocol (IOTP)", RFC 2802, April 2000.
  1424.  
  1425.    [7]  Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1 (SHA1)",
  1426.         RFC 3174, September 2001.
  1427.  
  1428.    [8]  National Institute of Standards and Technology, "Digital
  1429.         Signature Standard", FIPS PUB 186-1, December 1998, <http://
  1430.         csrc.nist.gov/fips/fips1861.pdf>.
  1431.  
  1432.  
  1433. Author's Address
  1434.  
  1435.    Anthony Arcieri (editor)
  1436.    PDTP.org
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455. Arcieri                 Expires January 4, 2005                [Page 26]
  1456.  
  1457. Internet-Draft        PDTP Protocol Specification              July 2004
  1458.  
  1459.  
  1460. Appendix A. Path format
  1461.  
  1462.    All paths used by PDTP are canonical Unix format absolute paths,
  1463.    given in the UTF-8 character set (see RFC2279 [3]).
  1464.  
  1465.    Entities in a path are either directories are files.  Every directory
  1466.    name should be postfixed with a '/' character, with a degenerate form
  1467.    of "/" for the root directory.  Therefore, all paths should begin
  1468.    with a '/' character, and when the last entity in a path is a
  1469.    directory, the entire path should also end with a '/' character.
  1470.  
  1471.    (Note: The traditional symbolic directory names '.' for the current
  1472.    directory and '..' for the current directory's parent are not
  1473.    allowed)
  1474.  
  1475.    Files always come at the end of a list of directories.  This
  1476.    directory list must contain at least one element, the root directory
  1477.    '/'.  So, in order to reference a file named 'foo' in the root
  1478.    directory, a client would pass a path of '/foo'.
  1479.  
  1480.    The maximum length of a path is 1024 bytes.  Paths longer than this
  1481.    limit are a protocol violation and an appropriate error should be
  1482.    returned.
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511. Arcieri                 Expires January 4, 2005                [Page 27]
  1512.  
  1513. Internet-Draft        PDTP Protocol Specification              July 2004
  1514.  
  1515.  
  1516. Appendix B. Authorization mechanisms
  1517.  
  1518.    The authorization process by the server sending the authorization
  1519.    magic number:
  1520.  
  1521.    uint32    Magic number    (0x41555448, "AUTH")
  1522.  
  1523.    The client then sends a 16-bit integer indicating the authorization
  1524.    mechanism index to utilize.
  1525.  
  1526.    uint16    Authorization mechanism
  1527.  
  1528.    The server responds:
  1529.  
  1530.    uint8    ACK (0x1) or NACK (0x0)
  1531.  
  1532.    A response of ACK indicates the use of this mechanism is allowed, and
  1533.    NACK rejects it.  If the server responds NACK, the client may either
  1534.    issue another authorization mechanism to try, or disconnect.
  1535.  
  1536.    If the server responds ACK, the specified authorization process is
  1537.    performed. At the end of the process, the server responds ACK (0x1)
  1538.    if the authorization succeeded or NACK (0x0) if it failed.  If an
  1539.    authorization attempt fails, the client may send another
  1540.    authorization mechanism index to attempt, or disconnect if it has
  1541.    exhausted the mechanisms it wishes to use.
  1542.  
  1543.    * Authorization mechanism 0x0: HMAC-SHA1
  1544.  
  1545.    This mechanism utilizes RFC2104 [2] HMAC hashing, using SHA1 (RFC3174
  1546.    [7]) as the underlying hash cipher.  The authentication proceeds as
  1547.    follows:
  1548.  
  1549.    Server sends:
  1550.    string    160-bits (20 bytes) of random challenge data
  1551.  
  1552.    The message to be encrypted is 20 bytes of random challenge data
  1553.    which is sent to the client by the server.  An HMAC-style hash should
  1554.    be applied to this message with an arbitrary length key common to
  1555.    both parties. The authentication proceeds as follows:
  1556.  
  1557.    Client responds:
  1558.    string    160-bits of SHA1 digest resulting from HMAC hashing
  1559.  
  1560.    The server should then check the hash and send ACK or NACK
  1561.    accordingly depending on if the digest matches or not.
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567. Arcieri                 Expires January 4, 2005                [Page 28]
  1568.  
  1569. Internet-Draft        PDTP Protocol Specification              July 2004
  1570.  
  1571.  
  1572. Intellectual Property Statement
  1573.  
  1574.    The IETF takes no position regarding the validity or scope of any
  1575.    intellectual property or other rights that might be claimed to
  1576.    pertain to the implementation or use of the technology described in
  1577.    this document or the extent to which any license under such rights
  1578.    might or might not be available; neither does it represent that it
  1579.    has made any effort to identify any such rights. Information on the
  1580.    IETF's procedures with respect to rights in standards-track and
  1581.    standards-related documentation can be found in BCP-11. Copies of
  1582.    claims of rights made available for publication and any assurances of
  1583.    licenses to be made available, or the result of an attempt made to
  1584.    obtain a general license or permission for the use of such
  1585.    proprietary rights by implementors or users of this specification can
  1586.    be obtained from the IETF Secretariat.
  1587.  
  1588.    The IETF invites any interested party to bring to its attention any
  1589.    copyrights, patents or patent applications, or other proprietary
  1590.    rights which may cover technology that may be required to practice
  1591.    this standard. Please address the information to the IETF Executive
  1592.    Director.
  1593.  
  1594.  
  1595. Full Copyright Statement
  1596.  
  1597.    Copyright (C) The Internet Society (2004). All Rights Reserved.
  1598.  
  1599.    This document and translations of it may be copied and furnished to
  1600.    others, and derivative works that comment on or otherwise explain it
  1601.    or assist in its implementation may be prepared, copied, published
  1602.    and distributed, in whole or in part, without restriction of any
  1603.    kind, provided that the above copyright notice and this paragraph are
  1604.    included on all such copies and derivative works. However, this
  1605.    document itself may not be modified in any way, such as by removing
  1606.    the copyright notice or references to the Internet Society or other
  1607.    Internet organizations, except as needed for the purpose of
  1608.    developing Internet standards in which case the procedures for
  1609.    copyrights defined in the Internet Standards process must be
  1610.    followed, or as required to translate it into languages other than
  1611.    English.
  1612.  
  1613.    The limited permissions granted above are perpetual and will not be
  1614.    revoked by the Internet Society or its successors or assignees.
  1615.  
  1616.    This document and the information contained herein is provided on an
  1617.    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
  1618.    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
  1619.    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
  1620.  
  1621.  
  1622.  
  1623. Arcieri                 Expires January 4, 2005                [Page 29]
  1624.  
  1625. Internet-Draft        PDTP Protocol Specification              July 2004
  1626.  
  1627.  
  1628.    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  1629.    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  1630.  
  1631.  
  1632. Acknowledgment
  1633.  
  1634.    Funding for the RFC Editor function is currently provided by the
  1635.    Internet Society.
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679. Arcieri                 Expires January 4, 2005                [Page 30]
  1680.  
  1681.