[Docs] [txt|pdf] [Tracker] [WG] [Email] [Nits]

Versions: 00

LDAPEXT Working Group                                           M. Smith
INTERNET-DRAFT                             Netscape Communications Corp.
Intended Category: Standards Track
Expires: 12 September 1998


                                                           12 March 1998


              LDAP C API Extensions for Persistent Search
               <draft-ietf-ldapext-c-api-psearch-00.txt>



1.  Status of this Memo

This draft document will be submitted to the RFC Editor as a Standards
Track document. Distribution of this memo is unlimited.  Technical dis-
cussion of this document will take place on the IETF LDAP Extension
Working Group mailing list <ietf-ldapext@netscape.com>.  Please send
editorial comments directly to the author <mcs@netscape.com>.

This document is an Internet-Draft.  Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and its
working groups.  Note that other groups may also distribute working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as ``work in progress.''

To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).

Copyright (C) The Internet Society (1998). All Rights Reserved.

Please see the Copyright section near the end of this document for more
information.










Expires: 12 September 1998                                      [Page 1]


INTERNET-DRAFT        LDAP C Persistent Search API         12 March 1998


2.  Abstract

This document defines extensions to the LDAP C API to support the LDAP
Persistent Search Simple Change Notification Mechanism.  More specifi-
cally, this document defines functions to create Persistent Search con-
trols and to parse Entry Change Notification controls.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED",  and "MAY" in this document are
to be interpreted as described in RFC 2119 [KEYWORDS].


3.  Background and Intended Usage

The LDAP C API [CAPI] defines a C language application programming
interface (API) to the Lightweight Directory Access Protocol [LDAP].
This document defines extensions to that API to support an optional LDAP
extension for change notification called Persistent Search [PSEARCH].

Persistent Search is an extension to the LDAPv3 [LDAP] search operation
that provides a simple mechanism by which an LDAP client can receive
notification of changes that occur in an LDAP server.  The mechanism is
designed to be very flexible yet easy for clients and servers to imple-
ment.

LDAP clients that wish to use the Persistent Search feature SHOULD first
check the supportedControls attribute in a server's rootDSE to determine
if a value identical to the Persistent Search control's OID is present.
If the OID is present and the client chooses to use the Persistent
Search feature, it MUST construct a Persistent Search control and send
it to the server within an LDAP searchRequest message.  Clients applica-
tions MAY use the ldap_create_persistentsearch_control() function des-
ribed in this document to create a Persistent Search control.

If requested in the Persistent Search control, servers MUST return an
Entry Change Notification control to the client with each SearchResul-
tEntry message returned due to an entry being added, deleted, or modi-
fied in the server.  An Entry Change Notification control MAY be parsed
to extract its contents by using the ldap_parse_entrychange_control()
function described in this document.



4.  Creating a Persistent Search Control

The ldap_create_persistentsearch_control() function MAY be used to
create a Persistent Search control which MAY in turn be passed to the
ldap_search_ext() or ldap_search_ext_s() functions described in [CAPI]



Expires: 12 September 1998                                      [Page 2]


INTERNET-DRAFT        LDAP C Persistent Search API         12 March 1998


to request a Persistent Search.

       int ldap_create_persistentsearch_control(
           LDAP            *ld,
           int             changetypes,
           int             changesonly,
           int             return_echg_ctls,
           char            ctl_iscritical,
           LDAPControl     **ctrlp
       );

       #define LDAP_CHANGETYPE_ADD             1
       #define LDAP_CHANGETYPE_DELETE          2
       #define LDAP_CHANGETYPE_MODIFY          4
       #define LDAP_CHANGETYPE_MODDN           8
       #define LDAP_CHANGETYPE_ANY             (1|2|4|8)

       #define LDAP_CONTROL_PERSISTENTSEARCH   "2.16.840.1.113730.3.4.3"

The parameters to the ldap_create_persistentsearch_control() function
are:

