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 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 . Please send editorial comments directly to the author . 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, , 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 , 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