home *** CD-ROM | disk | FTP | other *** search
/ Unix System Administration Handbook 1997 October / usah_oct97.iso / rfc / 1200s / rfc1202.txt < prev    next >
Text File  |  1991-02-06  |  21KB  |  619 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                            M. Rose
  8. Request for Comments: 1202       Performance Systems International, Inc.
  9.                                                            February 1991
  10.  
  11.  
  12.                       Directory Assistance Service
  13.  
  14. Status of this Memo
  15.  
  16.    This document defines a mechanism by which a user-interface may
  17.    access a textual DAP-like interface over a TCP/IP connection.  This
  18.    is a local mechanism.  This memo provides information for the
  19.    Internet community.  It does not specify any standard.  Distribution
  20.    of this memo is unlimited.
  21.  
  22. Table of Contents
  23.  
  24.    1. Introduction ..........................................   1
  25.    1.1 An Aside ............................................    3
  26.    2. Protocol ..............................................   3
  27.    2.1 Control Connection ..................................    4
  28.    2.1.1 Initialization ....................................    4
  29.    2.1.2 Transactions ......................................    4
  30.    2.1.2.1 INTR command ....................................    4
  31.    2.1.2.2 STAT command ....................................    5
  32.    2.1.2.3 QUIT command ....................................    5
  33.    2.2 Data Connection .....................................    5
  34.    2.2.1 Transactions ......................................    5
  35.    2.2.2 Responses .........................................    6
  36.    2.2.2.1 Numeric Responses ...............................    6
  37.    2.2.2.2 'm' Response ....................................    6
  38.    2.2.2.3 'y' Response ....................................    6
  39.    2.2.2.4 'p' Response ....................................    7
  40.    2.2.2.5 'e' Response ....................................    7
  41.    2.2.2.6 'l' Response ....................................    7
  42.    2.2.2.7 'd' Response ....................................    8
  43.    2.2.2.8 'P' Response ....................................    8
  44.    3. Example Interaction ...................................   9
  45.    4. References ............................................  10
  46.    5. Security Considerations...............................   11
  47.    6. Author's Address......................................   11
  48.  
  49. 1.  Introduction
  50.  
  51.    The OSI Directory [1] provides a powerful infrastructure for the
  52.    retrieval of information objects.  This infrastructure can be used to
  53.    support, e.g., white pages applications, application entity lookup,
  54.    and so on.
  55.  
  56.  
  57.  
  58. Rose                                                            [Page 1]
  59.  
  60. RFC 1202              Directory Assistance Service         February 1991
  61.  
  62.  
  63.    The Directory service is provided to applications through the
  64.    Directory Access Protocol (DAP), which binds a Directory User Agent
  65.    (DUA) to a Directory System Agent (DSA).
  66.  
  67.                                         | Directory Service
  68.                                         |    provided via DAP
  69.                                         |
  70.                +-----------+            |            +-----------+
  71.                |           |            |            |           |
  72.                |    DUA    | <----------+----------> |    DSA    |
  73.                |           |            |            |           |
  74.                +-----------+            |            +-----------+
  75.                                         |
  76.                          Directory User |
  77.  
  78.    The DAP is an OSI application layer protocol which uses the rich OSI
  79.    upper-layer infrastructure.  Unfortunately, the coding investment to
  80.    implement the DAP is significant.  As such, it is difficult to host
  81.    applications using the Directory on smaller workstations and personal
  82.    computers.
  83.  
  84.    This memo details a local mechanism which has been successfully used
  85.    to separate the functionality of the DAP from the complexity of
  86.    implementing the DAP.  That is, a split-DUA model is used: the DAP is
  87.    implemented on an entity (the "Directory Assistant"), which resides
  88.    on a capable workstation or mainframe and exports a simpler
  89.    interface, the "Directory Assistance" (DA) protocol, to other end-
  90.    systems where the user-interface resides, termed the DA-client.
  91.  
  92.    Since this mechanism provides assistance to applications wishing to
  93.    access the Directory, it is termed the "Directory Assistance" (DA)
  94.    service:
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Rose                                                            [Page 2]
  115.  
  116. RFC 1202              Directory Assistance Service         February 1991
  117.  
  118.  
  119.                                         | Directory Service
  120.                  split-DUA              |    provided via DAP
  121.                                         |
  122.                +-----------+            |            +-----------+
  123.                |           |            |            |           |
  124.                | Directory | <----------+----------> |    DSA    |
  125.                | Assistant |            |            |           |
  126.                |           |            |            +-----------+
  127.                +-----------+            |
  128.                     /|\                 |
  129.                      |                  |
  130.                      | DA-service       |
  131.                      |   provide via    |
  132.                      |   DA-protocol    |
  133.                      |                  |
  134.                ------+------            |
  135.                      |                  |
  136.                      |                  |
  137.                      |                  |
  138.                      |                  |
  139.                      |                  |
  140.                     \|/                 |
  141.                +-----------+            |
  142.                |           |            |
  143.                | DA-client |            |
  144.                |           |            |
  145.                +-----------+            |
  146.                                         |
  147.                          Directory User |
  148.  
  149.  
  150. 1.1.  An Aside
  151.  
  152.    This memo documents an already existing protocol, which was
  153.    originally used to provide a split-DUA model within the same host.
  154.    In the absence of detailed historical and implementational
  155.    understanding, some of the mechanisms described may not appear
  156.    intuitive.
  157.  
  158. 2.  Protocol
  159.  
  160.    The DA service operates using two TCP connections: a control
  161.    connection, and a data connection.  The control connection defines
  162.    the lifetime of an instance of the DA service; throughout this
  163.    lifetime, several data connections may be established.  However, at
  164.    any given instant, between zero and one data connections will be in
  165.    progress.
  166.  
  167.  
  168.  
  169.  
  170. Rose                                                            [Page 3]
  171.  
  172. RFC 1202              Directory Assistance Service         February 1991
  173.  
  174.  
  175.    The DA service is provided by the "Directory Assistant", which
  176.    consists of two entities: a DA-server, which manages the control
  177.    connection; and, a DAP-listener, which responds to commands on the
  178.    data connection.  The DA-server oversees the behavior of the DAP-
  179.    listener.
  180.  
  181. 2.1.  Control Connection
  182.  
  183.    Data sent over the control connection consists of a series of
  184.    transactions.  NVT-ASCII is used to express these transactions.  Each
  185.    transaction consists of the client sending a directive--a line of
  186.    text terminated by CR-LF; the DA-server returns a response--a line of
  187.    text terminated by CR-LF.  All responses from a DA-server start with
  188.    either "+OK" or "-ERR" depending on whether the transaction was
  189.    successful.
  190.  
  191. 2.1.1.  Initialization
  192.  
  193.    A DA-server listens on TCP port 411 for incoming connections.  Upon
  194.    establishing a control connection, the DA-server returns a response
  195.    indicating whether the service has been started.  If successful, the
  196.    response contains an IP-address and a TCP port, expressed in NVT-
  197.    ASCII, and separated by one or more instances of the space character.
  198.    This information corresponds to the TCP-endpoint that the DAP-
  199.    listener will use for the data connection.
  200.  
  201.    Note that the DA-server and DAP-listener need not reside at the same
  202.    IP-address.  In the future, DA-servers may employ a internal protocol
  203.    for load-balancing purposes.
  204.  
  205.    If the DA service can not be started, an error response is returned
  206.    and the control connection is closed.
  207.  
  208.  
  209. 2.1.2.  Transactions
  210.  
  211.    All transactions with the DA-server consist of a command followed by
  212.    zero or more arguments, separated by the space character.
  213.  
  214. 2.1.2.1.  INTR command
  215.  
  216.    The INTR command takes no arguments.
  217.  
  218.    The INTR command is used to interrupt any DAP transaction
  219.    currently in progress.
  220.  
  221.    The INTR command always returns success.
  222.  
  223.  
  224.  
  225.  
  226. Rose                                                            [Page 4]
  227.  
  228. RFC 1202              Directory Assistance Service         February 1991
  229.  
  230.  
  231. 2.1.2.2.  STAT command
  232.  
  233.    The STAT command takes no arguments.
  234.  
  235.    The STAT command is used to verify that the DAP-listener is
  236.    available.
  237.  
  238.    The STAT command returns success only if the DAP-listener is
  239.    still active.
  240.  
  241. 2.1.2.3.  QUIT command
  242.  
  243.    The QUIT command takes no arguments.
  244.  
  245.    The QUIT command is used to terminate the DA service.
  246.  
  247.    The QUIT command always returns success.
  248.  
  249. 2.2.  Data Connection
  250.  
  251.    Data sent over a data connection consists of a single DAP-
  252.    transaction.  NVT-ASCII is used to express these transactions.  Each
  253.    transaction consists of the client sending a command--a line of text
  254.    terminated by the LF-character; the DAP-listener returns zero or more
  255.    responses, each with a specific termination sequence.  All responses
  256.    from a DAP-listener start with a single identifying character.  If
  257.    the character is a digit (0-9), then the termination sequence
  258.    consists of a closing the data connection; otherwise, if the
  259.    character is a lower-case letter (a-z), then the response is
  260.    interactive and is terminated by the LF-character.
  261.  
  262. 2.2.1.  Transactions
  263.  
  264.    All transactions with the DAP-listener consist of a command followed
  265.    by zero or more arguments, separated by the space character.
  266.    Double-quotes may be used to prevent separation of tokens.
  267.  
  268.    The command set is taken from the DISH program:
  269.  
  270.                add         add a new entry
  271.                bind        connect to the Directory
  272.                compare     compare entry's attribute
  273.                delete      delete an entry
  274.                fred        back-end to FrED
  275.                list        list children
  276.                modify      modify an existing entry
  277.                modifyrdn   modify an entry's name
  278.                moveto      move to a position
  279.  
  280.  
  281.  
  282. Rose                                                            [Page 5]
  283.  
  284. RFC 1202              Directory Assistance Service         February 1991
  285.  
  286.  
  287.                search      search for an object
  288.                showentry   show an entry
  289.                showname    show an entry's name
  290.                squid       status of dish
  291.                unbind      disconnect from the Directory
  292.  
  293.    See [2] for a complete list of commands and arguments.
  294.  
  295.    Note that commands and arguments are in lower-case, and may
  296.    abbreviated to any unique prefix.
  297.  
  298. 2.2.2.  Responses
  299.  
  300.    There are two kinds of responses: numeric-responses, which consist of
  301.    arbitrary text; and, letter-responses, which consist of brief text,
  302.    and expect further interaction from the client.
  303.  
  304. 2.2.2.1.  Numeric Responses
  305.  
  306.    If the response is '1', then the DAP-transaction terminated normally;
  307.    if the response is '2', then the DAP-transaction failed; if the
  308.    response is '3', then the DAP-transaction was a search returning more
  309.    than one result and one of the -hitone or -list option was selected
  310.    for the search; if the response is '4', then the DAP-transaction
  311.    terminated normally and the remainder of this line consists of the
  312.    name of an entry (see the 'd' Response below); if the response is
  313.    '5', then all children of an entry were found by the DAP-transaction.
  314.    Once the response is completely sent, the DAP-listener closes the
  315.    data connection.
  316.  
  317.    Note that although numeric responses utilize ASCII, they are not
  318.    NVT-ASCII; in particular, the LF-character is used to indicate end-
  319.    of-line, rather than the CR-LF line termination sequence of NVT-
  320.    ASCII.
  321.  
  322. 2.2.2.2.  'm' Response
  323.  
  324.    The 'm' response contains a one-line message which should be
  325.    presented to the user.
  326.  
  327.    At this point, the client returns a response consisting of 'm'
  328.    followed by the LF-character.  The client should then continue
  329.    reading from the existing data connection.
  330.  
  331. 2.2.2.3.  'y' Response
  332.  
  333.    The 'y' response contains a yes/no question which should be presented
  334.    to the user.  After querying the user, the response (either 'y' or
  335.  
  336.  
  337.  
  338. Rose                                                            [Page 6]
  339.  
  340. RFC 1202              Directory Assistance Service         February 1991
  341.  
  342.  
  343.    'n'), followed by the LF-character, should be sent to the DAP-
  344.    listener.  The client should then continue reading from the existing
  345.    data connection.
  346.  
  347. 2.2.2.4.  'p' Response
  348.  
  349.    The 'p' response contains a password-prompt which should be presented
  350.    to the user.  After querying the user, the client returns a response
  351.    consisting of 'p' followed by the password supplied by the user
  352.    followed by the LF-character.  The client should then continue
  353.    reading from the existing data connection.
  354.  
  355. 2.2.2.5.  'e' Response
  356.  
  357.    The 'e' response is used to ask the user to edit some text.
  358.    Following the 'e' character is a decimal number in ASCII followed by
  359.    the LF-character, indicating the number of octets that should be
  360.    presented to the user for editing (these octets may include LF-
  361.    characters).
  362.  
  363.    At this point, the client returns a response consisting of a single
  364.    character followed by a LF-character.  If the character is 'e', the
  365.    edit is aborted (e.g., the text is too large), and the client should
  366.    then continue reading from the existing data connection.
  367.  
  368.    Otherwise, the DAP-listener sends the indicated number of octets
  369.    corresponding to the buffer that the user is to edit.  After the user
  370.    edits the buffer, one of two responses should be sent.
  371.  
  372.    If the user aborted the edit, the response sent to the DAP-listener
  373.    is a single character 'e', followed by the LF-character.
  374.  
  375.    Otherwise, the response consists of any single character other than
  376.    indicating the number of octets immediately following that resulted
  377.    from the user-edit.
  378.  
  379.    Regardless of the outcome, the client should then continue reading
  380.    from the existing data connection.
  381.  
  382. 2.2.2.6.  'l' Response
  383.  
  384.    The 'l' response contains an entry for a selection list to be
  385.    presented to the user.  The form of this entry consists of two
  386.    strings separated by the '$' character, and terminated by the LF-
  387.    character.  The first string is a user-friendly name, suitable for
  388.    display to the user; the second string is a fully-qualified
  389.    Distinguished Name in textual format.
  390.  
  391.  
  392.  
  393.  
  394. Rose                                                            [Page 7]
  395.  
  396. RFC 1202              Directory Assistance Service         February 1991
  397.  
  398.  
  399.    At this point, the client returns a response consisting of 'l'
  400.    followed by the LF-character.
  401.  
  402.    The client should continue to accumulate selection entries until an
  403.    LF-character.
  404.  
  405.    At this point, the user should be asked to select one or more of the
  406.    selection entries.  After this selection, the client sends back a
  407.    response consisting of 'L' followed by one or more decimal numbers in
  408.    ASCII followed by the LF-character.  The numbers are separated by
  409.    spaces, and correspond to the entries selected by the user.  (The
  410.    entry corresponding to the first 'l' response is numbered 1, etc.)
  411.  
  412.    The client should then continue reading from the existing data
  413.    connection.
  414.  
  415. 2.2.2.7.  'd' Response
  416.  
  417.    The 'd' response contains a name that the client may be interested
  418.    in.  The form of this name consists of two strings separated by the
  419.    '$' character, and terminated by the LF-character.  The first string
  420.    is a user-friendly name, suitable for display to the user; the second
  421.    string is a fully-qualified Distinguished Name in textual format.
  422.  
  423.    At this point, the client returns a response consisting of 'd'
  424.    followed by the LF-character.  The client should then continue
  425.    reading from the existing data connection.
  426.  
  427. 2.2.2.8.  'P' Response
  428.  
  429.    The 'P' response is used to transmit a picture to the client.
  430.    Following the 'P' character is a decimal number in ASCII followed by
  431.    a name and then the LF-character.  The decimal number indicates the
  432.    size of the picture.  The name contains three strings separated by
  433.    the '$' character.  The first string is the name of the attribute
  434.    corresponding to the picture, in textual format; the second string is
  435.    a user-friendly name, suitable for display to the user; and, the
  436.    third string is a fully-qualified DistingiushedName in textual
  437.    format.
  438.  
  439.    At this point, the client returns a response consisting of a single
  440.    character followed by a LF-character.  If the character is 'P', the
  441.    picture will not be sent (e.g., the image is too large), and the
  442.    client should then continue reading from the existing data
  443.    connection.
  444.  
  445.    Otherwise, the DAP-listener sends the indicated number of octets
  446.    corresponding to the picture.  The picture is encoded using the PBM
  447.  
  448.  
  449.  
  450. Rose                                                            [Page 8]
  451.  
  452. RFC 1202              Directory Assistance Service         February 1991
  453.  
  454.  
  455.    format from the PBMPLUS package.
  456.  
  457.    Regardless of the outcome, the client should then continue reading
  458.    from the existing data connection.
  459.  
  460. 3.  Example Interaction
  461.  
  462.    In the text that follows, "S:" refers to the DA-server, "L:" refers
  463.    to the DAP-listener, "C:" refers to the client talking to the DA-
  464.    server, and, "I:" refers to the client talking to the DAP-listener.
  465.  
  466.           S: <wait for connection on TCP port 411>
  467.  
  468.           C: <open connection to DA-server>
  469.           L: <wait for connections>
  470.           S: +OK 192.33.4.21 32867
  471.  
  472.           I: <open connection to DAP-listener>
  473.           I: bind -simple -user "@c=US@cn=Manager"
  474.           L: pc=US@cn=Manager
  475.           -- client asks user for password for "c=US@cn=Manager"
  476.           I: psecret
  477.           L: <closes connection, signaling success but no response>
  478.  
  479.           -- since response was null, client verifies that DAP-listener
  480.           -- is still operating...
  481.           C: STAT
  482.           S: +OK
  483.  
  484.           I: <open connection to DAP-listener>
  485.           I: fred -expand "@"
  486.           L: 5
  487.              North America$l=North America
  488.              US$c=US
  489.              ...
  490.           L: <closes connection>
  491.  
  492.           I: <open connection to DAP-listener>
  493.           I: fred -ufn rose,psi,us
  494.           L: 1
  495.              <followed by much data>
  496.           L: <closes connection>
  497.  
  498.           I: <open connection to DAP-listener>
  499.           I: fred -ufn -list,rose,ps,us
  500.           L: lHewlett-Packard, US$c=US@o=Hewlett-Packard
  501.           I: l
  502.           L: lPerformance Systems International, US$c=US@o=Performance...
  503.  
  504.  
  505.  
  506. Rose                                                            [Page 9]
  507.  
  508. RFC 1202              Directory Assistance Service         February 1991
  509.  
  510.  
  511.           I: l
  512.           L: lRutgers University, US$c=US@o=Rutgers University
  513.           I: l
  514.           L: Lps
  515.           -- client presents selection list to user asking to select
  516.           -- matches for 'ps', user selects the 2nd
  517.           I: L 2
  518.           L: dManager, US$c=US@cn=Manager
  519.           I: d
  520.           L: 4Marshall Rose, ...$c=US@o=Performance...
  521.              <followed by much data>
  522.           L: <closes connection>
  523.  
  524.           I: <open connection to DAP-listener>
  525.           I: fred -ufn -list,schoffstall,ps,us
  526.           L: 33 matches found.
  527.           Martin Schoffstall, ...$c=US@o=Performance...
  528.           Marvin Schoffstall, ...$c=US@o=Performance...
  529.           Steve Schoffstall, ...$c=US@o=Performance...
  530.           L: <closes connection>
  531.  
  532.           C: QUIT
  533.           L: <stop listening for connections>
  534.           S: +OK
  535.           C: <close connection>
  536.  
  537.           S: <wait for next connection>
  538.  
  539. 4.  References
  540.  
  541.    [1] Information Processing - Open Systems Interconnection - The
  542.        Directory, International Organization for Standardization.
  543.        International Standard 9594, (1988).
  544.  
  545.    [2] Kille, S., Robbins, C., Roe, M., and A. Turland, "The ISO
  546.        Development Environment: User's Manual", Volume 5: QUIPU,
  547.        Performance Systems International, January 1990.
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Rose                                                           [Page 10]
  563.  
  564. RFC 1202              Directory Assistance Service         February 1991
  565.  
  566.  
  567. 5.  Security Considerations
  568.  
  569.    Security considerations are not discussed in this memo.
  570.  
  571. 6.  Author's Address
  572.  
  573.    Marshall T. Rose
  574.    PSI, Inc.
  575.    PSI California Office
  576.    P.O. Box 391776
  577.    Mountain View, CA 94039
  578.  
  579.    Phone: (415) 961-3380
  580.  
  581.    EMail: mrose@psi.com
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618. Rose                                                           [Page 11]
  619.