ld               An LDAP session handle, as obtained from a call to
                 ldap_init().

changetypes      A bit-sensitive field that indicates which kinds of
                 changes the client wants to be informed about.  Its
                 value should be LDAP_CHANGETYPE_ANY, or any logical-OR
                 combination of LDAP_CHANGETYPE_ADD,
                 LDAP_CHANGETYPE_DELETE, LDAP_CHANGETYPE_MODIFY, and
                 LDAP_CHANGETYPE_MODDN.  This field corresponds to the
                 changeType element of the BER-encoded PersistentSearch
                 control value itself.

changesonly      A Boolean field that indicates whether the client
                 wishes to only receive searchResultEntry messages for
                 entries that have been changed. If non-zero, only
                 entries that result from changes are returned; other-
                 wise, all of the static entries that match the search
                 criteria are returned before the server begins change
                 notification.  This field corresponds to the change-
                 sOnly element of the BER-encoded PersistentSearch con-
                 trol value itself.

return_echg_ctls A Boolean field that indicates whether the server
                 should send back an Entry Change Notification control
                 with each searchResultEntry that is returned due to a
                 change to an entry.  If non-zero, Entry Change



Expires: 12 September 1998                                      [Page 3]


INTERNET-DRAFT        LDAP C Persistent Search API         12 March 1998


                 Notification controls are requested; if zero, they are
                 not.  This field corresponds to the returnECs element
                 of the BER-encoded PersistentSearch control value
                 itself.

ctl_iscritical   Used to set the ctl_iscritical flag within the result-
                 ing LDAPControl structure.  Pass a non-zero value to
                 indicate that the Persistent Search control is critical
                 and a zero value if it is not.

ctrlp            A result parameter that will be assigned the address of
                 an LDAPControl structure that contains the Persistent
                 Search control created by this function.  The memory
                 occupied by the LDAPControl structure should be freed
                 when it is no longer in use by calling
                 ldap_control_free().

The ldap_create_persistentsearch_control() function returns an LDAP
error code to indicate success or failure (LDAP_SUCCESS if all goes
well).



5.  Parsing an Entry Change Notification Control

When an application receives entries that contain Entry Change Notifica-
tion controls, it SHOULD use the ldap_parse_entrychange_control() func-
tion to look for and parse the control.

       int ldap_parse_entrychange_control(
           LDAP            *ld,
           LDAPControl     **ctrls,
           int             *chgtypep,
           char            **prevdnp,
           int             *chgnumpresentp,
           long            *chgnump
       );

       #define LDAP_CONTROL_ENTRYCHANGE        "2.16.840.1.113730.3.4.7"

The parameters to the ldap_parse_entrychange_control() function are:

ld               An LDAP session handle.

ctrls            The address of a NULL-terminated array of LDAPControl
                 structures, typically obtained by a call to
                 ldap_get_entry_controls().




Expires: 12 September 1998                                      [Page 4]


INTERNET-DRAFT        LDAP C Persistent Search API         12 March 1998


chgtypep         This result parameter is filled in with one of the fol-
                 lowing values to indicate the type of change that was
                 made that caused the entry to be returned:
                 LDAP_CHANGETYPE_ADD (1), LDAP_CHANGETYPE_DELETE (2),
                 LDAP_CHANGETYPE_MODIFY (4), or LDAP_CHANGETYPE_MODDN
                 (8).  If this parameter is NULL, the change type infor-
                 mation is not returned.  The value for this result
                 parameter is pulled from the changeType element of the
                 BER-encoded EntryChangeNotification control value
                 itself.

prevdnp          This result parameter is filled in with the DN the
                 entry had before it was renamed and/or moved by a
                 modifyDN operation.  It is set to NULL for other types
                 of changes.  If this parameter is NULL, the previous DN
                 information is not returned.  The value for this result
                 parameter is pulled from the previousDN element of the
                 BER-encoded EntryChangeNotification control value
                 itself.

