home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc1249 < prev    next >
Text File  |  1991-09-04  |  20KB  |  563 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           T. Howes
  8. Request for Comments: 1249                                      M. Smith
  9.                                                               B. Beecher
  10.                                                   University of Michigan
  11.                                                              August 1991
  12.  
  13.  
  14.                       DIXIE Protocol Specification
  15.  
  16. Status of this Memo
  17.  
  18.    This RFC defines a mechanism by which TCP/UDP based clients can
  19.    access OSI Directory Service without the overhead of the ISO
  20.    transport and presentation protocols required to implement full-blown
  21.    DAP.  This memo provides information for the Internet community.  It
  22.    does not specify any standard.  Distribution of this memo is
  23.    unlimited.
  24.  
  25. Table of Contents
  26.  
  27.    1. Introduction ..............................................  2
  28.    1.1 History ..................................................  2
  29.    2. Protocol ..................................................  2
  30.    2.1 Header ...................................................  3
  31.    2.2 Operations ...............................................  4
  32.    2.2.1 Read ...................................................  4
  33.    2.2.1.1 Read Request .........................................  4
  34.    2.2.1.2 Read Reply ...........................................  4
  35.    2.2.2 Search .................................................  5
  36.    2.2.2.1 Search Request .......................................  5
  37.    2.2.2.2 Search Reply .........................................  5
  38.    2.2.3 List ...................................................  5
  39.    2.2.3.1 List Request .........................................  5
  40.    2.2.3.2 List Reply ...........................................  5
  41.    2.2.4 Modify .................................................  5
  42.    2.2.4.1 Modify Request .......................................  6
  43.    2.2.4.2 Modify Reply .........................................  6
  44.    2.2.5 Modify RDN .............................................  6
  45.    2.2.5.1 Modify RDN Request ...................................  6
  46.    2.2.5.2 Modify RDN Reply .....................................  6
  47.    2.2.6 Add ....................................................  6
  48.    2.2.6.1 Add Request ..........................................  7
  49.    2.2.6.2 Add Reply ............................................  7
  50.    2.2.7 Remove .................................................  7
  51.    2.2.7.1 Remove Request .......................................  7
  52.    2.2.7.2 Remove Reply .........................................  7
  53.    2.2.8 Bind ...................................................  7
  54.    2.2.8.1 Bind Request .........................................  7
  55.  
  56.  
  57.  
  58. Howes, Smith, & Beecher                                         [Page 1]
  59.  
  60. RFC 1249                         DIXIE                       August 1991
  61.  
  62.  
  63.    2.2.8.2 Bind Reply ...........................................  8
  64.    2.3 Operation Code Summary ...................................  8
  65.    2.4 Return Code Summary ......................................  8
  66.    3. References ................................................  9
  67.    4. Available Implementations .................................  9
  68.    5. Security Considerations....................................  9
  69.    6. Authors' Addresses ........................................ 10
  70.  
  71. 1.    Introduction
  72.  
  73.    OSI Directory Service defines a powerful mechanism for storing and
  74.    retrieving information about objects, and for arranging those objects
  75.    in a hierarchical structure.  Many types of objects and information
  76.    can be stored in The Directory, including white pages information,
  77.    application information, service information, etc.  The OSI protocol
  78.    defined to allow access to this information is the Directory Access
  79.    Protocol (DAP).  The DAP, being an OSI application-layer program, is
  80.    fairly heavy-weight and requires a substantial amount of computing
  81.    power and coding investment to implement.
  82.  
  83.    The DIXIE protocol is designed for use by smaller hosts (e.g.,
  84.    Macintoshes and PCs) that do not have the computing power or
  85.    necessary software to implement a full OSI protocol stack.  The DIXIE
  86.    protocol is also useful for any Internet application that wants a
  87.    simple interface to X.500 that requires very little coding
  88.    investment.
  89.  
  90.    The basic idea behind DIXIE is the same as that described in RFC 1202
  91.    for the Directory Assistance Protocol.  DIXIE offers both UDP and TCP
  92.    access to The Directory.  While the Directory Assistance Protocol
  93.    exports something of a user interface, DIXIE provides a more direct
  94.    protocol translation.
  95.  
  96. 1.1   History
  97.  
  98.    The DIXIE protocol has evolved over time, slowly growing into the
  99.    protocol described by this document.  Without an understanding of the
  100.    circumstances surrounding this evolution, the wisdom of some of the
  101.    DIXIE design decisions may not be apparent.
  102.  
  103. 2.    Protocol
  104.  
  105.    This section describes the DIXIE protocol in detail.  DIXIE follows a
  106.    client-server request and response paradigm.  Clients send request
  107.    packets to a DIXIE server, and the server sends reply packets in
  108.    return.  Communication may be over UDP or TCP, depending upon the
  109.    needs of the client.  All modification operations (ADD, REMOVE,
  110.    MODIFY, MODIFYRDN) must be performed over a TCP connection, which
  111.  
  112.  
  113.  
  114. Howes, Smith, & Beecher                                         [Page 2]
  115.  
  116. RFC 1249                         DIXIE                       August 1991
  117.  
  118.  
  119.    provides some level of authentication.
  120.  
  121.    Whichever method of communication is used, the general packet format
  122.    is the same.  Each packet consists of a sixteen octet header followed
  123.    by some data.  The format of the header and data for each kind of
  124.    request is described below.
  125.  
  126.    The representation used for all X.500 data passed between the server
  127.    and the client is the QUIPU EDB format.  So, for example, a
  128.    Distinguished Name might look something like "c=US@o=University of
  129.    Michigan".  For a complete description of this format, see volume 5
  130.    of the ISODE Manual.
  131.  
  132.    The DIXIE server listens on port 96 for both UDP packets and TCP
  133.    connections.
  134.  
  135. 2.1   Header
  136.  
  137.    The DIXIE packet header is sixteen octets long.  For requests, the
  138.    header is described by the following:
  139.  
  140.       Start Length    Description
  141.       0       1       An opcode specifying one of the operations
  142.                       described below.  (see section 2.3 for a summary)
  143.       1       2       A request identifier to be included in the reply.
  144.                       This number should be unique to a request.
  145.       3       4       The total length of the request packet, excluding
  146.                       the header.
  147.       7       2       Unused.
  148.       9       1       Options.  Currently, there are only three options.
  149.                       If bit 0 is set, "large" attributes will be
  150.                       included in the response.  The choice of what
  151.                       constitutes large is up to the implementation.
  152.                       If bit 1 is set, the dereference aliases service
  153.                       control will be set for the X.500 operation.  If
  154.                       bit 2 is set, aliases will NOT be dereferenced and
  155.                       searched during a search operation.
  156.       10      1       Protocol version. The current version is 1.
  157.       11      1       For the search operation, this byte specifies the
  158.                       scope of the search.  (see section 2.2.2.1)
  159.       12      2       Timelimit in seconds for the operation.
  160.       14      2       Sizelimit for the operation (search and list).
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170. Howes, Smith, & Beecher                                         [Page 3]
  171.  
  172. RFC 1249                         DIXIE                       August 1991
  173.  
  174.  
  175.    For replies, the header is described by the following:
  176.  
  177.       Start Length    Description
  178.       0       1       A return code specifying either success or
  179.                       describing any error that occurred.  (see
  180.                       section 2.4 for a description of each code)
  181.       1       2       The identifier included in the corresponding
  182.                       request packet.
  183.       3       4       The total length of the response packet, excluding
  184.                       the header.
  185.       7       3       Unused.
  186.       10      1       Protocol version.  The current version is 1.
  187.       11      5       Unused.
  188.  
  189.    All unused fields should be set to null octets and are reserved for
  190.    future expansion.
  191.  
  192. 2.2   Operations
  193.  
  194.    This section describes the DIXIE operations, which closely parallel
  195.    the X.500 DAP operations.
  196.  
  197. 2.2.1 Read
  198.  
  199.    The DIXIE read operation corresponds to an X.500 DAP READ operation.
  200.  
  201. 2.2.1.1 Read Request
  202.  
  203.    The header opcode should be set to 0x01.  The data portion of the
  204.    packet consists of the DN of the entry to read, a null octet, and
  205.    then a null-octet separated list of attributes whose values are to be
  206.    returned from the read.  If no attributes to return are listed, all
  207.    attributes are returned.  The packet is terminated by two null octets
  208.    in a row.
  209.  
  210. 2.2.1.2 Read Reply
  211.  
  212.    The reply data for the read operation consists of the entry read,
  213.    followed by a null octet.  An entry consists of the DN of the entry,
  214.    followed by the octet 0x02, followed by a 0x02-octet separated list
  215.    of attribute values.  An attribute value consists of an attribute
  216.    type, followed by the octet 0x01, followed by a 0x01-octet separated
  217.    list of values.  Each attribute type, attribute value and
  218.    distinguished name has the form defined by the QUIPU EDB format.
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Howes, Smith, & Beecher                                         [Page 4]
  227.  
  228. RFC 1249                         DIXIE                       August 1991
  229.  
  230.  
  231. 2.2.2 Search
  232.  
  233.    The DIXIE search operation corresponds to an X.500 DAP SEARCH
  234.    operation.
  235.  
  236. 2.2.2.1 Search Request
  237.  
  238.    The header opcode should be set to 0x0f.  Octet 11 in the header
  239.    should be set to 0x01, 0x02, or 0x03, for a search scope of base
  240.    object, one level, or whole subtree, respectively.  The data portion
  241.    of the packet consists of the DN of the entry from which to start the
  242.    search, a null octet, a string containing the search filter (dish-
  243.    style), a null-octet, and then a null-octet separated list of
  244.    attributes whose values are to be returned from the search.  If no
  245.    attributes to return are listed, all attributes are returned.  The
  246.    packet is terminated by two null octets in a row.
  247.  
  248. 2.2.2.2 Search Reply
  249.  
  250.    The reply data to the search operation consists of two octets in
  251.    network byte order specifying the number of matches returned.  Next
  252.    comes this number of sequences of the form: one 0x03 octet followed
  253.    by one entry.  Each entry is as described above in section 2.2.1.2.
  254.  
  255. 2.2.3 List
  256.  
  257.    The DIXIE list operation corresponds to an X.500 DAP LIST operation.
  258.  
  259. 2.2.3.1 List Request
  260.  
  261.    The header opcode should be set to 0x10.  The data portion of the
  262.    packet consists of the DN of the entry on which to perform the list,
  263.    followed by a null octet.
  264.  
  265. 2.2.3.2 List Reply
  266.  
  267.    The reply data to the list operation consists of two octets in
  268.    network byte order specifying the number of subordinates returned,
  269.    followed by this number of sequences of the form: one 0x03 octet
  270.    followed by a Relative Distinguished Name of a subordinate.
  271.  
  272. 2.2.4 Modify
  273.  
  274.    The DIXIE modify operation corresponds to an X.500 DAP MODIFY
  275.    operation.
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Howes, Smith, & Beecher                                         [Page 5]
  283.  
  284. RFC 1249                         DIXIE                       August 1991
  285.  
  286.  
  287. 2.2.4.1 Modify Request
  288.  
  289.    The header opcode should be set to 0x02.  The data portion of the
  290.    packet consists of the DN of the entry to modify, followed by a null
  291.    octet, followed by a null-separated list of modify operations to
  292.    perform.  Each modify operation is one of the following:
  293.  
  294.            type            remove attribute type
  295.            type=value      make value the sole value for attribute type
  296.            type+=value     add value to attribute type
  297.            type-=value     remove value from attribute type
  298.  
  299.    The second form will see to it that existing values (if any) are
  300.    deleted before the new ones are added.  The third form will add the
  301.    attribute type if it does not already exist.  Note that the QUIPU EDB
  302.    format, used to specify value, allows multiple values to be specified
  303.    separated by the "&" character.  This operation is only allowed over
  304.    TCP.
  305.  
  306. 2.2.4.2 Modify Reply
  307.  
  308.    There is no reply data for the modify operation.  The only indication
  309.    of success or failure is the return code in the header.
  310.  
  311. 2.2.5 Modify RDN
  312.  
  313.    The DIXIE modify RDN operation corresponds to an X.500 DAP  MODIFYRDN
  314.    operation.
  315.  
  316. 2.2.5.1 Modify RDN Request
  317.  
  318.    The header opcode should be set to 0x13.  The data portion of the
  319.    packet consists of the DN of the entry to modify, followed by a null
  320.    octet, followed by the new RDN the entry should have, followed by a
  321.    final null octet.  The old value of the RDN is never kept as an
  322.    attribute of the entry.  This operation is only allowed over TCP.
  323.  
  324. 2.2.5.2 Modify RDN Reply
  325.  
  326.    There is no reply data to the modify RDN operation.  The only
  327.    indication of success or failure is the return code in the header.
  328.  
  329. 2.2.6 Add
  330.  
  331.    The DIXIE add operation corresponds to an X.500 DAP ADD operation.
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338. Howes, Smith, & Beecher                                         [Page 6]
  339.  
  340. RFC 1249                         DIXIE                       August 1991
  341.  
  342.  
  343. 2.2.6.1 Add Request
  344.  
  345.    The header opcode should be set to 0x11.  The data portion of the
  346.    packet consists of the DN of the entry to add, followed by a null
  347.    octet, followed by a null-separated list of the entry's attributes.
  348.    Each attribute in this list has the form:
  349.  
  350.            type=value
  351.  
  352.    where value can consist of a single value, or multiple values
  353.    separated by the "&" character.  The request is terminated by two
  354.    null octets in a row.  This operation is only allowed over TCP.
  355.  
  356. 2.2.6.2 Add Reply
  357.  
  358.    There is no reply data to the add operation.  The only indication of
  359.    success or failure is the return code in the header.
  360.  
  361. 2.2.7 Remove
  362.  
  363.    The DIXIE remove operation corresponds to an X.500 DAP REMOVE
  364.    operation.
  365.  
  366. 2.2.7.1 Remove Request
  367.  
  368.    The header opcode should be set to 0x12.  The data portion of the
  369.    packet consists of the DN of the entry to remove, followed by a null
  370.    octet.  This operation is only allowed over TCP.
  371.  
  372. 2.2.7.2 Remove Reply
  373.  
  374.    There is no reply data for the remove operation.  The only indication
  375.    of success or failure is the return code in the header.
  376.  
  377. 2.2.8 Bind
  378.  
  379.    The DIXIE bind operation corresponds to an X.500 DAP BIND operation
  380.    using simple authentication as defined in Recommendation X.509.
  381.  
  382. 2.2.8.1 Bind Request
  383.  
  384.    The header opcode should be set to 0x04.  The data portion of the
  385.    packet consists of the DN of the entry as which to bind, followed by
  386.    a null octet, followed by the password of the entry as which to bind,
  387.    followed by a final null octet.  A null DN corresponds causes a bind
  388.    as NULLDN to occur.
  389.  
  390.  
  391.  
  392.  
  393.  
  394. Howes, Smith, & Beecher                                         [Page 7]
  395.  
  396. RFC 1249                         DIXIE                       August 1991
  397.  
  398.  
  399. 2.2.8.2 Bind Reply
  400.  
  401.    The format of the bind reply packet depends on whether the operation
  402.    was invoked over TCP or UDP.  If the operation was invoked over TCP,
  403.    there is no reply data.  Success or failure of the operation is
  404.    indicated by the return code in the packet header.
  405.  
  406.    If the bind operation was invoked over UDP, the data portion of the
  407.    reply packet consists of an Internet address in standard dot
  408.    notation, followed by a 0x01 octet, followed by a decimal number (in
  409.    text form), followed by a null octet.  The address and number should
  410.    be taken to be the IP address and port number to which the client
  411.    should connect to obtain an authenticated TCP connection, bound as
  412.    the entity specified in the request packet.
  413.  
  414. 2.3 Operation Code Summary
  415.  
  416.    This section describes the  possible  values  for  the  DIXIE  header
  417.    operation code.  There are currently 8 possible values:
  418.  
  419.       0x01    Read
  420.       0x02    Modify
  421.       0x04    Bind
  422.       0x0f    Search
  423.       0x10    List
  424.       0x11    Add
  425.       0x12    Remove
  426.       0x13    Modify RDN
  427.  
  428. 2.4 Return Code Summary
  429.  
  430.    This section describes the possible values for the the DIXIE header
  431.    return code.  There are currently 17 possible values:
  432.  
  433.       0x01    The request was successful.
  434.       0x02    The search did not find any matches.
  435.       0x03    Some unknown, generic DIXIE error has occurred.
  436.       0x04    The DIXIE opcode was not recognized by the DIXIE server.
  437.       0x05    Insufficient access to perform a modification.
  438.       0x06    A malformed DN was supplied.
  439.       0x07    Some time limit or size limit was reached.
  440.               Partial results will be returned.
  441.       0x08    A modify was attempted before a bind.
  442.       0x09    A fragment requested was not found.
  443.       0x0a    An attribute type specified is invalid.
  444.       0x0b    An attribute specified does not exist in the entry.
  445.       0x0c    An attribute value specification is invalid.
  446.       0x0d    An attribute value does not exist (as for removal of the
  447.  
  448.  
  449.  
  450. Howes, Smith, & Beecher                                         [Page 8]
  451.  
  452. RFC 1249                         DIXIE                       August 1991
  453.  
  454.  
  455.               value).
  456.       0x0e    A modification of an entry's RDN was attempted via a modify
  457.               operation.  This is not allowed (use modrdn instead).
  458.       0x0f    A supplied DN references an invalid portion of the tree.
  459.       0x10    The DSA has passed back a referral to another DSA (as for a
  460.               modification to a non-local entry), and the DIXIE server was
  461.               unable to follow it.
  462.       0x11    The DSA is down or unreachable.
  463.  
  464. 3.    References
  465.  
  466.    [1] Information Processing - Open Systems Interconnection - The
  467.        Directory, International Organization for Standardization,
  468.        International Standard 9594, 1988.
  469.  
  470.    [2] Kille, S., Robbins, C., Roe, M., and A. Turland, "The ISO
  471.        Development Environment: User's Manual", Volume 5: QUIPU,
  472.        Performance Systems International, January 1990.
  473.  
  474.    [3] Rose, M., "Directory Assistance Service", RFC 1202, Performance
  475.        Systems International, February 1991.
  476.  
  477. 4.    Available Implementations
  478.  
  479.        This section is not meant as an endorsement of any
  480.        implementation, it is provided merely as information for the
  481.        Internet community.  A full Un*x-based implementation of the
  482.        DIXIE protocol in the form of a DIXIE server and DIXIE
  483.        application library is freely available for anonymous FTP from
  484.        the host terminator.cc.umich.edu in the ~ftp/x500 directory.
  485.        Un*x and Macintosh clients that use the DIXIE protocol have also
  486.        been implemented and are available from the same location.
  487.  
  488.        There is also a discussion list for DIXIE-related topics called
  489.        dixie@terminator.cc.umich.edu.  To join, send mail to dixie-
  490.        request@terminator.cc.umich.edu.
  491.  
  492. 5.    Security Considerations
  493.  
  494.    Security issues are not discussed in this memo.
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Howes, Smith, & Beecher                                         [Page 9]
  507.  
  508. RFC 1249                         DIXIE                       August 1991
  509.  
  510.  
  511. 6.    Authors' Addresses
  512.  
  513.    Tim Howes
  514.    University of Michigan
  515.    Information Technology Division
  516.    535 West William St.
  517.    Ann Arbor, MI 48103-4943
  518.  
  519.    Phone: +1 313 764-2278
  520.    EMail: tim@umich.edu
  521.  
  522.  
  523.    Mark Smith
  524.    University of Michigan
  525.    Information Technology Division
  526.    535 West William St.
  527.    Ann Arbor, MI 48103-4943
  528.  
  529.    Phone: +1 313 764-2277
  530.    EMail: mcs@umich.edu
  531.  
  532.  
  533.    Bryan Beecher
  534.    University of Michigan
  535.    Information Technology Division
  536.    535 West William St.
  537.    Ann Arbor, MI 48103-4943
  538.  
  539.    Phone: +1 313 764-4050
  540.    EMail: bryan@umich.edu
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Howes, Smith, & Beecher                                        [Page 10]
  563.