idnits 2.17.1 draft-armijo-ldap-dirsync-01.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 299 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 3 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** There are 36 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The "Author's Address" (or "Authors' Addresses") section title is misspelled. == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 12, 2000) is 8743 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC 2119' is defined on line 260, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2251 (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) == Outdated reference: A later version (-04) exists of draft-ietf-ldapext-authmeth-03 Summary: 7 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Michael P. Armijo 2 Status: Informational Microsoft Corporation 3 November 12, 1999 4 Expires May 12, 2000 6 Microsoft LDAP Control for Directory Synchronization 7 draft-armijo-ldap-dirsync-01.txt 9 1. Status of this Memo 11 This memo provides information for the Internet community. It does not 12 specify an Internet standard of any kind. Distribution of this memo is 13 unlimited. 15 This document is an Internet-Draft and is in full conformance with all 16 provisions of Section 10 of RFC2026. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any time. 24 It is inappropriate to use Internet-Drafts as reference material or to 25 cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 2. Abstract 35 This document defines an LDAP Control for Directory Synchronization. 36 This control allows a client to request changes made to a directory replica 37 since a state of that replica identified by an opaque "cookie." This 38 control is implemented by the Active Directory feature of Microsoft 39 Windows 2000 Server. It is intended that other members of the Internet 40 community be able to use this control if desired. 42 3. Overview 44 Many organizations today store information on multiple directories. 45 For example, e-mail accounts and related information might be stored in 46 one directory; information about files and networking in another; 47 certain data, such as financial or human resource data in yet another 48 directory. Such an environment is referred to as a mixed-directory 49 environment. 51 The LDAP Control for Directory Synchronization provides a method for 52 dissimilar directories to share pertinent information. 54 4. Directory Synchronization Control 56 This control MUST only be used with a SearchRequest message. A 57 server MUST ignore the control if used with any other message 58 unless the criticality field is set to True, in which case the 59 entire operation MUST fail and MUST instead return the resultCode 60 unsupportedCriticalExtension as per section 4.1.12 of [RFC 2251]. 61 The server MUST list that it recognizes this control in the 62 supportedControl attribute in the root DSE. 64 The replication control is included in the searchRequest and 65 searchResultDone messages as part of the server controls field of 66 the LDAPMessage. The structure of this control is as follows: 68 Repl Control ::= SEQUENCE { 69 controlType 1.2.840.113556.1.4.841 70 controlValue replControlValue 71 criticality TRUE 72 } 74 The replControlValue in the SearchRequest is an OCTET STRING wrapping 75 the BER-encoded version of the following: 77 realReplControlValue ::= SEQUENCE { 78 parentsFirst integer 79 maxReturnlength integer 80 cookie OCTET STRING 81 } 83 parentsFirst: Setting parentsFirst to one ensures that all parents of 84 the children come before their children. 86 maxReturnlength: This specifies the maximum length in bytes to be 87 returned in the control response. This can be used to limit the amount 88 of data returned. This field must be set to a number above zero for 89 date to returned. 91 cookie: The cookie is an implementation specific opaque OCTET STRING 92 that is updated by the directory during each search request. It allows 93 the Dirsync control to read changes incrementally from the directory. 94 The very first time the control is created, the cookie should be 95 encoded as a NULL string with 0 length. 97 The replControlValue in the SearchResponse is an OCTET STRING wrapping 98 the BER-encoded version of the following: 100 realReplControlValue ::= SEQUENCE { 101 Flag integer 102 maxReturnlength integer 103 cookie OCTET STRING 104 } 106 flag: If flag is set to a non-zero value, it implies that there is more 107 data to retrieve. 109 maxReturnlength: This specifies the maximum length in bytes to be 110 returned in the control response. 112 cookie: This is the opaque cookie returned by the server to be used by 113 the client in subsequent searches. 115 5. Provider/Consumer Interaction 117 Server implementations (Providers) MUST return a globally unique 118 identification (GUID) for each object returned with the Directory 119 Synchronization control. This unique identifier MUST be returned 120 in the value of the DN with the DNWithString Syntax (defined in 121 section 5.2). If the DN is static then the DN can be used for unique 122 identification of the object. Consumer applications MUST take the 123 first value in the DN value set (encoded with the DNWithString syntax) 124 to be the GUID to the object. A GUID MUST be matched to the existing 125 objects on the consumer store. The values returned by the Provider 126 server MUST be applied to the object, with the exception of reserved 127 attributes defined in section 5.1. A GUID with no corresponding object 128 on the consumer store MUST be treated as a new object. 130 The LDAP Directory Synchronization control allows a client to request 131 changes made to a directory replica since a state of that replica 132 identified by an opaque "cookie." 134 A typical consumer (dirsync agent) will work on a schedule to read 135 changes from a supplier directory and write changes to a consumer 136 directory. On this schedule the client will wake up, read the opaque 137 cookie from a file, then enter a loop passing the current cookie to 138 the supplier server and receive changes back. It computes updates 139 to perform to the consumer directory based on the changes, and makes 140 these updates. When these updates are committed it writes the new 141 cookie to the file, and goes around the loop again if the setting of 142 the 'flag' returned by the supplier states that there is additional 143 information to be retreieved. If not it exits the loop and sleeps 144 until the next scheduled cycle. 146 When the control is initally run the client should send the 147 cookie encoded as a NULL string with 0 length. 149 The server will respond to each Directory Synchronization search 150 request with the changes since the last control was run (based on 151 the cookie provided by the client) and a cookie to be stored and used 152 by the client during the next synchronization cycle. The client MUST 153 consider the cookie to be an opaque structure and not make any 154 assumptions about its internal organization or value. The client may 155 reuse older cookies, however this search request may result in changes 156 being reported that have already been received by the client. 158 In the case of a complete server failure, a client may pass a cookie 159 generated by one directory server to a different directory server 160 hosting the same directory partition. This may result in the new 161 server reporting changes already reported by the old server. The 162 new server MAY report a full synchronization (all objects and 163 attributes in the search request). The client MUST be able to handle 164 changes already reported being returned again. 166 The directory server SHOULD limit use of this control to entities 167 explicitly granted permission to use this control. The directory 168 server SHOULD return objects and attributes based on the filters of 169 the search request and based on the permissions of the authenticated 170 entity. 172 Server implementations may have other restraints on which containers 173 or objects may or may not use the Directory Synchronization control. 174 If a client attempts to run the Directory Synchronization control on 175 an object or container that does not support the control, the server 176 SHOULD return the error unwillingToPerform(53). 178 5.1 Interpretation of Advanced Directory Operations 180 Certain directory changes and operations are not defined in an LDAP 181 search response. The Directory Synchronization control will interpret 182 these operations using defined object attributes. The directory 183 synchronization consumer MUST understand and support these operations. 185 A Provider MUST return an attribute with a NULL value to signify that 186 attribute has been removed. A DirSync consumer MUST interpret this as 187 an attribute removal and process this accordingly. 189 If an object is deleted it will be returned in the search response 190 message with the 'isDeleted' attribute set to value True. The client 191 MUST interpret this as an object deletion and MUST perform the proper 192 operation on the consumer directory. 194 isDeleted 195 (1.2.840.113556.1.2.48 NAME 'isDeleted' 196 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7) 198 If an object is moved or renamed the attribute 'RDN' will be returned 199 with the value set to the new object name. The client MUST interpret 200 this as an object rename and perform the proper operation on the 201 consumer directory. 203 RDN 204 (1.2.840.113556.1.4.1 NAME 'RDN' 205 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15) 207 5.2 DN With String Syntax 209 ( 1.2.840.113556.1.4.904 DESC 'DNWithString') 210 Values with this string are encoded as follows: 212 DNWithString = StringTag ':' Count ':' String ':' DN 214 OctetTag = 'S' | 's' 216 Count = positive decimal number, counting number of bytes in 217 String 219 String = 220 // Note: the number 221 of bytes in the string encoding of the String is Count. 223 DN = 225 As an example, the string encoding of the combination of 226 "GUID=89876" and DC=foobar,DC=Com is 228 S:10:GUID=89876:DC=foobar,DC=Com 230 As an example, the string encoding of the combination of XYZ (where 231 X, Y, and Z all have two byte UTF-8 encodings) and 232 DC=foobar,DC=Com is 234 S:6:XYZ:DC=foobar,DC=Com 236 Note: Characters with multibyte UTF-8 encodings contribute more 237 than one to the count 239 6. Security Considerations 241 This document details a method for retreiving information from a 242 directory server using an LDAP control. Server implementations utilizing 243 this control SHOULD implement security mechanisms as defined in 244 Authentication Methods for LDAP [AuthMeth]. 246 Each implementation should take appropriate measures to insure that only 247 authorized entities can utilize this control. 249 7. References 251 [RFC 2251] 252 M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 253 (v3)", RFC 2251, December 1997. 1997. 255 [AuthMeth] 256 M. Wahl, H. Alvestrand, J. Hodges, R. Morgan. "Authentication 257 Methods for LDAP". INTERNET-DRAFT, Work In Progress. 258 draft-ietf-ldapext-authmeth-03.txt 260 [RFC 2119] 261 Bradner, S., "Key words for use in RFCs to Indicate Requirement 262 Levels," 263 RFC 2119, Harvard University, March 1997. 265 8. Authors Address 267 Michael P. Armijo 268 One Microsoft Way 269 Redmond, WA 270 98052 271 USA 273 (425)882-8080 274 micharm@microsoft.com 276 Expires May 12, 2000