8 draft-legg-ldap-gser-abnf-06.txt Adacel Technologies
9 Intended Category: Informational May 7, 2003
12 Common Elements of GSER Encodings
14 Copyright (C) The Internet Society (2003). All Rights Reserved.
19 This document is an Internet-Draft and is in full conformance with
20 all provisions of Section 10 of RFC2026.
22 Internet-Drafts are working documents of the Internet Engineering
23 Task Force (IETF), its areas, and its working groups. Note that
24 other groups may also distribute working documents as
27 Internet-Drafts are draft documents valid for a maximum of six months
28 and may be updated, replaced, or obsoleted by other documents at any
29 time. It is inappropriate to use Internet-Drafts as reference
30 material or to cite them other than as "work in progress".
32 The list of current Internet-Drafts can be accessed at
33 http://www.ietf.org/ietf/1id-abstracts.txt
35 The list of Internet-Draft Shadow Directories can be accessed at
36 http://www.ietf.org/shadow.html.
38 Distribution of this document is unlimited. Comments should be sent
39 to the LDAPEXT working group mailing list <ietf-ldapext@netscape.com>
42 This Internet-Draft expires on 7 November 2003.
47 The Generic String Encoding Rules (GSER) describe a human readable
48 text encoding for an ASN.1 value of any ASN.1 type. Specifications
49 making use of GSER may wish to provide an equivalent ABNF description
50 of the GSER encoding for a particular ASN.1 type as a convenience for
51 implementors. This document supports such specifications by
52 providing equivalent ABNF for the GSER encodings for ASN.1 types
53 commonly occuring in Lightweight Directory Access Protocol (LDAP)
58 Legg Expires 7 November 2003 [Page 1]
60 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
65 1. Table of Contents ............................................. 2
66 2. Introduction .................................................. 2
67 3. Conventions ................................................... 2
68 4. Separators .................................................... 2
69 5. ASN.1 Built-in Types .......................................... 3
70 6. ASN.1 Restricted String Types ................................. 7
71 7. Directory ASN.1 Types ......................................... 9
72 8. Security Considerations ....................................... 10
73 9. Normative References .......................................... 11
74 10. Informative References ....................................... 11
75 11. Copyright Notice ............................................. 11
76 12. Author's Address ............................................. 12
81 The Generic String Encoding Rules (GSER) defined in [7] define a
82 human readable text encoding, based on ASN.1 [8] value notation, for
83 an ASN.1 value of any ASN.1 type. Specifications making use of GSER
84 may wish to provide a non-normative equivalent ABNF [3] description
85 of the GSER encoding for a particular ASN.1 type as a convenience for
86 implementors unfamiliar with ASN.1. This document supports such
87 specifications by providing equivalent ABNF for the GSER encodings
88 for ASN.1 types commonly occuring in LDAP [9] or X.500 [10] attribute
89 and assertion syntaxes, as well as equivalent ABNF for the GSER
90 encodings for the ASN.1 built-in types.
92 The ABNF given in this document does not replace or alter GSER in any
93 way. If there is a discrepancy between the ABNF specified here and
94 the encoding defined by GSER in [7] then [7] is to be taken as
100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
102 document are to be interpreted as described in RFC 2119 [1].
107 Certain separators are commonly used in constructing equivalent ABNF
108 for SET and SEQUENCE types.
110 sp = *%x20 ; zero, one or more space characters
114 Legg Expires 7 November 2003 [Page 2]
116 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
119 msp = 1*%x20 ; one or more space characters
123 The <sep> rule is used in the ABNF description of the encoding for
124 ASN.1 SET or SEQUENCE types where all the components are either
125 OPTIONAL or DEFAULT. It encodes to an empty string if and only if
126 the immediately preceding character in the encoding is "{", i.e. it
127 is only empty for the first optional component actually present in
128 the SET or SEQUENCE value being encoded.
131 5. ASN.1 Built-in Types
133 This section describes the GSER encoding of values of the ASN.1
134 built-in types, except for the restricted character string types.
136 The <BIT-STRING> rule describes the GSER encoding of values of the
137 BIT STRING type without a named bit list.
139 BIT-STRING = bstring / hstring
141 If the number of bits in a BIT STRING value is a multiple of four the
142 <hstring> form of <BIT-STRING> MAY be used. The <bstring> form of
143 <BIT-STRING> is used otherwise. The <bstring> rule encodes each bit
144 as the character "0" or "1" in order from the first bit to the last
145 bit. The <hstring> rule encodes each group of four bits as a
146 hexadecimal number where the first bit is the most significant. An
147 odd number of hexadecimal digits is permitted.
149 hstring = squote *hexadecimal-digit squote %x48 ; '...'H
150 hexadecimal-digit = %x30-39 / ; "0" to "9"
153 bstring = squote *binary-digit squote %x42 ; '...'B
154 binary-digit = "0" / "1"
156 squote = %x27 ; ' (single quote)
158 The <BOOLEAN> rule describes the GSER encoding of values of the
161 BOOLEAN = %x54.52.55.45 / ; "TRUE"
162 %x46.41.4C.53.45 ; "FALSE"
164 The <CHARACTER-STRING> rule describes the GSER encoding of values of
165 the associated type for the unrestricted CHARACTER STRING type.
170 Legg Expires 7 November 2003 [Page 3]
172 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
175 CHARACTER-STRING = "{" sp id-identification msp Identification ","
176 sp id-data-value msp OCTET-STRING
179 id-identification = %x69.64.65.6E.74.69.66.69.63.61.74.69.6F.6E
181 id-data-value = %x64.61.74.61.2D.76.61.6C.75.65 ; "data-value"
183 Identification = ( id-syntaxes ":" Syntaxes ) /
184 ( id-syntax ":" OBJECT-IDENTIFIER ) /
185 ( id-presentation-context-id ":" INTEGER ) /
186 ( id-context-negotiation ":"
187 ContextNegotiation ) /
188 ( id-transfer-syntax ":" OBJECT-IDENTIFIER ) /
189 ( id-fixed ":" NULL )
191 id-syntaxes = %x73.79.6E.74.61.78.65.73
193 id-syntax = %x73.79.6E.74.61.78 ; "syntax"
194 id-presentation-context-id = %x70.72.65.73.65.6E.74.61.74.69.6F.6E
195 %x2D.63.6F.6E.74.65.78.74.2D.69.64
196 ; "presentation-context-id"
197 id-context-negotiation = %x63.6F.6E.74.65.78.74.2D.6E.65.67.6F
198 %x74.69.61.74.69.6F.6E
199 ; "context-negotiation"
200 id-transfer-syntax = %x74.72.61.6E.73.66.65.72.2D.73.79.6E
201 %x74.61.78 ; "transfer-syntax"
202 id-fixed = %x66.69.78.65.64 ; "fixed"
204 Syntaxes = "{" sp id-abstract msp OBJECT-IDENTIFIER ","
205 sp id-transfer msp OBJECT-IDENTIFIER
207 id-abstract = %x61.62.73.74.72.61.63.74 ; "abstract"
208 id-transfer = %x74.72.61.6E.73.66.65.72 ; "transfer"
210 ContextNegotiation = "{" sp id-presentation-context-id msp
212 sp id-transfer-syntax msp
216 The <INTEGER> rule describes the GSER encoding of values of the
217 INTEGER type without a named number list. The <INTEGER-0-MAX> rule
218 describes the GSER encoding of values of the constrained type INTEGER
219 (0..MAX). The <INTEGER-1-MAX> rule describes the GSER encoding of
220 values of the constrained type INTEGER (1..MAX).
222 INTEGER = "0" / positive-number / ("-" positive-number)
226 Legg Expires 7 November 2003 [Page 4]
228 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
231 INTEGER-0-MAX = "0" / positive-number
232 INTEGER-1-MAX = positive-number
233 positive-number = non-zero-digit *decimal-digit
234 decimal-digit = %x30-39 ; "0" to "9"
235 non-zero-digit = %x31-39 ; "1" to "9"
237 The <EMBEDDED-PDV> rule describes the GSER encoding of values of the
238 associated type for the EMBEDDED PDV type.
240 EMBEDDED-PDV = "{" sp id-identification msp Identification ","
241 sp id-data-value msp OCTET-STRING
244 The <EXTERNAL> rule describes the GSER encoding of values of the
245 associated type for the EXTERNAL type.
247 EXTERNAL = "{" [ sp id-direct-reference msp
248 OBJECT-IDENTIFIER "," ]
249 [ sp id-indirect-reference msp INTEGER "," ]
250 [ sp id-data-value-descriptor msp
251 ObjectDescriptor "," ]
252 sp id-encoding msp Encoding
255 id-direct-reference = %x64.69.72.65.63.74.2D.72.65.66.65.72
258 id-indirect-reference = %x69.6E.64.69.72.65.63.74.2D.72.65.66
260 ; "indirect-reference"
261 id-data-value-descriptor = %x64.61.74.61.2D.76.61.6C.75.65.2D.64
262 %x65.73.63.72.69.70.74.6F.72
263 ; "data-value-descriptor"
264 id-encoding = %x65.6E.63.6F.64.69.6E.67
267 Encoding = ( id-single-ASN1-type ":" Value ) /
268 ( id-octet-aligned ":" OCTET-STRING ) /
269 ( id-arbitrary ":" BIT-STRING )
271 id-single-ASN1-type = %x73.69.6E.67.6C.65.2D.41.53.4E.31.2D.74.79
274 id-octet-aligned = %x6F.63.74.65.74.2D.61.6C.69.67.6E.65.64
276 id-arbitrary = %x61.72.62.69.74.72.61.72.79
282 Legg Expires 7 November 2003 [Page 5]
284 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
287 The <Value> rule is defined in [7]. It represents the GSER encoding
288 of a single value of the ASN.1 type identified by the direct-
289 reference and/or indirect-reference components.
291 The <NULL> rule describes the GSER encoding of values of the NULL
294 NULL = %x4E.55.4C.4C ; "NULL"
296 The <OBJECT-IDENTIFIER> rule describes the GSER encoding of values of
297 the OBJECT IDENTIFIER type.
299 OBJECT-IDENTIFIER = numeric-oid / descr
300 numeric-oid = oid-component 1*( "." oid-component )
301 oid-component = "0" / positive-number
303 An OBJECT IDENTIFIER value is encoded using either the dotted decimal
304 representation or an object descriptor name, i.e. <descr>. The
305 <descr> rule is described in [4]. An object descriptor name is
306 potentially ambiguous and should be used with care.
308 The <OCTET-STRING> rule describes the GSER encoding of values of the
311 OCTET-STRING = hstring
313 The octets are encoded in order from the first octet to the last
314 octet. Each octet is encoded as a pair of hexadecimal digits where
315 the first digit corresponds to the four most significant bits of the
316 octet. If the hexadecimal string does not have an even number of
317 digits the four least significant bits in the last octet are assumed
320 The <REAL> rule describes the GSER encoding of values of the REAL
324 / PLUS-INFINITY ; positive infinity
325 / MINUS-INFINITY ; negative infinity
326 / realnumber ; positive base 10 REAL value
327 / ( "-" realnumber ) ; negative base 10 REAL value
328 / real-sequence-value ; non-zero base 2 or 10 REAL value
330 PLUS-INFINITY = %x50.4C.55.53.2D.49.4E.46.49.4E.49.54.59
332 MINUS-INFINITY = %x4D.49.4E.55.53.2D.49.4E.46.49.4E.49.54.59
338 Legg Expires 7 November 2003 [Page 6]
340 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
343 realnumber = mantissa exponent
344 mantissa = (positive-number [ "." *decimal-digit ])
345 / ( "0." *("0") positive-number )
346 exponent = "E" ( "0" / ([ "-" ] positive-number))
348 real-sequence-value = "{" sp id-mantissa msp INTEGER ","
349 sp id-base msp ( "2" / "10" ) ","
350 sp id-exponent msp INTEGER sp "}"
351 id-mantissa = %x6D.61.6E.74.69.73.73.61 ; "mantissa"
352 id-base = %x62.61.73.65 ; "base"
353 id-exponent = %x65.78.70.6F.6E.65.6E.74 ; "exponent"
355 A value of the REAL type MUST be encoded as "0" if it is zero.
357 The <RELATIVE-OID> rule describes the GSER encoding of values of the
360 RELATIVE-OID = oid-component *( "." oid-component )
363 6. ASN.1 Restricted String Types
365 This section describes the GSER encoding of values of the ASN.1
366 restricted character string types. The characters of a value of a
367 restricted character string type are always encoded as a UTF8
368 character string between double quotes. For some of the ASN.1 string
369 types this requires a translation to or from the UTF8 encoding. Some
370 of the ASN.1 string types permit only a subset of the characters
371 representable in UTF8. Any double quote characters in the character
372 string, where allowed by the character set, are escaped by being
375 The <UTF8String> rule describes the GSER encoding of values of the
376 UTF8String type. The characters of this string type do not require
377 any translation before being encoded.
379 UTF8String = StringValue
380 StringValue = dquote *SafeUTF8Character dquote
382 dquote = %x22 ; " (double quote)
384 SafeUTF8Character = %x00-21 / %x23-7F / ; ASCII minus dquote
385 dquote dquote / ; escaped double quote
386 %xC0-DF %x80-BF / ; 2 byte UTF8 character
387 %xE0-EF 2(%x80-BF) / ; 3 byte UTF8 character
388 %xF0-F7 3(%x80-BF) / ; 4 byte UTF8 character
389 %xF8-FB 4(%x80-BF) / ; 5 byte UTF8 character
390 %xFC-FD 5(%x80-BF) ; 6 byte UTF8 character
394 Legg Expires 7 November 2003 [Page 7]
396 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
399 The <NumericString>, <PrintableString>, <VisibleString>,
400 <ISO646String>, <IA5String>, <GeneralizedTime> and <UTCTime> rules
401 describe the GSER encoding of values of the correspondingly named
402 ASN.1 types. The characters of these string types are compatible
403 with UTF8 and do not require any translation before being encoded.
404 The GeneralizedTime and UTCTime types use the VisibleString character
405 set, but have a strictly defined format.
407 NumericString = dquote *(decimal-digit / space) dquote
410 PrintableString = dquote *PrintableCharacter dquote
411 PrintableCharacter = decimal-digit / space
415 / %x2B-2F ; + , - . /
420 ISO646String = VisibleString
421 VisibleString = dquote *SafeVisibleCharacter dquote
422 SafeVisibleCharacter = %x20-21
423 / %x23-7E ; printable ASCII minus dquote
424 / dquote dquote ; escaped double quote
426 IA5String = dquote *SafeIA5Character dquote
427 SafeIA5Character = %x00-21 / %x23-7F ; ASCII minus dquote
428 / dquote dquote ; escaped double quote
430 century = 2(%x30-39) ; "00" to "99"
431 year = 2(%x30-39) ; "00" to "99"
432 month = ( %x30 %x31-39 ) ; "01" (January) to "09"
433 / ( %x31 %x30-32 ) ; "10" to "12"
434 day = ( %x30 %x31-39 ) ; "01" to "09"
435 / ( %x31-32 %x30-39 ) ; "10" to "29"
436 / ( %x32 %x30-31 ) ; "30" to "31"
437 hour = ( %x30-31 %x30-39 ) / ( %x32 %x30-33 ) ; "00" to "23"
438 minute = %x30-36 %x30-39 ; "00" to "59"
439 second = %x30-36 %x30-39 ; "00" to "59"
441 UTCTime = dquote year month day hour minute [ second ]
442 [ %x5A / u-differential ] dquote
443 u-differential = ( "-" / "+" ) hour minute
444 GeneralizedTime = dquote century year month day hour
445 [ minute [ second ] ] [ fraction ]
446 [ %x5A / g-differential ] dquote
450 Legg Expires 7 November 2003 [Page 8]
452 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
455 fraction = ( "." / "," ) 1*(%x30-39)
456 g-differential = ( "-" / "+" ) hour [ minute ]
458 The <BMPString> and <UniversalString> rules describe the GSER
459 encoding of values of the BMPString and UniversalString types
460 respectively. BMPString (UCS-2) and UniversalString (UCS-4) values
461 are translated into UTF8 [6] character strings before being encoded
462 according to <StringValue>.
464 BMPString = StringValue
465 UniversalString = StringValue
467 The <TeletexString>, <T61String>, <VideotexString>, <GraphicString>,
468 <GeneralString> and <ObjectDescriptor> rules describe the GSER
469 encoding of values of the correspondingly named ASN.1 types. Values
470 of these string types are translated into UTF8 character strings
471 before being encoded according to <StringValue>. The
472 ObjectDescriptor type uses the GraphicString character set.
474 TeletexString = StringValue
475 T61String = StringValue
476 VideotexString = StringValue
477 GraphicString = StringValue
478 GeneralString = StringValue
479 ObjectDescriptor = GraphicString
482 7. Directory ASN.1 Types
484 This section describes the GSER encoding of values of selected ASN.1
485 types defined for LDAP and X.500. The ABNF rule names beginning with
486 uppercase letters describe the GSER encoding of values of the ASN.1
487 type with the same name.
489 AttributeType = OBJECT-IDENTIFIER
491 The characters of a DirectoryString are translated into UTF8
492 characters as required before being encoded between double quotes
493 with any embedded double quotes escaped by being repeated.
495 DirectoryString = StringValue /
496 ( id-teletexString ":" TeletexString ) /
497 ( id-printableString ":" PrintableString ) /
498 ( id-bmpString ":" BMPString ) /
499 ( id-universalString ":" UniversalString ) /
500 ( id-uTF8String ":" UTF8String )
502 id-teletexString = %x74.65.6C.65.74.65.78.53.74.72.69.6E.67
506 Legg Expires 7 November 2003 [Page 9]
508 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
512 id-printableString = %x70.72.69.6E.74.61.62.6C.65
513 %x53.74.72.69.6E.67 ; "printableString"
514 id-bmpString = %x62.6D.70.53.74.72.69.6E.67 ; "bmpString"
515 id-universalString = %x75.6E.69.76.65.72.73.61.6C
516 %x53.74.72.69.6E.67 ; "universalString"
517 id-uTF8String = %x75.54.46.38.53.74.72.69.6E.67
520 The <RDNSequence> rule describes the GSER encoding of values of the
521 RDNSequence type, which is syntactically equivalent to the
522 DistinguishedName and LocalName types. The <RDNSequence> rule
523 encodes a name as an LDAPDN character string between double quotes.
524 The character string is first derived according to the
525 <distinguishedName> rule in Section 3 of [5], and then it is encoded
526 between double quotes with any embedded double quotes escaped by
529 DistinguishedName = RDNSequence
530 LocalName = RDNSequence
531 RDNSequence = dquote *SafeUTF8Character dquote
533 The <RelativeDistinguishedName> rule describes the GSER encoding of
534 values of the RelativeDistinguishedName type that are not part of an
535 RDNSequence value. The <RelativeDistinguishedName> rule encodes an
536 RDN as a double quoted string containing the RDN as it would appear
537 in an LDAPDN character string. The character string is first derived
538 according to the <name-component> rule in Section 3 of [6], and then
539 any embedded double quote characters are escaped by being repeated.
540 This resulting string is output between double quotes.
542 RelativeDistinguishedName = dquote *SafeUTF8Character dquote
544 The <ORAddress> rule encodes an X.400 address as an IA5 character
545 string between double quotes. The character string is first derived
546 according to Section 4.1 of [2], and then any embedded double quotes
547 are escaped by being repeated. This resulting string is output
548 between double quotes.
550 ORAddress = dquote *SafeIA5Character dquote
553 8. Security Considerations
555 This document contains an alternative description of parts of the
556 Generic String Encoding Rules, but does not replace or alter GSER in
557 any way. For the full security implications of using GSER see the
558 Security Considerations section of [7].
562 Legg Expires 7 November 2003 [Page 10]
564 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
567 9. Normative References
569 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
570 Levels", BCP 14, RFC 2119, March 1997.
572 [2] Kille, S., "MIXER (Mime Internet X.400 Enhanced Relay): Mapping
573 between X.400 and RFC 822/MIME", RFC 2156, January 1998.
575 [3] Crocker, D. and P. Overell, "Augmented BNF for Syntax
576 Specifications: ABNF", RFC 2234, November 1997.
578 [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
579 Directory Access Protocol (v3): Attribute Syntax Definitions",
580 RFC 2252, December 1997.
582 [5] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access
583 Protocol (v3): UTF-8 String Representation of Distinguished
584 Names", RFC 2253, December 1997.
586 [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
589 [7] Legg, S., "Generic String Encoding Rules for ASN.1 Types",
590 draft-legg-ldap-gser-xx.txt, a work in progress, May 2003.
592 [8] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998
593 Information Technology - Abstract Syntax Notation One (ASN.1):
594 Specification of basic notation
597 10. Informative References
599 [9] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol
600 (v3): Technical Specification", RFC 3377, September 2002.
602 [10] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994,
603 Information Technology - Open Systems Interconnection - The
604 Directory: Overview of concepts, models and services
609 Copyright (C) The Internet Society (2003). All Rights Reserved.
611 This document and translations of it may be copied and furnished to
612 others, and derivative works that comment on or otherwise explain it
613 or assist in its implementation may be prepared, copied, published
614 and distributed, in whole or in part, without restriction of any
618 Legg Expires 7 November 2003 [Page 11]
620 INTERNET-DRAFT Common Elements of GSER Encodings May 7, 2003
623 kind, provided that the above copyright notice and this paragraph are
624 included on all such copies and derivative works. However, this
625 document itself may not be modified in any way, such as by removing
626 the copyright notice or references to the Internet Society or other
627 Internet organizations, except as needed for the purpose of
628 developing Internet standards in which case the procedures for
629 copyrights defined in the Internet Standards process must be
630 followed, or as required to translate it into languages other than
633 The limited permissions granted above are perpetual and will not be
634 revoked by the Internet Society or its successors or assigns.
636 This document and the information contained herein is provided on an
637 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
638 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
639 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
640 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
641 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
647 Adacel Technologies Ltd.
649 Brighton, Victoria 3186
652 Phone: +61 3 8530 7710
654 EMail: steven.legg@adacel.com.au
674 Legg Expires 7 November 2003 [Page 12]