LDAPWiki: Directory Synchronization Control

Overview#

Microsoft Active Directory Directory Synchronization Control or DirSync control is an LDAP server extension that enables an application to search a directory partition for objects that have changed since a previous state.

The Directory Synchronization Control is a Supported Control with an OID of 1.2.840.113556.1.4.841 and may be referred to as LDAP_SERVER_DIRSYNC_OID

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." The Directory Synchronization Control is implemented by the Microsoft Active Directory Windows 2000 Server. It is intended that other members of the Internet community be able to use this control if desired. [1]

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

Specification Details#

The Directory Synchronization Control 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
}

replControlValue#

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. used by the client in subsequent searches.

Additional Features#

We have also discovered some additional features.[2]

Apparently there are additional values for the replControlValue optional flags for use with the Directory Synchronization Control. These can be zero or a combination of one or more of the values listed in the following table.

Bit flag name and value Description

BIT	NAME	Description
0x00000001	LDAP_DIRSYNC_OBJECT_SECURITY (OS)	Windows Server® 2003 operating system, Windows Server® 2008 operating system, Windows Server® 2008 R2 operating system, and Windows Server® 2012 operating system: If this flag is present, the client can only view objects and attributes that are otherwise accessible to the client. If this flag is not present, the server checks if the client has access rights to read the changes in the NC. Microsoft Windows® 2000 operating system: Not supported.
0x00000800	LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER (AFO) (parentsFirst)	The server returns parent objects before child objects.
0x00002000	LDAP_DIRSYNC_PUBLIC_DATA_ONLY (PDO)	Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012: This flag can optionally be passed to the DC, but it has no effect. Windows 2000: Not supported.
0x80000000	LDAP_DIRSYNC_INCREMENTAL_VALUES (IV)	Windows Server 2003, Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012: If this flag is not present, all of the values, up to a server-specified limit, in a multivalued attribute are returned when any value changes. If this flag is present, only the changed values are returned, provided the attribute is a forward link value. Windows 2000: Not supported.

More Information#

There might be more information for this subject on one of the following:

[#1] - http://tools.ietf.org/html/draft-armijo-ldap-dirsync-01 - based on information retrieved 2013-06-09
[#2] - http://msdn.microsoft.com/en-us/library/cc223347.aspx - based on information retrieved 2013-06-09