Internet DRAFT - draft-armijo-ldap-dirsync


INTERNET-DRAFT 				                  Michael P. Armijo
Status: Informational			              Microsoft Corporation
November 12, 1999 
Expires May 12, 2000

          Microsoft LDAP Control for Directory Synchronization

1. Status of this Memo

This memo provides information for the Internet community. It does not 
specify an Internet standard of any kind. Distribution of this memo is 

This document is an Internet-Draft and is in full conformance with all 
provisions of Section 10 of RFC2026. 

Internet-Drafts are working documents 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."

The list of current Internet-Drafts can be accessed at

The list of Internet-Draft Shadow Directories can be accessed at

2. Abstract

This document defines an LDAP Control for Directory Synchronization.
This control allows a client to request changes made to a directory replica 
since a state of that replica identified by an opaque "cookie."  This 
control is implemented by the Active Directory feature of Microsoft 
Windows 2000 Server.  It is intended that other members of the Internet 
community be able to use this control if desired.

3. Overview

Many organizations today store information on multiple directories. 
For example, e-mail accounts and related information might be stored in 
one directory; information about files and networking in another; 
certain data, such as financial or human resource data in yet another 
directory. Such an environment is referred to as a mixed-directory 

The LDAP Control for Directory Synchronization provides a method for
dissimilar directories to share pertinent information.

4. Directory Synchronization Control

This control MUST only be used with a SearchRequest message.  A 
server MUST ignore the control if used with any other message 
unless the criticality field is set to True, in which case the 
entire operation MUST fail and MUST instead return the resultCode 
unsupportedCriticalExtension as per section 4.1.12 of [RFC 2251].  
The server MUST list that it recognizes this control in the 
supportedControl attribute in the root DSE.

The replication control is included in the searchRequest and 
searchResultDone messages as part of the server controls field of 
the LDAPMessage. The structure of this control is as follows:

