ldif-utf8
view proposal.txt @ 0:b49e8e2fc0ac
Original rfc2849.
| author | Yves dorfsman <yves@zioup.com> |
|---|---|
| date | Tue Mar 10 19:49:43 2009 -0600 |
| parents | |
| children | d307d875966f |
line source
7 Network Working Group G. Good
8 Request for Comments: 2849 iPlanet e-commerce Solutions
9 Category: Standards Track June 2000
12 The LDAP Data Interchange Format (LDIF) - Technical Specification
14 Status of this Memo
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
22 Copyright Notice
24 Copyright (C) The Internet Society (2000). All Rights Reserved.
26 Abstract
28 This document describes a file format suitable for describing
29 directory information or modifications made to directory information.
30 The file format, known as LDIF, for LDAP Data Interchange Format, is
31 typically used to import and export directory information between
32 LDAP-based directory servers, or to describe a set of changes which
33 are to be applied to a directory.
35 Background and Intended Usage
37 There are a number of situations where a common interchange format is
38 desirable. For example, one might wish to export a copy of the
39 contents of a directory server to a file, move that file to a
40 different machine, and import the contents into a second directory
41 server.
43 Additionally, by using a well-defined interchange format, development
44 of data import tools from legacy systems is facilitated. A fairly
45 simple set of tools written in awk or perl can, for example, convert
46 a database of personnel information into an LDIF file. This file can
47 then be imported into a directory server, regardless of the internal
48 database representation the target directory server uses.
50 The LDIF format was originally developed and used in the University
51 of Michigan LDAP implementation. The first use of LDIF was in
52 describing directory entries. Later, the format was expanded to
53 allow representation of changes to directory entries.
55 Relationship to the application/directory MIME content-type:
57 The application/directory MIME content-type [1] is a general
58 framework and format for conveying directory information, and is
59 independent of any particular directory service. The LDIF format is
60 a simpler format which is perhaps easier to create, and may also be
61 used, as noted, to describe a set of changes to be applied to a
62 directory.
64 The key words "MUST", "MUST NOT", "MAY", "SHOULD", and "SHOULD NOT"
65 used in this document are to be interpreted as described in [7].
67 Definition of the LDAP Data Interchange Format
69 The LDIF format is used to convey directory information, or a
70 description of a set of changes made to directory entries. An LDIF
71 file consists of a series of records separated by line separators. A
72 record consists of a sequence of lines describing a directory entry,
73 or a sequence of lines describing a set of changes to a directory
74 entry. An LDIF file specifies a set of directory entries, or a set
75 of changes to be applied to directory entries, but not both.
77 There is a one-to-one correlation between LDAP operations that modify
78 the directory (add, delete, modify, and modrdn), and the types of
79 changerecords described below ("add", "delete", "modify", and
80 "modrdn" or "moddn"). This correspondence is intentional, and
81 permits a straightforward translation from LDIF changerecords to
82 protocol operations.
84 Formal Syntax Definition of LDIF
86 The following definition uses the augmented Backus-Naur Form
87 specified in RFC 2234 [2].
89 ldif-file = ldif-content / ldif-changes
91 ldif-content = version-spec 1*(1*SEP ldif-attrval-record)
93 ldif-changes = version-spec 1*(1*SEP ldif-change-record)
95 ldif-attrval-record = dn-spec SEP 1*attrval-spec
97 ldif-change-record = dn-spec SEP *control changerecord
99 version-spec = "version:" FILL version-number
101 version-number = 1*DIGIT
102 ; version-number MUST be "1" for the
103 ; LDIF format described in this document.
105 dn-spec = "dn:" (FILL distinguishedName /
106 ":" FILL base64-distinguishedName)
108 distinguishedName = SAFE-STRING
109 ; a distinguished name, as defined in [3]
111 base64-distinguishedName = BASE64-UTF8-STRING
112 ; a distinguishedName which has been base64
113 ; encoded (see note 10, below)
115 rdn = SAFE-STRING
116 ; a relative distinguished name, defined as
117 ; <name-component> in [3]
119 base64-rdn = BASE64-UTF8-STRING
120 ; an rdn which has been base64 encoded (see
121 ; note 10, below)
123 control = "control:" FILL ldap-oid ; controlType
124 0*1(1*SPACE ("true" / "false")) ; criticality
125 0*1(value-spec) ; controlValue
126 SEP
127 ; (See note 9, below)
129 ldap-oid = 1*DIGIT 0*1("." 1*DIGIT)
130 ; An LDAPOID, as defined in [4]
132 attrval-spec = AttributeDescription value-spec SEP
134 value-spec = ":" ( FILL 0*1(SAFE-STRING) /
135 ":" FILL (BASE64-STRING) /
136 "<" FILL url)
137 ; See notes 7 and 8, below
139 url = <a Uniform Resource Locator,
140 as defined in [6]>
141 ; (See Note 6, below)
143 AttributeDescription = AttributeType [";" options]
144 ; Definition taken from [4]
146 AttributeType = ldap-oid / (ALPHA *(attr-type-chars))
148 options = option / (option ";" options)
150 option = 1*opt-char
152 attr-type-chars = ALPHA / DIGIT / "-"
154 opt-char = attr-type-chars
156 changerecord = "changetype:" FILL
157 (change-add / change-delete /
158 change-modify / change-moddn)
160 change-add = "add" SEP 1*attrval-spec
162 change-delete = "delete" SEP
164 change-moddn = ("modrdn" / "moddn") SEP
165 "newrdn:" ( FILL rdn /
166 ":" FILL base64-rdn) SEP
167 "deleteoldrdn:" FILL ("0" / "1") SEP
168 0*1("newsuperior:"
169 ( FILL distinguishedName /
170 ":" FILL base64-distinguishedName) SEP)
172 change-modify = "modify" SEP *mod-spec
174 mod-spec = ("add:" / "delete:" / "replace:")
175 FILL AttributeDescription SEP
176 *attrval-spec
177 "-" SEP
179 SPACE = %x20
180 ; ASCII SP, space
182 FILL = *SPACE
184 SEP = (CR LF / LF)
186 CR = %x0D
187 ; ASCII CR, carriage return
189 LF = %x0A
190 ; ASCII LF, line feed
192 ALPHA = %x41-5A / %x61-7A
193 ; A-Z / a-z
195 DIGIT = %x30-39
196 ; 0-9
198 UTF8-1 = %x80-BF
200 UTF8-2 = %xC0-DF UTF8-1
202 UTF8-3 = %xE0-EF 2UTF8-1
204 UTF8-4 = %xF0-F7 3UTF8-1
206 UTF8-5 = %xF8-FB 4UTF8-1
208 UTF8-6 = %xFC-FD 5UTF8-1
210 SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-7F
211 ; any value <= 127 decimal except NUL, LF,
212 ; and CR
214 SAFE-INIT-CHAR = %x01-09 / %x0B-0C / %x0E-1F /
215 %x21-39 / %x3B / %x3D-7F
216 ; any value <= 127 except NUL, LF, CR,
217 ; SPACE, colon (":", ASCII 58 decimal)
218 ; and less-than ("<" , ASCII 60 decimal)
220 SAFE-STRING = [SAFE-INIT-CHAR *SAFE-CHAR]
222 UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 /
223 UTF8-4 / UTF8-5 / UTF8-6
225 UTF8-STRING = *UTF8-CHAR
227 BASE64-UTF8-STRING = BASE64-STRING
228 ; MUST be the base64 encoding of a
229 ; UTF8-STRING
231 BASE64-CHAR = %x2B / %x2F / %x30-39 / %x3D / %x41-5A /
232 %x61-7A
233 ; +, /, 0-9, =, A-Z, and a-z
234 ; as specified in [5]
236 BASE64-STRING = [*(BASE64-CHAR)]
239 Notes on LDIF Syntax
241 1) For the LDIF format described in this document, the version
242 number MUST be "1". If the version number is absent,
243 implementations MAY choose to interpret the contents as an
244 older LDIF file format, supported by the University of
245 Michigan ldap-3.3 implementation [8].
247 2) Any non-empty line, including comment lines, in an LDIF file
248 MAY be folded by inserting a line separator (SEP) and a SPACE.
249 Folding MUST NOT occur before the first character of the line.
250 In other words, folding a line into two lines, the first of
251 which is empty, is not permitted. Any line that begins with a
252 single space MUST be treated as a continuation of the previous
253 (non-empty) line. When joining folded lines, exactly one space
254 character at the beginning of each continued line must be
255 discarded. Implementations SHOULD NOT fold lines in the middle
256 of a multi-byte UTF-8 character.
258 3) Any line that begins with a pound-sign ("#", ASCII 35) is a
259 comment line, and MUST be ignored when parsing an LDIF file.
261 4) Any dn or rdn that contains characters other than those
262 defined as "SAFE-UTF8-CHAR", or begins with a character other
263 than those defined as "SAFE-INIT-UTF8-CHAR", above, MUST be
264 base-64 encoded. Other values MAY be base-64 encoded. Any
265 value that contains characters other than those defined as
266 "SAFE-CHAR", or begins with a character other than those
267 defined as "SAFE-INIT-CHAR", above, MUST be base-64 encoded.
268 Other values MAY be base-64 encoded.
270 5) When a zero-length attribute value is to be included directly
271 in an LDIF file, it MUST be represented as
272 AttributeDescription ":" FILL SEP. For example, "seeAlso:"
273 followed by a newline represents a zero-length "seeAlso"
274 attribute value. It is also permissible for the value
275 referred to by a URL to be of zero length.
277 6) When a URL is specified in an attrval-spec, the following
278 conventions apply:
280 a) Implementations SHOULD support the file:// URL format. The
281 contents of the referenced file are to be included verbatim
282 in the interpreted output of the LDIF file.
283 b) Implementations MAY support other URL formats. The
284 semantics associated with each supported URL will be
285 documented in an associated Applicability Statement.
287 7) Distinguished names, relative distinguished names, and
288 attribute values of DirectoryString syntax MUST be valid UTF-8
289 strings. Implementations that read LDIF MAY interpret files
290 in which these entities are stored in some other character set
291 encoding, but implementations MUST NOT generate LDIF content
292 which does not contain valid UTF-8 data.
294 8) Values or distinguished names that end with SPACE SHOULD be
295 base-64 encoded.
297 9) When controls are included in an LDIF file, implementations
298 MAY choose to ignore some or all of them. This may be
299 necessary if the changes described in the LDIF file are being
300 sent on an LDAPv2 connection (LDAPv2 does not support
301 controls), or the particular controls are not supported by the
302 remote server. If the criticality of a control is "true", then
303 the implementation MUST either include the control, or MUST
304 NOT send the operation to a remote server.
306 10) When an attrval-spec, distinguishedName, or rdn is base64-
307 encoded, the encoding rules specified in [5] are used with the
308 following exceptions: a) The requirement that base64 output
309 streams must be represented as lines of no more than 76
310 characters is removed. Lines in LDIF files may only be folded
311 according to the folding rules described in note 2, above. b)
312 Base64 strings in [5] may contain characters other than those
313 defined in BASE64-CHAR, and are ignored. LDIF does not permit
314 any extraneous characters, other than those used for line
315 folding.
317 Examples of LDAP Data Interchange Format
319 Example 1: An simple LDAP file with two entries
321 version: 1
322 dn: cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
323 objectclass: top
324 objectclass: person
325 objectclass: organizationalPerson
326 cn: Barbara Jensen
327 cn: Barbara J Jensen
328 cn: Babs Jensen
329 sn: Jensen
330 uid: bjensen
331 telephonenumber: +1 408 555 1212
332 description: A big sailing fan.
334 dn: cn=Bjorn Jensen, ou=Accounting, dc=airius, dc=com
335 objectclass: top
336 objectclass: person
337 objectclass: organizationalPerson
338 cn: Bjorn Jensen
339 sn: Jensen
340 telephonenumber: +1 408 555 1212
342 Example 2: A file containing an entry with a folded attribute value
344 version: 1
345 dn:cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com
346 objectclass:top
347 objectclass:person
348 objectclass:organizationalPerson
349 cn:Barbara Jensen
350 cn:Barbara J Jensen
351 cn:Babs Jensen
352 sn:Jensen
353 uid:bjensen
354 telephonenumber:+1 408 555 1212
355 description:Babs is a big sailing fan, and travels extensively in sea
356 rch of perfect sailing conditions.
357 title:Product Manager, Rod and Reel Division
359 Example 3: A file containing a base-64-encoded value
361 version: 1
362 dn: cn=Gern Jensen, ou=Product Testing, dc=airius, dc=com
363 objectclass: top
364 objectclass: person
365 objectclass: organizationalPerson
366 cn: Gern Jensen
367 cn: Gern O Jensen
368 sn: Jensen
369 uid: gernj
370 telephonenumber: +1 408 555 1212
371 description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVl
372 IGlzIGJhc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdG
373 VyIGluIGl0IChhIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQg
374 b3V0IG1vcmUu
376 Example 4: A file containing an entries with UTF-8-encoded attribute
377 values, including language tags. Comments indicate the contents
378 of UTF-8-encoded attributes and distinguished names.
380 version: 1
381 dn:: b3U95Za25qWt6YOoLG89QWlyaXVz
382 # dn:: ou=<JapaneseOU>,o=Airius
383 objectclass: top
384 objectclass: organizationalUnit
385 ou:: 5Za25qWt6YOo
386 # ou:: <JapaneseOU>
387 ou;lang-ja:: 5Za25qWt6YOo
388 # ou;lang-ja:: <JapaneseOU>
389 ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2
391 # ou;lang-ja:: <JapaneseOU_in_phonetic_representation>
392 ou;lang-en: Sales
393 description: Japanese office
395 dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz
396 # dn:: uid=<uid>,ou=<JapaneseOU>,o=Airius
397 userpassword: {SHA}O3HSv1MusyL4kTjP+HKI5uxuNoM=
398 objectclass: top
399 objectclass: person
400 objectclass: organizationalPerson
401 objectclass: inetOrgPerson
402 uid: rogasawara
403 mail: rogasawara@airius.co.jp
404 givenname;lang-ja:: 44Ot44OJ44OL44O8
405 # givenname;lang-ja:: <JapaneseGivenname>
406 sn;lang-ja:: 5bCP56yg5Y6f
407 # sn;lang-ja:: <JapaneseSn>
408 cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
409 # cn;lang-ja:: <JapaneseCn>
410 title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw==
411 # title;lang-ja:: <JapaneseTitle>
412 preferredlanguage: ja
413 givenname:: 44Ot44OJ44OL44O8
414 # givenname:: <JapaneseGivenname>
415 sn:: 5bCP56yg5Y6f
416 # sn:: <JapaneseSn>
417 cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA==
418 # cn:: <JapaneseCn>
419 title:: 5Za25qWt6YOoIOmDqOmVtw==
420 # title:: <JapaneseTitle>
421 givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8
422 # givenname;lang-ja;phonetic::
423 <JapaneseGivenname_in_phonetic_representation_kana>
424 sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ
425 # sn;lang-ja;phonetic:: <JapaneseSn_in_phonetic_representation_kana>
426 cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA==
427 # cn;lang-ja;phonetic:: <JapaneseCn_in_phonetic_representation_kana>
428 title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg==
429 # title;lang-ja;phonetic::
430 # <JapaneseTitle_in_phonetic_representation_kana>
431 givenname;lang-en: Rodney
432 sn;lang-en: Ogasawara
433 cn;lang-en: Rodney Ogasawara
434 title;lang-en: Sales, Director
436 Example 5: A file containing a reference to an external file
438 version: 1
439 dn: cn=Horatio Jensen, ou=Product Testing, dc=airius, dc=com
440 objectclass: top
441 objectclass: person
442 objectclass: organizationalPerson
443 cn: Horatio Jensen
445 cn: Horatio N Jensen
446 sn: Jensen
447 uid: hjensen
448 telephonenumber: +1 408 555 1212
449 jpegphoto:< file:///usr/local/directory/photos/hjensen.jpg
451 Example 6: A file containing a series of change records and comments
453 version: 1
454 # Add a new entry
455 dn: cn=Fiona Jensen, ou=Marketing, dc=airius, dc=com
456 changetype: add
457 objectclass: top
458 objectclass: person
459 objectclass: organizationalPerson
460 cn: Fiona Jensen
461 sn: Jensen
462 uid: fiona
463 telephonenumber: +1 408 555 1212
464 jpegphoto:< file:///usr/local/directory/photos/fiona.jpg
466 # Delete an existing entry
467 dn: cn=Robert Jensen, ou=Marketing, dc=airius, dc=com
468 changetype: delete
470 # Modify an entry's relative distinguished name
471 dn: cn=Paul Jensen, ou=Product Development, dc=airius, dc=com
472 changetype: modrdn
473 newrdn: cn=Paula Jensen
474 deleteoldrdn: 1
476 # Rename an entry and move all of its children to a new location in
477 # the directory tree (only implemented by LDAPv3 servers).
478 dn: ou=PD Accountants, ou=Product Development, dc=airius, dc=com
479 changetype: modrdn
480 newrdn: ou=Product Development Accountants
481 deleteoldrdn: 0
482 newsuperior: ou=Accounting, dc=airius, dc=com
484 # Modify an entry: add an additional value to the postaladdress
485 # attribute, completely delete the description attribute, replace
486 # the telephonenumber attribute with two values, and delete a specific
487 # value from the facsimiletelephonenumber attribute
488 dn: cn=Paula Jensen, ou=Product Development, dc=airius, dc=com
489 changetype: modify
490 add: postaladdress
491 postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086
492 -
494 delete: description
495 -
496 replace: telephonenumber
497 telephonenumber: +1 408 555 1234
498 telephonenumber: +1 408 555 5678
499 -
500 delete: facsimiletelephonenumber
501 facsimiletelephonenumber: +1 408 555 9876
502 -
504 # Modify an entry: replace the postaladdress attribute with an empty
505 # set of values (which will cause the attribute to be removed), and
506 # delete the entire description attribute. Note that the first will
507 # always succeed, while the second will only succeed if at least
508 # one value for the description attribute is present.
509 dn: cn=Ingrid Jensen, ou=Product Support, dc=airius, dc=com
510 changetype: modify
511 replace: postaladdress
512 -
513 delete: description
514 -
516 Example 7: An LDIF file containing a change record with a control
517 version: 1
518 # Delete an entry. The operation will attach the LDAPv3
519 # Tree Delete Control defined in [9]. The criticality
520 # field is "true" and the controlValue field is
521 # absent, as required by [9].
522 dn: ou=Product Development, dc=airius, dc=com
523 control: 1.2.840.113556.1.4.805 true
524 changetype: delete
526 Security Considerations
528 Given typical directory applications, an LDIF file is likely to
529 contain sensitive personal data. Appropriate measures should be
530 taken to protect the privacy of those persons whose data is contained
531 in an LDIF file.
533 Since ":<" directives can cause external content to be included when
534 processing an LDIF file, one should be cautious of accepting LDIF
535 files from external sources. A "trojan" LDIF file could name a file
536 with sensitive contents and cause it to be included in a directory
537 entry, which a hostile entity could read via LDAP.
539 LDIF does not provide any method for carrying authentication
540 information with an LDIF file. Users of LDIF files must take care to
541 verify the integrity of an LDIF file received from an external
542 source.
544 Acknowledgments
546 The LDAP Interchange Format was developed as part of the University
547 of Michigan LDAP reference implementation, and was developed by Tim
548 Howes, Mark Smith, and Gordon Good. It is based in part upon work
549 supported by the National Science Foundation under Grant No. NCR-
550 9416667.
552 Members of the IETF LDAP Extensions Working group provided many
553 helpful suggestions. In particular, Hallvard B. Furuseth of the
554 University of Oslo made many significant contributions to this
555 document, including a thorough review and rewrite of the BNF.
557 References
559 [1] Howes, T. and M. Smith, "A MIME Content-Type for Directory
560 Information", RFC 2425, September 1998.
562 [2] Crocker, D., and P. Overell, "Augmented BNF for Syntax
563 Specifications: ABNF", RFC 2234, November 1997.
565 [3] Wahl, M., Kille, S. and T. Howes, "A String Representation of
566 Distinguished Names", RFC 2253, December 1997.
568 [4] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
569 Protocol (v3)", RFC 2251, July 1997.
571 [5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
572 Extensions (MIME) Part One: Format of Internet Message Bodies",
573 RFC 2045, November 1996.
575 [6] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform
576 Resource Locators (URL)", RFC 1738, December 1994.
578 [7] Bradner, S., "Key Words for use in RFCs to Indicate Requirement
579 Levels", BCP 14, RFC 2119, March 1997.
581 [8] The SLAPD and SLURPD Administrators Guide. University of
582 Michigan, April 1996. <URL:
583 http://www.umich.edu/~dirsvcs/ldap/doc/guides/slapd/toc.html>
585 [9] M. P. Armijo, "Tree Delete Control", Work in Progress.
587 Author's Address
589 Gordon Good
590 iPlanet e-commerce Solutions
591 150 Network Circle
592 Mailstop USCA17-201
593 Santa Clara, CA 95054, USA
595 Phone: +1 408 276 4351
596 EMail: ggood@netscape.com
598 Full Copyright Statement
600 Copyright (C) The Internet Society (2000). All Rights Reserved.
602 This document and translations of it may be copied and furnished to
603 others, and derivative works that comment on or otherwise explain it
604 or assist in its implementation may be prepared, copied, published
605 and distributed, in whole or in part, without restriction of any
606 kind, provided that the above copyright notice and this paragraph are
607 included on all such copies and derivative works. However, this
608 document itself may not be modified in any way, such as by removing
609 the copyright notice or references to the Internet Society or other
610 Internet organizations, except as needed for the purpose of
611 developing Internet standards in which case the procedures for
612 copyrights defined in the Internet Standards process must be
613 followed, or as required to translate it into languages other than
614 English.
616 The limited permissions granted above are perpetual and will not be
617 revoked by the Internet Society or its successors or assigns.
619 This document and the information contained herein is provided on an
620 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
621 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
622 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
623 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
624 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
626 Acknowledgement
628 Funding for the RFC Editor function is currently provided by the
629 Internet Society.