idnits 2.17.1 draft-good-ldap-ldif-02.txt: 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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard 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 18 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([2], [3], [4], [5], [6], [7], [8], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == 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 exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: attrval-spec = attribute-description ((":") / (":" *SPACE value) / ("::" *SPACE base64-value) / (":<" *SPACE url)) url = ; (See Note 6, below) attribute-description = value = 1*safe-initval *safe ; (See Note 9, below) safe = safe-initval = base64-value = -- 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 (1 February 1999) is 9216 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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: '3' is defined on line 482, but no explicit reference was found in the text == Unused Reference: '5' is defined on line 491, but no explicit reference was found in the text == Unused Reference: '6' is defined on line 497, but no explicit reference was found in the text == Outdated reference: A later version (-07) exists of draft-ietf-asid-mime-direct-06 ** Obsolete normative reference: RFC 822 (ref. '2') (Obsoleted by RFC 2822) ** Obsolete normative reference: RFC 1779 (ref. '3') (Obsoleted by RFC 2253, RFC 3494) ** Obsolete normative reference: RFC 2251 (ref. '4') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) ** Obsolete normative reference: RFC 1521 (ref. '5') (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) ** Obsolete normative reference: RFC 1738 (ref. '6') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. '8' Summary: 13 errors (**), 0 flaws (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 LDAP Data Interchange Format (LDIF) Gordon Good 3 INTERNET-DRAFT Netscape Communications 4 1 February 1999 6 The LDAP Data Interchange Format (LDIF) - Technical Specification 7 Filename: draft-good-ldap-ldif-02.txt 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet- 22 Drafts as reference material or to cite them other than as 23 "work in progress." 25 To view the list Internet-Draft Shadow Directories, see 26 http://www.ietf.org/shadow.html. 28 This Internet Draft expires August 1st, 1999. 30 Abstract 32 This document describes a file format suitable for describing 33 directory information or modifications made to directory information. 34 The file format, known as LDIF, for LDAP Data Interchange Format, is 35 typically used to import and export directory information between 36 LDAP-based directory servers, or to describe a set of changes which 37 are to be applied to a directory. 39 Background and Intended Usage 41 There are a number of situations where a common interchange format is 42 desirable. For example, one might wish to export a copy of the 43 contents of a directory server to a file, move that file to a 44 different machine, and import the contents into a second directory 45 server. 47 Additionally, by using a well-defined interchange format, development 48 of data import tools from legacy systems is facilitated. A fairly 49 simple set of tools written in awk or perl can, for example, convert 50 a database of personnel information into an LDIF file, which can then 51 be imported into a directory server, regardless of the internal 52 database representation the target directory server uses. 54 The LDIF format was originally developed and used in the University 55 of Michigan LDAP implementation. The first use of LDIF was in 56 describing directory entries. Later, the format was expanded to 57 allow representation of changes to directory entries. 59 Relationship to the application/directory MIME content-type: 61 The application/directory MIME content-type [1] is a general 62 framework and format for conveying directory information, and is 63 independent of any particular directory service. It is preferred, in 64 most cases, to LDIF, for conveying directory information. The LDIF 65 format is a simpler format which is perhaps easier to create, and 66 also may be used, as noted, to describe a set of changes to be 67 applied to a directory. 69 The key words "MUST", "MAY", and "SHOULD" used in this document are 70 to be interpreted as described in [7]. 72 Definition of the LDAP Data Interchange Format 74 The LDIF format is used to convey directory information, or a 75 description of a set of changes made to directory entries. An LDIF 76 file consists of a series of records separated by line separators. A 77 record consists of a sequence of lines describing a directory entry, 78 or a sequence of lines describing a set of changes to a single 79 directory entry. An LDIF file specifies a set of directory entries, 80 or a set of changes to be applied to directory entries, but not both. 82 There is a one-to-one correlation between LDAP operations which 83 modify the directory (add, delete, modify, and modrdn), and the types 84 of changerecords described below ("add", "delete", "modify", and 85 "modrdn" or "moddn"). This correspondence is intentional, and 86 permits a straightforward translation from LDIF changerecords to 87 protocol operations. 89 Formal Syntax Definition of LDIF 91 The following definition uses the augmented Backus-Naur Form 92 specified in RFC 822 [2]. 94 ldif-file = ldif-content / ldif-changes 95 ldif-content = 0,1*(version-spec 1*SEP) 96 ldif-attrval-record *(1*SEP ldif-attrval-record) 97 ldif-changes = 0,1*(version-spec 1*SEP) 98 ldif-change-record *(1*SEP ldif-change-record) 99 ldif-attrval-record = dn-spec SEP 1*(attrval-spec SEP) 100 ldif-change-record = dn-spec SEP 1*(changerecord SEP) 102 version-spec = "version:" *SPACE version-number 103 version-number = 1*DIGIT ; version-number MUST be "1" for the 104 ; LDIF format described in this document. 106 dn-spec = ("dn:" *SPACE dn) / ("dn::" *SPACE base64-dn) 107 dn = 108 base64-dn = 110 rdn = 112 base64-rdn = 115 attrval-spec = attribute-description ((":") / (":" *SPACE value) / 116 ("::" *SPACE base64-value) / 117 (":<" *SPACE url)) 118 url = 119 ; (See Note 6, below) 120 attribute-description = 123 value = 1*safe-initval *safe 124 ; (See Note 9, below) 125 safe = 126 safe-initval = 129 base64-value = 131 changerecord = change-add / change-delete / change-modify / 132 change-moddn 133 change-add = "changetype:" *SPACE "add" 1*(SEP attrval-spec) 134 change-delete = "changetype:" *SPACE "delete" 135 change-moddn = "changetype:" *SPACE ("modrdn" / "moddn") SEP 136 ("newrdn:" *SPACE rdn / 137 "newrdn::" *SPACE base-64-rdn) SEP 138 "deleteoldrdn:" *SPACE ("0" / "1") 139 0,1*(SEP (("newsuperior:" *SPACE dn) / 140 ("newsuperior::" *SPACE base-64-dn))) 141 change-modify = "changetype:" *SPACE "modify" 1*(SEP mod-spec) 142 mod-spec = mod-add-spec / mod-delete-spec / mod-replace-spec 143 mod-add-spec = "add:" *SPACE attribute-description 144 1*(SEP attrval-spec) SEP "-" 145 mod-delete-spec = "delete:" *SPACE attribute-description 146 *(SEP attrval-spec) SEP "-" 147 mod-replace-spec = "replace:" *SPACE attribute-description 148 *(SEP attrval-spec) SEP "-" 149 SPACE = 150 SEP = (CR LF / LF) 151 CR = 152 LF = 153 DIGIT = 155 Notes on LDIF Syntax 157 1) The version number is optional. If absent, version 0 is assumed, 158 which corresponds to the version of LDIF supported by the University 159 of Michigan ldap-3.3 reference implementation [8]. For the LDIF 160 format described in this document, the version number MUST be "1". 162 2) Any non-comment line in an LDIF file MAY be wrapped by inserting a 163 line separator (SEP) and a SPACE. Any line which begins with a 164 single space MUST be treated as a continuation of the previous line. 165 When joining folded lines, exactly one space character at the 166 beginning of each continued line must be discarded. 168 3) Any line which begins with a pound-sign ("#", ASCII 35) is a 169 comment line, and MUST be ignored when parsing an LDIF file. 171 4) Any dn or value which contains characters other than those defined 172 as "safe," or begins with a character other than those defined as 173 "safe-initval", above, MUST be base-64 encoded. Other values MAY be 174 base-64 encoded. 176 5) To represent a zero-length attribute value, use an attrval-spec of 177 "attribute-description:". For example, "seeAlso:" represents a 178 zero-length "seeAlso" attribute value. 180 6) When a URL is specified in an attrval-spec, the following 181 conventions apply: 182 a) Implementations SHOULD support the file:// URL format. The 183 contents of the referenced file are to be included verbatim 184 in the interpreted output of the LDIF file. 185 b) Implementations MAY support other URL formats. The semantics 186 associated with each supported URL will be documented in 187 an associated Applicability Statement. 189 7) While it is permissible for character values larger than 126 to be 190 contained in an attribute value, implementations SHOULD base-64 191 encode any value which contains such characters when generating LDIF. 192 However, implementations MAY leave the values unencoded. This 193 relaxation is designed to allow editing of LDIF files containing 194 UTF-8 data. 196 8) Attribute values contained in LDIF files represent directory data, 197 and therefore MUST be valid UTF-8 strings. Implementations which read 198 LDIF MAY interpret files in which the values are stored in some other 199 character set encoding, but implementations MUST NOT generate LDIF 200 content which does not contain valid UTF-8 data. 202 9) Values that end with SPACE SHOULD be base-64 encoded. 204 Differences from previous versions of this document 206 Differences between draft-ietf-asid-ldif-00.txt and draft-ietf-asid- 207 ldif-01.txt 209 1) The BNF has been modified to explicitly disallow ldif content and 210 change records in the same file. In other words, a given LDIF file 211 is either a series of directory entries, or a series of 212 modifications. An LDIF file MUST NOT contain both types of records. 214 2) External references are now URLs, instead of simple filenames. 216 3) The BNF has been modified to allow base-64-encoded distinguished 217 names. 219 4) Multiple separators are now permitted between records. 221 Differences between draft-ietf-asid-ldif-01.txt and draft-ietf-asid- 222 ldif-02.txt 224 1) The BNF has been modified such that a simple attribute name 225 ("attrname") has been replaced with an "attribute-description" as 226 defined in the LDAPv3 protocol document [4]. This permits language 227 codes and other attribute options to be carried in an LDIF file. 229 2) A new option, "charset", may be used in attribute descriptions. 230 This facilitates multi-lingual character set conversion. 232 3) The definition of the "safe" and "safe-initval" productions has 233 been relaxed to allow non-ASCII characters with values greater than 234 126. This permits more natural expression of character sets such as 235 Latin-1 in LDIF files. 237 Differences between draft-ietf-asid-ldif-02.txt and draft-good-ldap- 238 ldif-00.txt 240 1) The "charset-option" and "charset-name" productions were removed 241 from the BNF, due to objections within the working group. UTF-8 is 242 the only character set which may be used in LDIF. 244 2) Examples were reworked to reflect the above change, and to include 245 an example of a non-western language represented in UTF-8. 247 Differences between draft-ietf-good-ldif-00.txt and draft-good-ldap- 248 ldif-01.txt 250 1) Added version identifiers to the examples - they were missing. 252 2) Clarified that LDIF file must use UTF-8. 254 Differences between draft-ietf-good-ldif-01.txt and draft-good-ldap- 255 ldif-02.txt 257 1) Added a recommendation that values ending in SPACE should be 258 base-64 encoded. 260 2) Clarified the procedure for joining folded lines. 262 3) Updated header to reflect new IETF I-D guidelines. 264 Examples of LDAP Data Interchange Format 266 Example 1: An simple LDAP file with two entries 268 version: 1 269 dn: cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US 270 objectclass: top 271 objectclass: person 272 objectclass: organizationalPerson 273 cn: Barbara Jensen 274 cn: Barbara J Jensen 275 cn: Babs Jensen 276 sn: Jensen 277 uid: bjensen 278 telephonenumber: +1 408 555 1212 279 description: A big sailing fan. 281 dn: cn=Bjorn Jensen, ou=Accounting, o=Ace Industry, c=US 282 objectclass: top 283 objectclass: person 284 objectclass: organizationalPerson 285 cn: Bjorn Jensen 286 sn: Jensen 287 telephonenumber: +1 408 555 1212 289 Example 2: A file containing an entry with a folded attribute value 291 version: 1 292 dn:cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US 293 objectclass:top 294 objectclass:person 295 objectclass:organizationalPerson 296 cn:Barbara Jensen 297 cn:Barbara J Jensen 298 cn:Babs Jensen 299 sn:Jensen 300 uid:bjensen 301 telephonenumber:+1 408 555 1212 302 description:Babs is a big sailing fan, and travels extensively in search of 303 perfect sailing conditions. 304 title:Product Manager, Rod and Reel Division 306 Example 3: A file containing a base-64-encoded value 308 version: 1 309 dn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US 310 objectclass: top 311 objectclass: person 312 objectclass: organizationalPerson 313 cn: Gern Jensen 314 cn: Gern O Jensen 315 sn: Jensen 316 uid: gernj 317 telephonenumber: +1 408 555 1212 318 description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVlIGlzIGJ 319 hc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdGVyIGluIGl0ICh 320 hIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQgb3V0IG1vcmUu 322 Example 4: A file containing an entries with UTF-8-encoded attribute 323 values, including language tags. Comments indicate the contents 324 of UTF-8-encoded attributes and distinguished names. 326 version: 1 327 dn:: b3U95Za25qWt6YOoLG89QWlyaXVz 328 # dn:: ou=,o=Airius 329 objectclass: top 330 objectclass: organizationalUnit 331 ou:: 5Za25qWt6YOo 332 # ou:: 333 ou;lang-ja:: 5Za25qWt6YOo 334 # ou;lang-ja:: 335 ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2 336 # ou;lang-ja:: 337 ou;lang-en: Sales 338 description: Japanese office 340 dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz 341 # dn:: uid=,ou=,o=Airius 342 userpassword: {SHA}O3HSv1MusyL4kTjP+HKI5uxuNoM= 343 objectclass: top 344 objectclass: person 345 objectclass: organizationalPerson 346 objectclass: inetOrgPerson 347 uid: rogasawara 348 mail: rogasawara@airius.co.jp 349 givenname;lang-ja:: 44Ot44OJ44OL44O8 350 # givenname;lang-ja:: 351 sn;lang-ja:: 5bCP56yg5Y6f 352 # sn;lang-ja:: 353 cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA== 354 # cn;lang-ja:: 355 title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw== 356 # title;lang-ja:: 357 preferredlanguage: ja 358 givenname:: 44Ot44OJ44OL44O8 359 # givenname:: 360 sn:: 5bCP56yg5Y6f 361 # sn:: 362 cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA== 363 # cn:: 364 title:: 5Za25qWt6YOoIOmDqOmVtw== 365 # title:: 366 givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8 367 # givenname;lang-ja;phonetic:: 368 369 sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ 370 # sn;lang-ja;phonetic:: 371 cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA== 372 # cn;lang-ja;phonetic:: 373 title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg== 374 # title;lang-ja;phonetic:: 375 givenname;lang-en: Rodney 376 sn;lang-en: Ogasawara 377 cn;lang-en: Rodney Ogasawara 378 title;lang-en: Sales, Director 379 Example 5: A file containing a reference to an external file 381 version: 1 382 dn: cn=Horatio Jensen, ou=Product Testing, o=Ace Industry, c=US 383 objectclass: top 384 objectclass: person 385 objectclass: organizationalPerson 386 cn: Horatio Jensen 387 cn: Horatio N Jensen 388 sn: Jensen 389 uid: hjensen 390 telephonenumber: +1 408 555 1212 391 jpegphoto:< file:///usr/local/directory/photos/hjensen.jpg 393 Example 6: A file containing a series of change records and comments 395 version: 1 396 # Add a new entry 397 dn: cn=Fiona Jensen, ou=Marketing, o=Ace Industry, c=US 398 changetype: add 399 objectclass: top 400 objectclass: person 401 objectclass: organizationalPerson 402 cn: Fiona Jensen 403 sn: Jensen 404 uid: fiona 405 telephonenumber: +1 408 555 1212 406 jpegphoto:< file:///usr/local/directory/photos/fiona.jpg 408 # Delete an existing entry 409 dn: cn=Robert Jensen, ou=Marketing, o=Ace Industry, c=US 410 changetype: delete 412 # Modify an entry's relative distinguished name 413 dn: cn=Paul Jensen, ou=Product Development, o=Ace Industry, c=US 414 changetype: modrdn 415 newrdn: cn=Paula Jensen 416 deleteoldrdn: 1 418 # Rename an entry and move all of its children to a new location in 419 # the directory tree (only implemented by LDAPv3 servers). 420 dn: ou=PD Accountants, ou=Product Development, o=Ace Industry, c=US 421 changetype: modrdn 422 newrdn: ou=Product Development Accountants 423 deleteoldrdn: 0 424 newsuperior: ou=Accounting, o=Ace Industry, c=US 426 # Modify an entry: add an additional value to the postaladdress attribute, 427 # completely delete the description attribute, replace the telephonenumber 428 # attribute with two values, and delete a specific value from the 429 # facsimiletelephonenumber attribute 430 dn: cn=Paula Jensen, ou=Product Development, o=Ace Industry, c=US 431 changetype: modify 432 add: postaladdress 433 postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086 434 - 435 delete: description 436 - 437 replace: telephonenumber 438 telephonenumber: +1 408 555 1234 439 telephonenumber: +1 408 555 5678 440 - 441 delete: facsimiletelephonenumber 442 facsimiletelephonenumber: +1 408 555 9876 443 - 445 Security Considerations 447 Given typical directory applications, an LDIF file is likely to 448 contain sensitive personal data. Appropriate measures should be 449 taken to protect the privacy of those persons whose data is contained 450 in an LDIF file. 452 Since ":<" directives can cause external content to be included when 453 processing an LDIF file, one should be cautious of accepting LDIF 454 files from external sources. A "trojan" LDIF file could name a file 455 with sensitive contents and cause it to be included in a directory 456 entry, which a hostile entity could read via LDAP. 458 LDIF does not provide any method for carrying authentication 459 information with an LDIF file. Users of LDIF files must take care to 460 verify the integrity of an LDIF file received from an external 461 source. 463 Acknowledgments 465 The LDAP Interchange Format was developed as part of the University 466 of Michigan LDAP reference implementation, and was developed by Tim 467 Howes, Mark Smith, and Gordon Good. It is based in part upon work 468 supported by the National Science Foundation under Grant No. NCR- 469 9416667. 471 References 473 [1] Howes, T., Smith, M., "A MIME Content-Type for Directory Infor- 474 mation", INTERNET-DRAFT draft-ietf-asid-mime-direct-06.txt, 475 Netscape Communications Corp., 478 [2] Crocker, D.H., "Standard for the Format of ARPA Internet Text 479 Messages", RFC 822, University of Delaware, August 1982, 480 482 [3] Kille, S., "A String Representation of Distinguished Names", RFC 483 1779, ISODE Consortium, March 1995, 484 486 [4] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access 487 Protocol (v3)", RFC 2251, Critical Angle, Inc., ISODE Consor- 488 tium, Netscape Communications Corp., July, 1997, 489 491 [5] Borenstein, N., Freed, N., "MIME (Multipurpose Internet Mail 492 Extensions) Part One: Mechanisms for Specifying and Describing 493 the Format of Internet Message Bodies", section 5.2, "Base64 494 Content-Transfer-Encoding", RFC 1521, Bellcore, Innosoft, 495 December 1993, 497 [6] T. Berners-Lee, L. Masinter, M. McCahill, "Uniform Resource 498 Locators (URL)", CERN, Xerox Corporation, University of Min- 499 nesota, Request for Comment (RFC) 1738, December 1994, 500 502 [7] S. Bradner, "Key Words for use in RFCs to Indicate Requirement 503 Levels", Harvard University, RFC 2119, March 1997, 504 506 [8] The SLAPD and SLURPD Administrators Guide. University of Michi- 507 gan, April 1996. 510 Author's Address 512 Gordon Good 513 Netscape Communications Corp. 514 501 E. Middlefield Rd. 515 Mailstop MV068 516 Mountain View, CA 94043, USA 517 Phone: +1 650 937-3825 518 EMail: ggood@netscape.com 519 This Internet Draft expires August 1st, 1999.