Repl	Control ::= SEQUENCE {
		controlType		1.2.840.113556.1.4.841
		controlValue		replControlValue
		criticality		TRUE

The replControlValue in the SearchRequest is an OCTET STRING wrapping 
the BER-encoded version of the following:

realReplControlValue ::= SEQUENCE {
		parentsFirst		integer
		maxReturnlength		integer
		cookie			OCTET STRING

parentsFirst: Setting parentsFirst to one ensures that all parents of 
the children come before their children.   

maxReturnlength: This specifies the maximum length in bytes to be 
returned in the control response. This can be used to limit the amount 
of data returned.  This field must be set to a number above zero for 
date to returned.

cookie: The cookie is an implementation specific opaque OCTET STRING 
that is updated by the directory during each search request. It allows 
the Dirsync control to read changes incrementally from the directory. 
The very first time the control is created, the cookie should be 
encoded as a NULL string with 0 length.

The replControlValue in the SearchResponse is an OCTET STRING wrapping 
the BER-encoded version of the following:

realReplControlValue ::= SEQUENCE {
		Flag			integer
		maxReturnlength		integer
		cookie			OCTET STRING

flag: If flag is set to a non-zero value, it implies that there is more 
data to retrieve. 

maxReturnlength: This specifies the maximum length in bytes to be 
returned in the control response. 

cookie: This is the opaque cookie returned by the server to be used by 
the client in subsequent searches.

5. Provider/Consumer Interaction

Server implementations (Providers) MUST return a globally unique 
identification (GUID) for each object returned with the Directory 
Synchronization control.  This unique identifier MUST be returned 
in the value of the DN with the DNWithString Syntax (defined in 
section 5.2).  If the DN is static then the DN can be used for unique 
identification of the object. Consumer applications MUST take the 
first value in the DN value set (encoded with the DNWithString syntax) 
to be the GUID to the object.  A GUID MUST be matched to the existing 
objects on the consumer store.  The values returned by the Provider 
server MUST be applied to the object, with the exception of reserved 
attributes defined in section 5.1.  A GUID with no corresponding object 
on the consumer store MUST be treated as a new object.

The LDAP Directory Synchronization control allows a client to request 
changes made to a directory replica since a state of that replica 
identified by an opaque "cookie."  

A typical consumer (dirsync agent) will work on a schedule to read 
changes from a supplier directory and write changes to a consumer 
directory.  On this schedule the client will wake up, read the opaque 
cookie from a file, then enter a loop passing the current cookie to 
the supplier server and receive changes back.  It computes updates 
to perform to the consumer directory based on the changes, and makes 
these updates.  When these updates are committed it writes the new 
cookie to the file, and goes around the loop again if the setting of 
the 'flag' returned by the supplier states that there is additional 
information to be retreieved.  If not it exits the loop and sleeps 
until the next scheduled cycle.

When the control is initally run the client should send the 
cookie encoded as a NULL string with 0 length. 

The server will respond to each Directory Synchronization search 
request with the changes since the last control was run (based on 
the cookie provided by the client) and a cookie to be stored and used 
by the client during the next synchronization cycle.  The client MUST 
consider the cookie to be an opaque structure and not make any 
assumptions about its internal organization or value.  The client may 
reuse older cookies, however this search request may result in changes 
being reported that have already been received by the client.

In the case of a complete server failure, a client may pass a cookie 
generated by one directory server to a different directory server 
hosting the same directory partition.  This may result in the new 
server reporting changes already reported by the old server.  The 
new server MAY report a full synchronization (all objects and 
attributes in the search request).  The client MUST be able to handle 
changes already reported being returned again.

The directory server SHOULD limit use of this control to entities 
explicitly granted permission to use this control.  The directory 
server SHOULD return objects and attributes based on the filters of 
the search request and based on the permissions of the authenticated 

Server implementations may have other restraints on which containers 
or objects may or may not use the Directory Synchronization control. 
If a client attempts to run the Directory Synchronization control on 
an object or container that does not support the control, the server 
SHOULD return the error unwillingToPerform(53). 

5.1 Interpretation of Advanced Directory Operations

Certain directory changes and operations are not defined in an LDAP 
search response.  The Directory Synchronization control will interpret 
these operations using defined object attributes.  The directory 
synchronization consumer MUST understand and support these operations.

A Provider MUST return an attribute with a NULL value to signify that 
attribute has been removed.  A DirSync consumer MUST interpret this as 
an attribute removal and process this accordingly.

If an object is deleted it will be returned in the search response 
message with the 'isDeleted' attribute set to value True.  The client 
MUST interpret this as an object deletion and MUST perform the proper 
operation on the consumer directory.

	(1.2.840.113556.1.2.48 NAME 'isDeleted' 

If an object is moved or renamed the attribute 'RDN' will be returned 
with the value set to the new object name.  The client MUST interpret 
this as an object rename and perform the proper operation on the 
consumer directory.
	(1.2.840.113556.1.4.1 NAME 'RDN' 

5.2  DN With String Syntax

( 1.2.840.113556.1.4.904 DESC 'DNWithString')
Values with this string are encoded as follows:

	DNWithString  = StringTag ':' Count ':' String ':' DN
	OctetTag = 'S' | 's'
	Count = positive decimal number, counting number of bytes in 
	String = <normally encoded (i.e. UTF8 for V3) string>  
	// Note: the number 
	of bytes in the string encoding of the String is Count. 
	DN = <normal string encoding of a DN> 

	As an example, the string encoding of the combination of 
	"GUID=89876" and DC=foobar,DC=Com is


	As an example, the string encoding of the combination of XYZ (where 
	X, Y, and Z all have two byte UTF-8 encodings) and 
	DC=foobar,DC=Com is


	Note: Characters with multibyte UTF-8 encodings contribute more 
	than one to the count

6. Security Considerations

This document details a method for retreiving information from a 
directory server using an LDAP control.  Server implementations utilizing 
this control SHOULD implement security mechanisms as defined in 
Authentication Methods for LDAP [AuthMeth].

Each implementation should take appropriate measures to insure that only 
authorized entities can utilize this control.

7. References

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

    M. Wahl, H. Alvestrand, J. Hodges, R. Morgan. "Authentication 
    Methods for LDAP".  INTERNET-DRAFT, Work In Progress. 

[RFC 2119] 
    Bradner, S., "Key words for use in RFCs to Indicate Requirement 
    RFC 2119, Harvard University, March 1997.

8. Authors Address

 Michael P. Armijo
 One Microsoft Way
 Redmond, WA 


Expires May 12, 2000