home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / rfc / rfc1777 < prev    next >
Text File  |  1995-09-15  |  45KB  |  1,236 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           W. Yeong
  8. Request for Comments: 1777             Performance Systems International
  9. Obsoletes: 1487                                                 T. Howes
  10. Category: Standards Track                         University of Michigan
  11.                                                                 S. Kille
  12.                                                         ISODE Consortium
  13.                                                               March 1995
  14.  
  15.  
  16.                  Lightweight Directory Access Protocol
  17.  
  18. Status of this Memo
  19.  
  20.    This document specifies an Internet standards track protocol for the
  21.    Internet community, and requests discussion and suggestions for
  22.    improvements.  Please refer to the current edition of the "Internet
  23.    Official Protocol Standards" (STD 1) for the standardization state
  24.    and status of this protocol.  Distribution of this memo is unlimited.
  25.  
  26. Abstract
  27.  
  28.    The protocol described in this document is designed to provide access
  29.    to the X.500 Directory while not incurring the resource requirements
  30.    of the Directory Access Protocol (DAP). This protocol is specifically
  31.    targeted at simple management applications and browser applications
  32.    that provide simple read/write interactive access to the X.500
  33.    Directory, and is intended to be a complement to the DAP itself.
  34.  
  35.    Key aspects of LDAP are:
  36.  
  37.    - Protocol elements are carried directly over TCP or other transport,
  38.      bypassing much of the session/presentation overhead.
  39.  
  40.    - Many protocol data elements are encoding as ordinary strings (e.g.,
  41.      Distinguished Names).
  42.  
  43.    - A lightweight BER encoding is used to encode all protocol elements.
  44.  
  45. 1.  History
  46.  
  47.    The tremendous interest in X.500 [1,2] technology in the Internet has
  48.    lead to efforts to reduce the high "cost of entry" associated with
  49.    use of the technology, such as the Directory Assistance Service [3]
  50.    and DIXIE [4]. While efforts such as these have met with success,
  51.    they have been solutions based on particular implementations and as
  52.    such have limited applicability.  This document continues the efforts
  53.    to define Directory protocol alternatives but departs from previous
  54.    efforts in that it consciously avoids dependence on particular
  55.  
  56.  
  57.  
  58. Yeong, Howes & Kille                                            [Page 1]
  59.  
  60. RFC 1777                          LDAP                        March 1995
  61.  
  62.  
  63.    implementations.
  64.  
  65. 2.  Protocol Model
  66.  
  67.    The general model adopted by this protocol is one of clients
  68.    performing protocol operations against servers. In this model, this
  69.    is accomplished by a client transmitting a protocol request
  70.    describing the operation to be performed to a server, which is then
  71.    responsible for performing the necessary operations on the Directory.
  72.    Upon completion of the necessary operations, the server returns a
  73.    response containing any results or errors to the requesting client.
  74.    In keeping with the goal of easing the costs associated with use of
  75.    the Directory, it is an objective of this protocol to minimize the
  76.    complexity of clients so as to facilitate widespread deployment of
  77.    applications capable of utilizing the Directory.
  78.  
  79.    Note that, although servers are required to return responses whenever
  80.    such responses are defined in the protocol, there is no requirement
  81.    for synchronous behavior on the part of either client or server
  82.    implementations: requests and responses for multiple operations may
  83.    be exchanged by client and servers in any order, as long as clients
  84.    eventually receive a response for every request that requires one.
  85.  
  86.    Consistent with the model of servers performing protocol operations
  87.    on behalf of clients, it is also to be noted that protocol servers
  88.    are expected to handle referrals without resorting to the return of
  89.    such referrals to the client. This protocol makes no provisions for
  90.    the return of referrals to clients, as the model is one of servers
  91.    ensuring the performance of all necessary operations in the
  92.    Directory, with only final results or errors being returned by
  93.    servers to clients.
  94.  
  95.    Note that this protocol can be mapped to a strict subset of the
  96.    directory abstract service, so it can be cleanly provided by the DAP.
  97.  
  98. 3.  Mapping Onto Transport Services
  99.  
  100.    This protocol is designed to run over connection-oriented, reliable
  101.    transports, with all 8 bits in an octet being significant in the data
  102.    stream.  Specifications for two underlying services are defined here,
  103.    though others are also possible.
  104.  
  105. 3.1.  Transmission Control Protocol (TCP)
  106.  
  107.    The LDAPMessage PDUs are mapped directly onto the TCP bytestream.
  108.    Server implementations running over the TCP should provide a protocol
  109.    listener on port 389.
  110.  
  111.  
  112.  
  113.  
  114. Yeong, Howes & Kille                                            [Page 2]
  115.  
  116. RFC 1777                          LDAP                        March 1995
  117.  
  118.  
  119. 3.2.  Connection Oriented Transport Service (COTS)
  120.  
  121.    The connection is established.  No special use of T-Connect is made.
  122.    Each LDAPMessage PDU is mapped directly onto T-Data.
  123.  
  124. 4.  Elements of Protocol
  125.  
  126.    For the purposes of protocol exchanges, all protocol operations are
  127.    encapsulated in a common envelope, the LDAPMessage, which is defined
  128.    as follows:
  129.  
  130.      LDAPMessage ::=
  131.          SEQUENCE {
  132.               messageID      MessageID,
  133.               protocolOp     CHOICE {
  134.                                   bindRequest         BindRequest,
  135.                                   bindResponse        BindResponse,
  136.                                   unbindRequest       UnbindRequest,
  137.                                   searchRequest       SearchRequest,
  138.                                   searchResponse      SearchResponse,
  139.                                   modifyRequest       ModifyRequest,
  140.                                   modifyResponse      ModifyResponse,
  141.                                   addRequest          AddRequest,
  142.                                   addResponse         AddResponse,
  143.                                   delRequest          DelRequest,
  144.                                   delResponse         DelResponse,
  145.                                   modifyRDNRequest    ModifyRDNRequest,
  146.                                   modifyRDNResponse   ModifyRDNResponse,
  147.                                   compareDNRequest    CompareRequest,
  148.                                   compareDNResponse   CompareResponse,
  149.                                   abandonRequest      AbandonRequest
  150.                              }
  151.          }
  152.  
  153.      MessageID ::= INTEGER (0 .. maxInt)
  154.  
  155.    The function of the LDAPMessage is to provide an envelope containing
  156.    common fields required in all protocol exchanges. At this time the
  157.    only common field is a message ID, which is required to have a value
  158.    different from the values of any other requests outstanding in the
  159.    LDAP session of which this message is a part.
  160.  
  161.    The message ID value must be echoed in all LDAPMessage envelopes
  162.    encapsulting responses corresponding to the request contained in the
  163.    LDAPMessage in which the message ID value was originally used.
  164.  
  165.    In addition to the LDAPMessage defined above, the following
  166.    definitions are also used in defining protocol operations:
  167.  
  168.  
  169.  
  170. Yeong, Howes & Kille                                            [Page 3]
  171.  
  172. RFC 1777                          LDAP                        March 1995
  173.  
  174.  
  175.      LDAPString ::= OCTET STRING
  176.  
  177.    The LDAPString is a notational convenience to indicate that, although
  178.    strings of LDAPString type encode as OCTET STRING types, the legal
  179.    character set in such strings is limited to the IA5 character set.
  180.  
  181.      LDAPDN ::= LDAPString
  182.  
  183.      RelativeLDAPDN ::= LDAPString
  184.  
  185.    An LDAPDN and a RelativeLDAPDN are respectively defined to be the
  186.    representation of a Distinguished Name and a Relative Distinguished
  187.    Name after encoding according to the specification in [5], such that
  188.  
  189.      <distinguished-name> ::= <name>
  190.  
  191.      <relative-distinguished-name> ::= <name-component>
  192.  
  193.    where <name> and <name-component> are as defined in [5].
  194.  
  195.      AttributeValueAssertion ::=
  196.          SEQUENCE {
  197.               attributeType       AttributeType,
  198.               attributeValue      AttributeValue
  199.          }
  200.  
  201.    The AttributeValueAssertion type definition  is similar to the one in
  202.    the X.500 Directory standards.
  203.  
  204.      AttributeType ::= LDAPString
  205.  
  206.      AttributeValue ::= OCTET STRING
  207.  
  208.    An AttributeType value takes on as its value the textual string
  209.    associated with that AttributeType in the X.500 Directory standards.
  210.    For example, the AttributeType 'organizationName' with object
  211.    identifier 2.5.4.10 is represented as an AttributeType in this
  212.    protocol by the string "organizationName".  In the event that a
  213.    protocol implementation encounters an Attribute Type with which it
  214.    cannot associate a textual string, an ASCII string encoding of the
  215.    object identifier associated with the Attribute Type may be
  216.    subsitituted.  For example, the organizationName AttributeType may be
  217.    represented by the ASCII string "2.5.4.10" if a protocol
  218.    implementation is unable to associate the string "organizationName"
  219.    with it.
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Yeong, Howes & Kille                                            [Page 4]
  227.  
  228. RFC 1777                          LDAP                        March 1995
  229.  
  230.  
  231.    A field of type AttributeValue takes on as its value an octet string
  232.    encoding of a Directory AttributeValue type. The definition of these
  233.    string encodings for different Directory AttributeValue types may be
  234.    found in companions to this document that define the encodings of
  235.    various attribute syntaxes such as [6].
  236.  
  237.      LDAPResult ::=
  238.          SEQUENCE {
  239.              resultCode    ENUMERATED {
  240.                              success                      (0),
  241.                              operationsError              (1),
  242.                              protocolError                (2),
  243.                              timeLimitExceeded            (3),
  244.                              sizeLimitExceeded            (4),
  245.                              compareFalse                 (5),
  246.                              compareTrue                  (6),
  247.                              authMethodNotSupported       (7),
  248.                              strongAuthRequired           (8),
  249.                              noSuchAttribute              (16),
  250.                              undefinedAttributeType       (17),
  251.                              inappropriateMatching        (18),
  252.                              constraintViolation          (19),
  253.                              attributeOrValueExists       (20),
  254.                              invalidAttributeSyntax       (21),
  255.                              noSuchObject                 (32),
  256.                              aliasProblem                 (33),
  257.                              invalidDNSyntax              (34),
  258.                              isLeaf                       (35),
  259.                              aliasDereferencingProblem    (36),
  260.                              inappropriateAuthentication  (48),
  261.                              invalidCredentials           (49),
  262.                              insufficientAccessRights     (50),
  263.                              busy                         (51),
  264.                              unavailable                  (52),
  265.                              unwillingToPerform           (53),
  266.                              loopDetect                   (54),
  267.                              namingViolation              (64),
  268.                              objectClassViolation         (65),
  269.                              notAllowedOnNonLeaf          (66),
  270.                              notAllowedOnRDN              (67),
  271.                              entryAlreadyExists           (68),
  272.                              objectClassModsProhibited    (69),
  273.                              other                        (80)
  274.                            },
  275.              matchedDN     LDAPDN,
  276.              errorMessage  LDAPString
  277.          }
  278.  
  279.  
  280.  
  281.  
  282. Yeong, Howes & Kille                                            [Page 5]
  283.  
  284. RFC 1777                          LDAP                        March 1995
  285.  
  286.  
  287.    The LDAPResult is the construct used in this protocol to return
  288.    success or failure indications from servers to clients. In response
  289.    to various requests, servers will return responses containing fields
  290.    of type LDAPResult to indicate the final status of a protocol
  291.    operation request.  The errorMessage field of this construct may, at
  292.    the servers option, be used to return an ASCII string containing a
  293.    textual, human-readable error diagnostic. As this error diagnostic is
  294.    not standardized, implementations should not rely on the values
  295.    returned.  If the server chooses not to return a textual diagnostic,
  296.    the errorMessage field of the LDAPResult type should contain a zero
  297.    length string.
  298.  
  299.    For resultCodes of noSuchObject, aliasProblem, invalidDNSyntax,
  300.    isLeaf, and aliasDereferencingProblem, the matchedDN field is set to
  301.    the name of the lowest entry (object or alias) in the DIT that was
  302.    matched and is a truncated form of the name provided or, if an alias
  303.    has been dereferenced, of the resulting name.  The matchedDN field
  304.    should be set to NULL DN (a zero length string) in all other cases.
  305.  
  306. 4.1.  Bind Operation
  307.  
  308.    The function of the Bind Operation is to initiate a protocol session
  309.    between a client and a server, and to allow the authentication of the
  310.    client to the server. The Bind Operation must be the first operation
  311.    request received by a server from a client in a protocol session.
  312.    The Bind Request is defined as follows:
  313.  
  314.      BindRequest ::=
  315.          [APPLICATION 0] SEQUENCE {
  316.                              version   INTEGER (1 .. 127),
  317.                              name      LDAPDN,
  318.                              authentication CHOICE {
  319.                                   simple        [0] OCTET STRING,
  320.                                   krbv42LDAP    [1] OCTET STRING,
  321.                                   krbv42DSA     [2] OCTET STRING
  322.                              }
  323.          }
  324.  
  325.    Parameters of the Bind Request are:
  326.  
  327.    - version: A version number indicating the version of the protocol to
  328.      be used in this protocol session.  This document describes version
  329.      2 of the LDAP protocol.  Note that there is no version negotiation,
  330.      and the client should just set this parameter to the version it
  331.      desires.
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338. Yeong, Howes & Kille                                            [Page 6]
  339.  
  340. RFC 1777                          LDAP                        March 1995
  341.  
  342.  
  343.    - name: The name of the Directory object that the client wishes to
  344.      bind as.  This field may take on a null value (a zero length
  345.      string) for the purposes of anonymous binds.
  346.  
  347.    - authentication: information used to authenticate the name, if any,
  348.      provided in the Bind Request. The "simple" authentication option
  349.      provides minimal authentication facilities, with the contents of
  350.      the authentication field consisting only of a cleartext password.
  351.      This option should also be used when unauthenticated or anonymous
  352.      binds are to be performed, with the field containing a zero length
  353.      string in such cases. Kerberos version 4 [7] authentication to the
  354.      LDAP server and the DSA is accomplished by using the "krbv42LDAP"
  355.      and "krbv42DSA" authentication options, respectively.  Note that
  356.      though they are referred to as separate entities here, there is no
  357.      requirement these two entities be distinct (i.e., a DSA could speak
  358.      LDAP directly).  Two separate authentication options are provided
  359.      to support all implementations.  Each octet string should contain
  360.      the kerberos ticket (e.g., as returned by krb_mk_req()) for the
  361.      appropriate service.  The suggested service name for authentication
  362.      to the LDAP server is "ldapserver".  The suggested service name for
  363.      authentication to the DSA is "x500dsa".  In both cases, the
  364.      suggested instance name for the service is the name of the host on
  365.      which the service is running.  Of course, the actual service names
  366.      and instances will depend on what is entered in the local kerberos
  367.      principle database.
  368.  
  369.    The Bind Operation requires a response, the Bind Response, which is
  370.    defined as:
  371.  
  372.      BindResponse ::= [APPLICATION 1] LDAPResult
  373.  
  374.    A Bind Response consists simply of an indication from the server of
  375.    the status of the client's request for the initiation of a protocol
  376.    session.
  377.  
  378.    Upon receipt of a Bind Request, a protocol server will authenticate
  379.    the requesting client if necessary, and attempt to set up a protocol
  380.    session with that client. The server will then return a Bind Response
  381.    to the client indicating the status of the session setup request.
  382.  
  383. 4.2.  Unbind Operation
  384.  
  385.    The function of the Unbind Operation is to terminate a protocol
  386.    session.  The Unbind Operation is defined as follows:
  387.  
  388.      UnbindRequest ::= [APPLICATION 2] NULL
  389.  
  390.  
  391.  
  392.  
  393.  
  394. Yeong, Howes & Kille                                            [Page 7]
  395.  
  396. RFC 1777                          LDAP                        March 1995
  397.  
  398.  
  399.    The Unbind Operation has no response defined. Upon transmission of an
  400.    UnbindRequest, a protocol client may assume that the protocol session
  401.    is terminated. Upon receipt of an UnbindRequest, a protocol server
  402.    may assume that the requesting client has terminated the session and
  403.    that all outstanding requests may be discarded.
  404.  
  405. 4.3.  Search Operation
  406.  
  407.    The Search Operation allows a client to request that a search be
  408.    performed on its behalf by a server. The Search Request is defined as
  409.    follows:
  410.  
  411.      SearchRequest ::=
  412.          [APPLICATION 3] SEQUENCE {
  413.              baseObject    LDAPDN,
  414.              scope         ENUMERATED {
  415.                                 baseObject            (0),
  416.                                 singleLevel           (1),
  417.                                 wholeSubtree          (2)
  418.                            },
  419.              derefAliases  ENUMERATED {
  420.                                         neverDerefAliases     (0),
  421.                                         derefInSearching      (1),
  422.                                         derefFindingBaseObj   (2),
  423.                                         derefAlways           (3)
  424.                                    },
  425.              sizeLimit     INTEGER (0 .. maxInt),
  426.              timeLimit     INTEGER (0 .. maxInt),
  427.              attrsOnly     BOOLEAN,
  428.              filter        Filter,
  429.              attributes    SEQUENCE OF AttributeType
  430.      }
  431.  
  432.      Filter ::=
  433.          CHOICE {
  434.              and                [0] SET OF Filter,
  435.              or                 [1] SET OF Filter,
  436.              not                [2] Filter,
  437.              equalityMatch      [3] AttributeValueAssertion,
  438.              substrings         [4] SubstringFilter,
  439.              greaterOrEqual     [5] AttributeValueAssertion,
  440.              lessOrEqual        [6] AttributeValueAssertion,
  441.              present            [7] AttributeType,
  442.              approxMatch        [8] AttributeValueAssertion
  443.          }
  444.  
  445.      SubstringFilter
  446.          SEQUENCE {
  447.  
  448.  
  449.  
  450. Yeong, Howes & Kille                                            [Page 8]
  451.  
  452. RFC 1777                          LDAP                        March 1995
  453.  
  454.  
  455.              type               AttributeType,
  456.              SEQUENCE OF CHOICE {
  457.                  initial        [0] LDAPString,
  458.                  any            [1] LDAPString,
  459.                  final          [2] LDAPString
  460.              }
  461.          }
  462.  
  463.    Parameters of the Search Request are:
  464.  
  465.    - baseObject: An LDAPDN that is the base object entry relative to
  466.      which the search is to be performed.
  467.  
  468.    - scope: An indicator of the scope of the search to be performed. The
  469.      semantics of the possible values of this field are identical to the
  470.      semantics of the scope field in the Directory Search Operation.
  471.  
  472.    - derefAliases: An indicator as to how alias objects should be
  473.      handled in searching.  The semantics of the possible values of
  474.      this field are, in order of increasing value:
  475.  
  476.              neverDerefAliases: do not dereference aliases in searching
  477.              or in locating the base object of the search;
  478.  
  479.              derefInSearching: dereference aliases in subordinates of
  480.              the base object in searching, but not in locating the
  481.              base object of the search;
  482.  
  483.              derefFindingBaseObject: dereference aliases in locating
  484.              the base object of the search, but not when searching
  485.              subordinates of the base object;
  486.  
  487.              derefAlways: dereference aliases both in searching and in
  488.              locating the base object of the search.
  489.  
  490.    - sizelimit: A sizelimit that restricts the maximum number of entries
  491.      to be returned as a result of the search. A value of 0 in this
  492.      field indicates that no sizelimit restrictions are in effect for
  493.      the search.
  494.  
  495.    - timelimit: A timelimit that restricts the maximum time (in seconds)
  496.      allowed for a search. A value of 0 in this field indicates that no
  497.      timelimit restrictions are in effect for the search.
  498.  
  499.    - attrsOnly: An indicator as to whether search results should contain
  500.      both attribute types and values, or just attribute types.  Setting
  501.      this field to TRUE causes only attribute types (no values) to be
  502.      returned.  Setting this field to FALSE causes both attribute types
  503.  
  504.  
  505.  
  506. Yeong, Howes & Kille                                            [Page 9]
  507.  
  508. RFC 1777                          LDAP                        March 1995
  509.  
  510.  
  511.      and values to be returned.
  512.  
  513.    - filter: A filter that defines the conditions that must be fulfilled
  514.      in order for the search to match a given entry.
  515.  
  516.    - attributes: A list of the attributes from each entry found as a
  517.      result of the search to be returned. An empty list signifies that
  518.      all attributes from each entry found in the search are to be
  519.      returned.
  520.  
  521.    The results of the search attempted by the server upon receipt of a
  522.    Search Request are returned in Search Responses, defined as follows:
  523.  
  524.   Search Response ::=
  525.       CHOICE {
  526.            entry          [APPLICATION 4] SEQUENCE {
  527.                                objectName     LDAPDN,
  528.                                attributes     SEQUENCE OF SEQUENCE {
  529.                                                    AttributeType,
  530.                                                    SET OF AttributeValue
  531.                                               }
  532.                           },
  533.            resultCode     [APPLICATION 5] LDAPResult
  534.        }
  535.  
  536.    Upon receipt of a Search Request, a server will perform the necessary
  537.    search of the DIT.
  538.  
  539.    The server will return to the client a sequence of responses
  540.    comprised of:
  541.  
  542.    - Zero or more Search Responses each consisting of an entry found
  543.      during the search; with the response sequence terminated by
  544.  
  545.    - A single Search Response containing an indication of success, or
  546.      detailing any errors that have occurred.
  547.  
  548.    Each entry returned will contain all attributes, complete with
  549.    associated values if necessary, as specified in the 'attributes'
  550.    field of the Search Request.
  551.  
  552.    Note that an X.500 "list" operation can be emulated by a one-level
  553.    LDAP search operation with a filter checking for the existence of the
  554.    objectClass attribute, and that an X.500 "read" operation can be
  555.    emulated by a base object LDAP search operation with the same filter.
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Yeong, Howes & Kille                                           [Page 10]
  563.  
  564. RFC 1777                          LDAP                        March 1995
  565.  
  566.  
  567. 4.4.  Modify Operation
  568.  
  569.    The Modify Operation allows a client to request that a modification
  570.    of the DIB be performed on its behalf by a server.  The Modify
  571.    Request is defined as follows:
  572.  
  573. ModifyRequest ::=
  574.     [APPLICATION 6] SEQUENCE {
  575.          object         LDAPDN,
  576.          modification   SEQUENCE OF SEQUENCE {
  577.                              operation      ENUMERATED {
  578.                                                  add       (0),
  579.                                                  delete    (1),
  580.                                                  replace   (2)
  581.                                             },
  582.                              modification   SEQUENCE {
  583.                                                type    AttributeType,
  584.                                                values  SET OF
  585.                                                          AttributeValue
  586.                                             }
  587.                         }
  588.     }
  589.  
  590.    Parameters of the Modify Request are:
  591.  
  592.    - object: The object to be modified. The value of this field should
  593.      name the object to be modified after all aliases have been
  594.      dereferenced. The server will not perform any alias dereferencing
  595.      in determining the object to be modified.
  596.  
  597.    - A list of modifications to be performed on the entry to be modified.
  598.      The entire list of entry modifications should be performed
  599.      in the order they are listed, as a single atomic operation.  While
  600.      individual modifications may violate the Directory schema, the
  601.      resulting entry after the entire list of modifications is performed
  602.      must conform to the requirements of the Directory schema. The
  603.      values that may be taken on by the 'operation' field in each
  604.      modification construct have the following semantics respectively:
  605.  
  606.              add: add values listed to the given attribute, creating
  607.              the attribute if necessary;
  608.  
  609.              delete: delete values listed from the given attribute,
  610.  
  611.      removing the entire attribute if no values are listed, or
  612.      if all current values of the attribute are listed for
  613.      deletion;
  614.  
  615.  
  616.  
  617.  
  618. Yeong, Howes & Kille                                           [Page 11]
  619.  
  620. RFC 1777                          LDAP                        March 1995
  621.  
  622.  
  623.      replace: replace existing values of the given attribute
  624.      with the new values listed, creating the attribute if
  625.      necessary.
  626.  
  627.    The result of the modify attempted by the server upon receipt of a
  628.    Modify Request is returned in a Modify Response, defined as follows:
  629.  
  630.      ModifyResponse ::= [APPLICATION 7] LDAPResult
  631.  
  632.    Upon receipt of a Modify Request, a server will perform the necessary
  633.    modifications to the DIB.
  634.  
  635.    The server will return to the client a single Modify Response
  636.    indicating either the successful completion of the DIB modification,
  637.    or the reason that the modification failed. Note that due to the
  638.    requirement for atomicity in applying the list of modifications in
  639.    the Modify Request, the client may expect that no modifications of
  640.    the DIB have been performed if the Modify Response received indicates
  641.    any sort of error, and that all requested modifications have been
  642.    performed if the Modify Response indicates successful completion of
  643.    the Modify Operation.
  644.  
  645. 4.5.  Add Operation
  646.  
  647.    The Add Operation allows a client to request the addition of an entry
  648.    into the Directory. The Add Request is defined as follows:
  649.  
  650.      AddRequest ::=
  651.          [APPLICATION 8] SEQUENCE {
  652.               entry          LDAPDN,
  653.               attrs          SEQUENCE OF SEQUENCE {
  654.                                   type          AttributeType,
  655.                                   values        SET OF AttributeValue
  656.                              }
  657.          }
  658.  
  659.    Parameters of the Add Request are:
  660.  
  661.    - entry: the Distinguished Name of the entry to be added. Note that
  662.      all components of the name except for the last RDN component must
  663.      exist for the add to succeed.
  664.  
  665.    - attrs: the list of attributes that make up the content of the entry
  666.      being added.
  667.  
  668.    The result of the add attempted by the server upon receipt of a Add
  669.    Request is returned in the Add Response, defined as follows:
  670.  
  671.  
  672.  
  673.  
  674. Yeong, Howes & Kille                                           [Page 12]
  675.  
  676. RFC 1777                          LDAP                        March 1995
  677.  
  678.  
  679.      AddResponse ::= [APPLICATION 9] LDAPResult
  680.  
  681.    Upon receipt of an Add Request, a server will attempt to perform the
  682.    add requested. The result of the add attempt will be returned to the
  683.    client in the Add Response.
  684.  
  685. 4.6.  Delete Operation
  686.  
  687.    The Delete Operation allows a client to request the removal of an
  688.    entry from the Directory. The Delete Request is defined as follows:
  689.  
  690.      DelRequest ::= [APPLICATION 10] LDAPDN
  691.  
  692.    The Delete Request consists only of the Distinguished Name of the
  693.    entry to be deleted.  The result of the delete attempted by the
  694.    server upon receipt of a Delete Request is returned in the Delete
  695.    Response, defined as follows:
  696.  
  697.      DelResponse ::= [APPLICATION 11] LDAPResult
  698.  
  699.    Upon receipt of a Delete Request, a server will attempt to perform
  700.    the entry removal requested. The result of the delete attempt will be
  701.    returned to the client in the Delete Response. Note that only leaf
  702.    objects may be deleted with this operation.
  703.  
  704. 4.7.  Modify RDN Operation
  705.  
  706.    The Modify RDN Operation allows a client to change the last component
  707.    of the name of an entry in the Directory. The Modify RDN Request is
  708.    defined as follows:
  709.  
  710.      ModifyRDNRequest ::=
  711.          [APPLICATION 12] SEQUENCE {
  712.               entry          LDAPDN,
  713.               newrdn         RelativeLDAPDN,
  714.               deleteoldrdn   BOOLEAN
  715.          }
  716.  
  717.    Parameters of the Modify RDN Request are:
  718.  
  719.    - entry: the name of the entry to be changed.
  720.  
  721.    - newrdn: the RDN that will form the last component of the new name.
  722.  
  723.    - deleteoldrdn: a boolean parameter that controls whether the old RDN
  724.      attribute values should be retained as attributes of the entry or
  725.      deleted from the entry.
  726.  
  727.  
  728.  
  729.  
  730. Yeong, Howes & Kille                                           [Page 13]
  731.  
  732. RFC 1777                          LDAP                        March 1995
  733.  
  734.  
  735.    The result of the name change attempted by the server upon receipt of
  736.    a Modify RDN Request is returned in the Modify RDN Response, defined
  737.    as follows:
  738.  
  739.      ModifyRDNResponse ::= [APPLICATION 13] LDAPResult
  740.  
  741.    Upon receipt of a Modify RDN Request, a server will attempt to
  742.    perform the name change. The result of the name change attempt will
  743.    be returned to the client in the Modify RDN Response. The attributes
  744.    that make up the old RDN are deleted from the entry, or kept,
  745.    depending on the setting of the deleteoldrdn parameter.
  746.  
  747. 4.8.  Compare Operation
  748.  
  749.    The Compare Operation allows a client to compare an assertion
  750.    provided with an entry in the Directory. The Compare Request is
  751.    defined as follows:
  752.  
  753.      CompareRequest ::=
  754.          [APPLICATION 14] SEQUENCE {
  755.               entry          LDAPDN,
  756.               ava            AttributeValueAssertion
  757.          }
  758.  
  759.    Parameters of the Compare Request are:
  760.  
  761.    - entry: the name of the entry to be compared with.
  762.  
  763.    - ava: the assertion with which the entry is to be compared.
  764.  
  765.    The result of the compare attempted by the server upon receipt of a
  766.    Compare Request is returned in the Compare Response, defined as
  767.    follows:
  768.  
  769.      CompareResponse ::= [APPLICATION 15] LDAPResult
  770.  
  771.    Upon receipt of a Compare Request, a server will attempt to perform
  772.    the requested comparison. The result of the comparison will be
  773.    returned to the client in the Compare Response. Note that errors and
  774.    the result of comparison are all returned in the same construct.
  775.  
  776. 6.9.  Abandon Operation
  777.  
  778.    The function of the Abandon Operation is to allow a client to request
  779.    that the server abandon an outstanding operation.  The Abandon
  780.    Request is defined as follows:
  781.  
  782.      AbandonRequest ::= [APPLICATION 16] MessageID
  783.  
  784.  
  785.  
  786. Yeong, Howes & Kille                                           [Page 14]
  787.  
  788. RFC 1777                          LDAP                        March 1995
  789.  
  790.  
  791.    There is no response defined in the Abandon Operation. Upon
  792.    transmission of an Abandon Operation, a client may expect that the
  793.    operation identityfied by the Message ID in the Abandon Request has
  794.    been abandoned. In the event that a server receives an Abandon
  795.    Request on a Search Operation in the midst of transmitting responses
  796.    to that search, that server should cease transmitting responses to
  797.    the abandoned search immediately.
  798.  
  799. 5.  Protocol Element Encodings
  800.  
  801.    The protocol elements of LDAP are encoded for exchange using the
  802.    Basic Encoding Rules (BER) [12] of ASN.1 [11]. However, due to the
  803.    high overhead involved in using certain elements of the BER, the
  804.    following additional restrictions are placed on BER-encodings of LDAP
  805.    protocol elements:
  806.  
  807.    (1)  Only the definite form of length encoding will be used.
  808.  
  809.    (2)  Bitstrings and octet strings and all character string types
  810.         will be encoded in the primitive form only.
  811.  
  812. 6.  Security Considerations
  813.  
  814.    This version of the protocol provides facilities only for simple
  815.    authentication using a cleartext password, and for kerberos version 4
  816.    authentication.  Future versions of LDAP will likely include support
  817.    for other authentication methods.
  818.  
  819. 7.  Bibliography
  820.  
  821.    [1] The Directory: Overview of Concepts, Models and Service.  CCITT
  822.        Recommendation X.500, 1988.
  823.  
  824.    [2] Information Processing Systems -- Open Systems Interconnection --
  825.        The Directory: Overview of Concepts, Models and Service.  ISO/IEC
  826.        JTC 1/SC21; International Standard 9594-1, 1988
  827.  
  828.    [3] Rose, M., "Directory Assistance Service", RFC 1202, Performance
  829.        Systems International, Inc., February 1991.
  830.  
  831.    [4] Howes, T., Smith, M., and B. Beecher, "DIXIE Protocol
  832.        Specification, RFC 1249, University of Michigan, August 1991.
  833.  
  834.    [5] Kille, S., "A String Representation of Distinguished Names", RFC
  835.        1779, ISODE Consortium, March 1995.
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842. Yeong, Howes & Kille                                           [Page 15]
  843.  
  844. RFC 1777                          LDAP                        March 1995
  845.  
  846.  
  847.    [6] Howes, T., Kille, S., Yeong, W., and C. Robbins, "Lightweight
  848.        Directory Access Protocol", RFC 1488, University of Michigan,
  849.        ISODE Consortium, Performance Systems International, NeXor Ltd.,
  850.        July 1993.
  851.  
  852.    [7] Kerberos Authentication and Authorization System.  S.P. Miller,
  853.        B.C. Neuman, J.I. Schiller, J.H. Saltzer; MIT Project Athena
  854.        Documentation Section E.2.1, December 1987.
  855.  
  856.    [8] The Directory: Models.  CCITT Recommendation X.501 ISO/IEC JTC
  857.        1/SC21; International Standard 9594-2, 1988.
  858.  
  859.   [10] The Directory: Abstract Service Definition.  CCITT Recommendation
  860.        X.511, ISO/IEC JTC 1/SC21; International Standard 9594-3, 1988.
  861.  
  862.   [11] Specification of Abstract Syntax Notation One (ASN.1).  CCITT
  863.        Recommendation X.208, 1988.
  864.  
  865.   [12] Specification of Basic Encoding Rules for Abstract Syntax
  866.        Notation One (ASN.1).  CCITT Recommendation X.209, 1988.
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898. Yeong, Howes & Kille                                           [Page 16]
  899.  
  900. RFC 1777                          LDAP                        March 1995
  901.  
  902.  
  903. 10.  Authors' Addresses
  904.  
  905.        Wengyik Yeong
  906.        PSI Inc.
  907.        510 Huntmar Park Drive
  908.        Herndon, VA 22070
  909.        USA
  910.  
  911.        Phone:  +1 703-450-8001
  912.        EMail:  yeongw@psilink.com
  913.  
  914.  
  915.        Tim Howes
  916.        University of Michigan
  917.        ITD Research Systems
  918.        535 W William St.
  919.        Ann Arbor, MI 48103-4943
  920.        USA
  921.  
  922.        Phone:  +1 313 747-4454
  923.        EMail:   tim@umich.edu
  924.  
  925.  
  926.        Steve Kille
  927.        ISODE Consortium
  928.        PO Box 505
  929.        London
  930.        SW11 1DX
  931.        UK
  932.  
  933.        Phone:  +44-71-223-4062
  934.        EMail:  S.Kille@isode.com
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954. Yeong, Howes & Kille                                           [Page 17]
  955.  
  956. RFC 1777                          LDAP                        March 1995
  957.  
  958.  
  959. Appendix A - Complete ASN.1 Definition
  960.  
  961. Lightweight-Directory-Access-Protocol DEFINITIONS IMPLICIT TAGS ::=
  962.  
  963. BEGIN
  964.  
  965. LDAPMessage ::=
  966.     SEQUENCE {
  967.          messageID      MessageID,
  968.                         -- unique id in request,
  969.                         -- to be echoed in response(s)
  970.          protocolOp     CHOICE {
  971.                              searchRequest       SearchRequest,
  972.                              searchResponse      SearchResponse,
  973.                              modifyRequest       ModifyRequest,
  974.                              modifyResponse      ModifyResponse,
  975.                              addRequest          AddRequest,
  976.                              addResponse         AddResponse,
  977.                              delRequest          DelRequest,
  978.                              delResponse         DelResponse,
  979.                              modifyDNRequest     ModifyDNRequest,
  980.                              modifyDNResponse    ModifyDNResponse,
  981.                              compareDNRequest    CompareRequest,
  982.                              compareDNResponse   CompareResponse,
  983.                              bindRequest         BindRequest,
  984.                              bindResponse        BindResponse,
  985.                              abandonRequest      AbandonRequest,
  986.                              unbindRequest       UnbindRequest
  987.                         }
  988.     }
  989.  
  990. BindRequest ::=
  991.     [APPLICATION 0] SEQUENCE {
  992.          version        INTEGER (1 .. 127),
  993.                         -- current version is 2
  994.          name           LDAPDN,
  995.                         -- null name implies an anonymous bind
  996.          authentication CHOICE {
  997.                              simple        [0] OCTET STRING,
  998.                                        -- a zero length octet string
  999.                                        -- implies an unauthenticated
  1000.                                        -- bind.
  1001.                              krbv42LDAP    [1] OCTET STRING,
  1002.                              krbv42DSA     [2] OCTET STRING
  1003.                                        -- values as returned by
  1004.                                        -- krb_mk_req()
  1005.                                        -- Other values in later versions
  1006.                                        -- of this protocol.
  1007.  
  1008.  
  1009.  
  1010. Yeong, Howes & Kille                                           [Page 18]
  1011.  
  1012. RFC 1777                          LDAP                        March 1995
  1013.  
  1014.  
  1015.                         }
  1016.     }
  1017.  
  1018. BindResponse ::= [APPLICATION 1] LDAPResult
  1019.  
  1020. UnbindRequest ::= [APPLICATION 2] NULL
  1021.  
  1022. SearchRequest ::=
  1023.     [APPLICATION 3] SEQUENCE {
  1024.          baseObject     LDAPDN,
  1025.          scope          ENUMERATED {
  1026.                              baseObject            (0),
  1027.                              singleLevel           (1),
  1028.                              wholeSubtree          (2)
  1029.                         },
  1030.          derefAliases   ENUMERATED {
  1031.                              neverDerefAliases     (0),
  1032.                              derefInSearching      (1),
  1033.                              derefFindingBaseObj   (2),
  1034.                              alwaysDerefAliases    (3)
  1035.                         },
  1036.          sizeLimit      INTEGER (0 .. maxInt),
  1037.                         -- value of 0 implies no sizelimit
  1038.          timeLimit      INTEGER (0 .. maxInt),
  1039.                         -- value of 0 implies no timelimit
  1040.          attrsOnly     BOOLEAN,
  1041.                         -- TRUE, if only attributes (without values)
  1042.                         -- to be returned.
  1043.          filter         Filter,
  1044.          attributes     SEQUENCE OF AttributeType
  1045.     }
  1046.  
  1047. SearchResponse ::=
  1048.     CHOICE {
  1049.          entry          [APPLICATION 4] SEQUENCE {
  1050.                              objectName     LDAPDN,
  1051.                              attributes     SEQUENCE OF SEQUENCE {
  1052.                                               AttributeType,
  1053.                                               SET OF
  1054.                                                 AttributeValue
  1055.                                             }
  1056.                         },
  1057.          resultCode     [APPLICATION 5] LDAPResult
  1058.     }
  1059.  
  1060. ModifyRequest ::=
  1061.     [APPLICATION 6] SEQUENCE {
  1062.          object         LDAPDN,
  1063.  
  1064.  
  1065.  
  1066. Yeong, Howes & Kille                                           [Page 19]
  1067.  
  1068. RFC 1777                          LDAP                        March 1995
  1069.  
  1070.  
  1071.          modifications  SEQUENCE OF SEQUENCE {
  1072.                              operation     ENUMERATED {
  1073.                                              add      (0),
  1074.                                              delete   (1),
  1075.                                              replace  (2)
  1076.                                            },
  1077.                              modification  SEQUENCE {
  1078.                                              type     AttributeType,
  1079.                                              values   SET OF
  1080.                                                         AttributeValue
  1081.                                            }
  1082.                         }
  1083.     }
  1084.  
  1085.  
  1086. ModifyResponse ::= [APPLICATION 7] LDAPResult
  1087.  
  1088. AddRequest ::=
  1089.     [APPLICATION 8] SEQUENCE {
  1090.          entry          LDAPDN,
  1091.          attrs          SEQUENCE OF SEQUENCE {
  1092.                              type          AttributeType,
  1093.                              values        SET OF AttributeValue
  1094.                         }
  1095.     }
  1096.  
  1097. AddResponse ::= [APPLICATION 9] LDAPResult
  1098.  
  1099. DelRequest ::= [APPLICATION 10] LDAPDN
  1100.  
  1101. DelResponse ::= [APPLICATION 11] LDAPResult
  1102.  
  1103. ModifyRDNRequest ::=
  1104.     [APPLICATION 12] SEQUENCE {
  1105.          entry          LDAPDN,
  1106.          newrdn         RelativeLDAPDN -- old RDN always deleted
  1107.     }
  1108.  
  1109. ModifyRDNResponse ::= [APPLICATION 13] LDAPResult
  1110.  
  1111. CompareRequest ::=
  1112.     [APPLICATION 14] SEQUENCE {
  1113.          entry          LDAPDN,
  1114.          ava            AttributeValueAssertion
  1115.     }
  1116.  
  1117. CompareResponse ::= [APPLICATION 15] LDAPResult
  1118.  
  1119.  
  1120.  
  1121.  
  1122. Yeong, Howes & Kille                                           [Page 20]
  1123.  
  1124. RFC 1777                          LDAP                        March 1995
  1125.  
  1126.  
  1127. AbandonRequest ::= [APPLICATION 16] MessageID
  1128.  
  1129. MessageID ::= INTEGER (0 .. maxInt)
  1130.  
  1131. LDAPDN ::= LDAPString
  1132.  
  1133. RelativeLDAPDN ::= LDAPString
  1134.  
  1135. Filter ::=
  1136.     CHOICE {
  1137.         and            [0] SET OF Filter,
  1138.         or             [1] SET OF Filter,
  1139.         not            [2] Filter,
  1140.         equalityMatch  [3] AttributeValueAssertion,
  1141.         substrings     [4] SubstringFilter,
  1142.         greaterOrEqual [5] AttributeValueAssertion,
  1143.         lessOrEqual    [6] AttributeValueAssertion,
  1144.         present        [7] AttributeType,
  1145.         approxMatch    [8] AttributeValueAssertion
  1146.     }
  1147.  
  1148. LDAPResult ::=
  1149.     SEQUENCE {
  1150.         resultCode    ENUMERATED {
  1151.                         success                      (0),
  1152.                         operationsError              (1),
  1153.                         protocolError                (2),
  1154.                         timeLimitExceeded            (3),
  1155.                         sizeLimitExceeded            (4),
  1156.                         compareFalse                 (5),
  1157.                         compareTrue                  (6),
  1158.                         authMethodNotSupported       (7),
  1159.                         strongAuthRequired           (8),
  1160.                         noSuchAttribute              (16),
  1161.                         undefinedAttributeType       (17),
  1162.                         inappropriateMatching        (18),
  1163.                         constraintViolation          (19),
  1164.                         attributeOrValueExists       (20),
  1165.                         invalidAttributeSyntax       (21),
  1166.                         noSuchObject                 (32),
  1167.                         aliasProblem                 (33),
  1168.                         invalidDNSyntax              (34),
  1169.                         isLeaf                       (35),
  1170.                         aliasDereferencingProblem    (36),
  1171.                         inappropriateAuthentication  (48),
  1172.                         invalidCredentials           (49),
  1173.                         insufficientAccessRights     (50),
  1174.                         busy                         (51),
  1175.  
  1176.  
  1177.  
  1178. Yeong, Howes & Kille                                           [Page 21]
  1179.  
  1180. RFC 1777                          LDAP                        March 1995
  1181.  
  1182.  
  1183.                         unavailable                  (52),
  1184.                         unwillingToPerform           (53),
  1185.                         loopDetect                   (54),
  1186.                         namingViolation              (64),
  1187.                         objectClassViolation         (65),
  1188.                         notAllowedOnNonLeaf          (66),
  1189.                         notAllowedOnRDN              (67),
  1190.                         entryAlreadyExists           (68),
  1191.                         objectClassModsProhibited    (69),
  1192.                         other                        (80)
  1193.                       },
  1194.         matchedDN     LDAPDN,
  1195.         errorMessage  LDAPString
  1196.     }
  1197.  
  1198. AttributeType ::= LDAPString
  1199.                 -- text name of the attribute, or dotted
  1200.                 -- OID representation
  1201.  
  1202. AttributeValue ::= OCTET STRING
  1203.  
  1204. AttributeValueAssertion ::=
  1205.     SEQUENCE {
  1206.         attributeType        AttributeType,
  1207.         attributeValue       AttributeValue
  1208.     }
  1209.  
  1210. SubstringFilter ::=
  1211.     SEQUENCE {
  1212.         type               AttributeType,
  1213.         SEQUENCE OF CHOICE {
  1214.           initial          [0] LDAPString,
  1215.           any              [1] LDAPString,
  1216.           final            [2] LDAPString
  1217.       }
  1218.     }
  1219.  
  1220. LDAPString ::= OCTET STRING
  1221.  
  1222. maxInt INTEGER ::= 65535
  1223. END
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234. Yeong, Howes & Kille                                           [Page 22]
  1235.  
  1236.