chgnumpresentp   This result parameter is filled in with a non-zero
                 value if a change number was returned in the
                 EntryChangeNotification control (the change number is
                 optional and servers MAY choose not to return it).  If
                 this parameter is NULL, no indication of whether the
                 change number was present is returned.

chgnump          This result parameter is filled in with the change
                 number if one was returned in the EntryChangeNotifica-
                 tion control (chgnumpresentp will be filled in with a
                 non-zero value if this parameter is filled in).  If
                 this parameter is NULL, the change number is not
                 returned.  The value for this result parameter is
                 pulled from the optional changeNumber element of the
                 BER-encoded EntryChangeNotification control value
                 itself.

The ldap_parse_entrychange_control() function returns an LDAP error code
that indicates whether an EntryChangeNotification control was found and
whether the parsing was successful.  LDAP_SUCCESS is returned if all
goes well, LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does
not include an EntryChangeNotification control, and another LDAP error
code that is defined in [CAPI] is returned if a parsing error or other
problem occurs.







Expires: 12 September 1998                                      [Page 5]


INTERNET-DRAFT        LDAP C Persistent Search API         12 March 1998


6.  Security Considerations

In some situations, it may be important to prevent general exposure of
information about the changes that are made to an an LDAP server.
Clients should take care to not abuse the Persistent Search feature and
should be prepared for servers to refuse to service a particular Per-
sistent Search request due to access control or other site-defined poli-
cies.

Please see the protocol extension document [PSEARCH] for a discussion of
related security considerations.


7.  Copyright

Copyright (C) The Internet Society (1998). All Rights Reserved.


others, and derivative works that comment on or otherwise explain it or
assist in its implementation may be prepared, copied, published and dis-
tributed, in whole or in part, without restriction of any kind, provided
that the above copyright notice and this paragraph are included on all
such copies and derivative works.  However, this document itself may not
be modified in any way, such as by removing the copyright notice or
references to the Internet Society or other Internet organizations,
except as needed for the  purpose of developing Internet standards in
which case the procedures for copyrights defined in the Internet Stan-
dards process must be followed, or as required to translate it into
languages other than English.

The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.

This document and the information contained herein is provided on an "AS
IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
NESS FOR A PARTICULAR PURPOSE.



8.  Bibliography

[CAPI]      M. Smith, T. Howes, A. Herron, C. Weider, M. Wahl, A. Anan-
            tha, "The C LDAP Application Program Interface", INTERNET-
            DRAFT, <draft-ietf-ldapext-ldap-c-api-00.txt>, March 1998.




Expires: 12 September 1998                                      [Page 6]


INTERNET-DRAFT        LDAP C Persistent Search API         12 March 1998


[KEYWORDS]  S. Bradner, "Key words for use in RFCs to Indicate Require-
            ment Levels", RFC 2119, March 1997.

[LDAP]      M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
            Protocol (v3)", RFC 2251, December 1997.

[PSEARCH]   M. Smith, G. Good, T. Howes, R. Weltman, "Persistent Search:
            A Simple LDAP Change Notification Mechanism", INTERNET-DRAFT
            <draft-ietf-ldapext-psearch-00.txt>, March 1998.


9.  Author's Address

   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd., Mailstop MV068
   Mountain View, CA 94043
   USA
   +1 650 937-3477
   mcs@netscape.com































Expires: 12 September 1998                                      [Page 7]

1.     Status of this Memo............................................1
2.     Abstract.......................................................2
3.     Background and Intended Usage..................................2
4.     Creating a Persistent Search Control...........................2
5.     Parsing an Entry Change Notification Control...................4
6.     Security Considerations........................................6
7.     Copyright......................................................6
8.     Bibliography...................................................6
9.     Author's Address...............................................7


Html markup produced by rfcmarkup 1.129b, available from https://tools.ietf.org/tools/rfcmarkup/