8 draft-legg-ldap-gser-abnf-04.txt Adacel Technologies
9 Intended Category: Informational August 19, 2002
12 Common Elements of GSER Encodings
14 Copyright (C) The Internet Society (2002). 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 19 February 2002.
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 19 February 2002 [Page 1]
60 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
65 1. Abstract .................................................... 1
66 2. Table of Contents ........................................... 2
67 3. Introduction ................................................ 2
68 4. Conventions ................................................. 2
69 5. Separators .................................................. 2
70 6. ASN.1 Built-in Types ........................................ 3
71 7. ASN.1 Restricted String Types ............................... 7
72 8. Directory ASN.1 Types ....................................... 8
73 9. Security Considerations ..................................... 9
74 10. Normative References ....................................... 10
75 11. Informative References ..................................... 10
76 12. Copyright Notice ........................................... 10
77 13. Author's Address ........................................... 11
82 The Generic String Encoding Rules (GSER) defined in [9] define a
83 human readable text encoding, based on ASN.1 [7] value notation, for
84 an ASN.1 value of any ASN.1 type. Specifications making use of GSER
85 may wish to provide a non-normative equivalent ABNF [3] description
86 of the GSER encoding for a particular ASN.1 type as a convenience for
87 implementors unfamiliar with ASN.1. This document supports such
88 specifications by providing equivalent ABNF for the GSER encodings
89 for ASN.1 types commonly occuring in LDAP [8] or X.500 [10] attribute
90 and assertion syntaxes, as well as equivalent ABNF for the GSER
91 encodings for the ASN.1 built-in types.
93 The ABNF given in this document does not replace or alter GSER in any
94 way. If there is a discrepancy between the ABNF specified here and
95 the encoding defined by GSER in [9] then [9] is to be taken as
101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
103 document are to be interpreted as described in RFC 2119 [1].
108 Certain separators are commonly used in constructing equivalent ABNF
109 for SET and SEQUENCE types.
114 Legg Expires 19 February 2002 [Page 2]
116 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
119 sp = *%x20 ; zero, one or more space characters
120 msp = 1*%x20 ; one or more space characters
124 The <sep> rule is used in the ABNF description of the encoding for
125 ASN.1 SET or SEQUENCE types where all the components are either
126 OPTIONAL or DEFAULT. It encodes to an empty string if and only if
127 the immediately preceding character in the encoding is "{", i.e. it
128 is only empty for the first optional component actually present in
129 the SET or SEQUENCE value being encoded.
132 6. ASN.1 Built-in Types
134 This section describes the GSER encoding of values of the ASN.1
135 built-in types, except for the restricted character string types.
137 The <BIT-STRING> rule describes the GSER encoding of values of the
138 BIT STRING type without a named bit list.
140 BIT-STRING = bstring / hstring
142 If the number of bits in a BIT STRING value is a multiple of four the
143 <hstring> form of <BIT-STRING> MAY be used. The <bstring> form of
144 <BIT-STRING> is used otherwise. The <bstring> rule encodes each bit
145 as the character "0" or "1" in order from the first bit to the last
146 bit. The <hstring> rule encodes each group of four bits as a
147 hexadecimal number where the first bit is the most significant. An
148 odd number of hexadecimal digits is permitted.
150 hstring = squote *hexadecimal-digit squote %x48 ; '...'H
151 hexadecimal-digit = %x30-39 / ; "0" to "9"
154 bstring = squote *binary-digit squote %x42 ; '...'B
155 binary-digit = "0" / "1"
157 squote = %x27 ; ' (single quote)
159 The <BOOLEAN> rule describes the GSER encoding of values of the
162 BOOLEAN = %x54.52.55.45 / ; "TRUE"
163 %x46.41.4C.53.45 ; "FALSE"
165 The <CHARACTER-STRING> rule describes the GSER encoding of values of
166 the associated type for the unrestricted CHARACTER STRING type.
170 Legg Expires 19 February 2002 [Page 3]
172 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
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 19 February 2002 [Page 4]
228 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
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-descriptor msp
243 "," sp id-data-value msp OCTET-STRING
246 id-data-value-descriptor = %x64.61.74.61.2D.76.61.6C.75.65.2D.64
247 %x65.73.63.72.69.70.74.6F.72
248 ; "data-value-descriptor"
250 The <EXTERNAL> rule describes the GSER encoding of values of the
251 associated type for the EXTERNAL type.
253 EXTERNAL = "{" sp id-identification msp E-Identification
254 [ "," sp id-data-value-descriptor msp
256 "," sp id-data-value msp OCTET-STRING
259 E-Identification = ( id-syntax ":" OBJECT-IDENTIFIER ) /
260 ( id-presentation-context-id ":" INTEGER ) /
261 ( id-context-negotiation ":"
264 The <NULL> rule describes the GSER encoding of values of the NULL
267 NULL = %x4E.55.4C.4C ; "NULL"
269 The <OBJECT-IDENTIFIER> rule describes the GSER encoding of values of
270 the OBJECT IDENTIFIER type.
272 OBJECT-IDENTIFIER = numeric-oid / descr
273 numeric-oid = oid-component 1*( "." oid-component )
274 oid-component = "0" / positive-number
276 An OBJECT IDENTIFIER value is encoded using either the dotted decimal
277 representation or an object descriptor name, i.e. <descr>. The
278 <descr> rule is described in [4]. An object descriptor name is
282 Legg Expires 19 February 2002 [Page 5]
284 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
287 potentially ambiguous and should be used with care.
289 The <OCTET-STRING> rule describes the GSER encoding of values of the
292 OCTET-STRING = hstring
294 The octets are encoded in order from the first octet to the last
295 octet. Each octet is encoded as a pair of hexadecimal digits where
296 the first digit corresponds to the four most significant bits of the
297 octet. If the hexadecimal string does not have an even number of
298 digits the four least significant bits in the last octet are assumed
301 The <REAL> rule describes the GSER encoding of values of the REAL
305 / PLUS-INFINITY ; positive infinity
306 / MINUS-INFINITY ; negative infinity
307 / realnumber ; positive base 10 REAL value
308 / ( "-" realnumber ) ; negative base 10 REAL value
309 / real-sequence-value ; non-zero base 2 or 10 REAL value
311 PLUS-INFINITY = %x50.4C.55.53.2D.49.4E.46.49.4E.49.54.59
313 MINUS-INFINITY = %x4D.49.4E.55.53.2D.49.4E.46.49.4E.49.54.59
316 realnumber = mantissa exponent
317 mantissa = (positive-number [ "." *decimal-digit ])
318 / ( "0." *("0") positive-number )
319 exponent = "E" ( "0" / ([ "-" ] positive-number))
321 real-sequence-value = "{" sp id-mantissa msp INTEGER ","
322 sp id-base msp ( "2" / "10" ) ","
323 sp id-exponent msp INTEGER sp "}"
324 id-mantissa = %x6D.61.6E.74.69.73.73.61 ; "mantissa"
325 id-base = %x62.61.73.65 ; "base"
326 id-exponent = %x65.78.70.6F.6E.65.6E.74 ; "exponent"
328 A value of the REAL type MUST be encoded as "0" if it is zero.
330 The <RELATIVE-OID> rule describes the GSER encoding of values of the
333 RELATIVE-OID = oid-component *( "." oid-component )
338 Legg Expires 19 February 2002 [Page 6]
340 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
343 7. ASN.1 Restricted String Types
345 This section describes the GSER encoding of values of the ASN.1
346 restricted character string types. The characters of a value of a
347 restricted character string type are always encoded as a UTF8
348 character string between double quotes. For some of the ASN.1 string
349 types this requires a translation to or form the UTF8 encoding. Some
350 of the ASN.1 string types permit only a subset of the characters
351 representable in UTF8. Any double quote characters in the character
352 string, where allowed by the character set, are escaped by being
355 The <UTF8String> rule describes the GSER encoding of values of the
356 UTF8String type. The characters of this string type do not require
357 any translation before being encoded.
359 UTF8String = StringValue
360 StringValue = dquote *SafeUTF8Character dquote
362 dquote = %x22 ; " (double quote)
364 SafeUTF8Character = %x00-21 / %x23-7F / ; ASCII minus dquote
365 dquote dquote / ; escaped double quote
366 %xC0-DF %x80-BF / ; 2 byte UTF8 character
367 %xE0-EF 2(%x80-BF) / ; 3 byte UTF8 character
368 %xF0-F7 3(%x80-BF) / ; 4 byte UTF8 character
369 %xF8-FB 4(%x80-BF) / ; 5 byte UTF8 character
370 %xFC-FD 5(%x80-BF) ; 6 byte UTF8 character
372 The <NumericString>, <PrintableString>, <VisibleString>,
373 <ISO646String>, <IA5String>, <GeneralizedTime> and <UTCTime> rules
374 describe the GSER encoding of values of the correspondingly named
375 ASN.1 types. The characters of these string types are compatible
376 with UTF8 and do not require any translation before being encoded.
377 The GeneralizedTime and UTCTime types use the VisibleString character
378 set, but have a strictly defined format.
380 NumericString = dquote *(decimal-digit / space) dquote
383 PrintableString = dquote *PrintableCharacter dquote
384 PrintableCharacter = decimal-digit / space
388 / %x2B-2F ; + , - . /
394 Legg Expires 19 February 2002 [Page 7]
396 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
401 ISO646String = VisibleString
402 VisibleString = dquote *SafeVisibleCharacter dquote
403 SafeVisibleCharacter = %x20-21
404 / %x23-7E ; printable ASCII minus dquote
405 / dquote dquote ; escaped double quote
407 IA5String = dquote *SafeIA5Character dquote
408 SafeIA5Character = %x00-21 / %x23-7F ; ASCII minus dquote
409 / dquote dquote ; escaped double quote
411 UTCTime = dquote 10(decimal-digit) [2(decimal-digit)]
412 [ "Z" / u-differential ] dquote
413 u-differential = ( "-" / "+" ) 4(decimal-digit)
414 GeneralizedTime = dquote 10(decimal-digit)
416 fraction [ "Z" / g-differential ] dquote
417 fraction = ( "." / "," ) 1*decimal-digit
418 g-differential = ( "-" / "+" ) 1*2(2(decimal-digit))
420 The <BMPString> and <UniversalString> rules describe the GSER
421 encoding of values of the BMPString and UniversalString types
422 respectively. BMPString (UCS-2) and UniversalString (UCS-4) values
423 are translated into UTF8 [6] character strings before being encoded
424 according to <StringValue>.
426 BMPString = StringValue
427 UniversalString = StringValue
429 The <TeletexString>, <T61String>, <VideotexString>, <GraphicString>,
430 <GeneralString> and <ObjectDescriptor> rules describe the GSER
431 encoding of values of the correspondingly named ASN.1 types. Values
432 of these string types are translated into UTF8 character strings
433 before being encoded according to <StringValue>. The
434 ObjectDescriptor type uses the GraphicString character set.
436 TeletexString = StringValue
437 T61String = StringValue
438 VideotexString = StringValue
439 GraphicString = StringValue
440 GeneralString = StringValue
441 ObjectDescriptor = GraphicString
444 8. Directory ASN.1 Types
446 This section describes the GSER encoding of values of selected ASN.1
450 Legg Expires 19 February 2002 [Page 8]
452 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
455 types defined for LDAP and X.500. The ABNF rule names beginning with
456 uppercase letters describe the GSER encoding of values of the ASN.1
457 type with the same name.
459 AttributeType = OBJECT-IDENTIFIER
461 The characters of a DirectoryString are translated into UTF8
462 characters as required before being encoded between double quotes
463 with any embedded double quotes escaped by being repeated.
465 DirectoryString = dquote *SafeUTF8Character dquote
467 The <RDNSequence> rule describes the GSER encoding of values of the
468 RDNSequence type, which is syntactically equivalent to the
469 DistinguishedName and LocalName types. The <RDNSequence> rule
470 encodes a name as an LDAPDN character string between double quotes.
471 The character string is first derived according to the
472 <distinguishedName> rule in Section 3 of [5], and then it is encoded
473 between double quotes with any embedded double quotes escaped by
476 DistinguishedName = RDNSequence
477 LocalName = RDNSequence
478 RDNSequence = dquote *SafeUTF8Character dquote
480 The <RelativeDistinguishedName> rule describes the GSER encoding of
481 values of the RelativeDistinguishedName type that are not part of an
482 RDNSequence value. The <RelativeDistinguishedName> rule encodes an
483 RDN as a double quoted string containing the RDN as it would appear
484 in an LDAPDN character string. The character string is first derived
485 according to the <name-component> rule in Section 3 of [6], and then
486 any embedded double quote characters are escaped by being repeated.
487 This resulting string is output between double quotes.
489 RelativeDistinguishedName = dquote *SafeUTF8Character dquote
491 The <ORAddress> rule encodes an X.400 address as an IA5 character
492 string between double quotes. The character string is first derived
493 according to Section 4.1 of [2], and then any embedded double quotes
494 are escaped by being repeated. This resulting string is output
495 between double quotes.
497 ORAddress = dquote *SafeIA5Character dquote
500 9. Security Considerations
502 GSER, and therefore the ABNF encodings described in this document, do
506 Legg Expires 19 February 2002 [Page 9]
508 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
511 not necessarily enable the exact octet encoding of values of the
512 TeletexString, VideotexString, GraphicString or GeneralString types
513 to be reconstructed, so a transformation from DER to GSER and back to
514 DER may not reproduce the original DER encoding. This has
515 consequences for the verification of digital signatures.
518 10. Normative References
520 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
521 Levels", BCP 14, RFC 2119, March 1997.
523 [2] Kille, S., "MIXER (Mime Internet X.400 Enhanced Relay): Mapping
524 between X.400 and RFC 822/MIME", RFC 2156, January 1998.
526 [3] Crocker, D. and P. Overell, "Augmented BNF for Syntax
527 Specifications: ABNF", RFC 2234, November 1997.
529 [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight
530 Directory Access Protocol (v3): Attribute Syntax Definitions",
531 RFC 2252, December 1997.
533 [5] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access
534 Protocol (v3): UTF-8 String Representation of Distinguished
535 Names", RFC 2253, December 1997.
537 [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC
540 [7] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998
541 Information Technology - Abstract Syntax Notation One (ASN.1):
542 Specification of basic notation
545 11. Informative References
547 [8] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
548 Protocol (v3)", RFC 2251, December 1997.
550 [9] Legg, S., "Generic String Encoding Rules for ASN.1 Types",
551 draft-legg-ldap-gser-xx.txt, a work in progress, August 2002.
553 [10] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994,
554 Information Technology - Open Systems Interconnection - The
555 Directory: Overview of concepts, models and services
562 Legg Expires 19 February 2002 [Page 10]
564 INTERNET-DRAFT Common Elements of GSER Encodings August 19, 2002
567 Copyright (C) The Internet Society (2002). All Rights Reserved.
569 This document and translations of it may be copied and furnished to
570 others, and derivative works that comment on or otherwise explain it
571 or assist in its implementation may be prepared, copied, published
572 and distributed, in whole or in part, without restriction of any
573 kind, provided that the above copyright notice and this paragraph are
574 included on all such copies and derivative works. However, this
575 document itself may not be modified in any way, such as by removing
576 the copyright notice or references to the Internet Society or other
577 Internet organizations, except as needed for the purpose of
578 developing Internet standards in which case the procedures for
579 copyrights defined in the Internet Standards process must be
580 followed, or as required to translate it into languages other than
583 The limited permissions granted above are perpetual and will not be
584 revoked by the Internet Society or its successors or assigns.
586 This document and the information contained herein is provided on an
587 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
588 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
589 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
590 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
591 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
597 Adacel Technologies Ltd.
598 405-409 Ferntree Gully Road
599 Mount Waverley, Victoria 3149
602 Phone: +61 3 9451 2107
604 EMail: steven.legg@adacel.com.au
618 Legg Expires 19 February 2002 [Page 11]