INTERNET-DRAFT                                            Michael P. Armijo
Status: Informational                                 Microsoft Corporation
February 1999
Expires August 1999



          Microsoft LDAP Control for Directory Synchronization
                  draft-armijo-ldap-dirsync-00.txt


. 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
unlimited.

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
http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.



. Abstract

This document defines an LDAP Control for Directory Synchronization.
This control allows a client to request changes from a directory since
the last Directory Synchronization Control was run.  This control is
implemented by the Active Directory feature of Microsoft Windows
 Server.  It is intended that other members of the Internet
community be able to use this control if desired.


. 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
environment.

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


. 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
                maxAttributeCount       integer
                cookie                  OCTET STRING
}

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

maxAttributeCount: This specifies the maximum number of attributes to
return. This can be used to limit the amount of data 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
                maxAttributeCount       integer
                cookie                  OCTET STRING
}

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

maxAttributeCount: This specifies the maximum number of attributes to
return. This can be used to limit the amount of data returned.

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


. Client Server Interaction

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 client (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
entity.

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 client MUST understand and support these operations.

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

        isDeleted
        (1.2.840.113556.1.2.48 NAME 'isDeleted'
          SYNTAX 1.3.6.1.4.1.1466.115.121.1.7)


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.

        RDN
        (1.2.840.113556.1.4.1 NAME 'RDN'
           SYNTAX 1.3.6.1.4.1.1466.115.121.1.15)


. 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.


. References

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

[AuthMeth]
    M. Wahl, H. Alvestrand, J. Hodges, R. Morgan. "Authentication
    Methods for LDAP".  INTERNET-DRAFT, Work In Progress.
    draft-ietf-ldapext-authmeth-03.txt

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


. Authors Address

 Michael P. Armijo
 One Microsoft Way
 Redmond, WA
 98052
 USA

 (425)882-8080
 micharm@microsoft.com


Internet-Draft
Expires August 1999