1asn(n) ASN.1 processing asn(n)
2______________________________________________________________________________
6
8 asn - ASN.1 BER encoder/decoder
9
11 package require Tcl 8.4
12 package require asn ?0.8.3?
14 ::asn::asnSequence evalue...
16 ::asn::asnSequenceFromList elist
18 ::asn::asnSet evalue...
20 ::asn::asnSetFromList elist
22 ::asn::asnApplicationConstr appNumber evalue...
24 ::asn::asnApplication appNumber data
26 ::asn::asnChoice appNumber evalue...
28 ::asn::asnChoiceConstr appNumber evalue...
30 ::asn::asnInteger number
32 ::asn::asnEnumeration number
34 ::asn::asnBoolean bool
36 ::asn::asnContext context data
38 ::asn::asnContextConstr context evalue...
40 ::asn::asnObjectIdentifier idlist
42 ::asn::asnUTCTime utcstring
44 ::asn::asnNull
46 ::asn::asnBitString string
48 ::asn::asnOctetString string
50 ::asn::asnNumericString string
52 ::asn::asnPrintableString string
54 ::asn::asnIA5String string
56 ::asn::asnBMPString string
58 ::asn::asnUTF8String string
60 ::asn::asnString string
62 ::asn::defaultStringType ?type?
64 ::asn::asnPeekByte data_var byte_var
66 ::asn::asnGetLength data_var length_var
68 ::asn::asnGetResponse chan data_var
70 ::asn::asnGetInteger data_var int_var
72 ::asn::asnGetEnumeration data_var enum_var
74 ::asn::asnGetOctetString data_var string_var
76 ::asn::asnGetString data_var string_var ?type_var?
78 ::asn::asnGetNumericString data_var string_var
80 ::asn::asnGetPrintableString data_var string_var
82 ::asn::asnGetIA5String data_var string_var
84 ::asn::asnGetBMPString data_var string_var
86 ::asn::asnGetUTF8String data_var string_var
88 ::asn::asnGetUTCTime data_var utc_var
90 ::asn::asnGetBitString data_var bits_var
92 ::asn::asnGetObjectIdentifier data_var oid_var
94 ::asn::asnGetBoolean data_var bool_var
96 ::asn::asnGetNull data_var
98 ::asn::asnGetSequence data_var sequence_var
100 ::asn::asnGetSet data_var set_var
102 ::asn::asnGetApplication data_var appNumber_var ?content_var? ?encod‐
104 ingType_var?
105 ::asn::asnGetContext data_var contextNumber_var ?content_var? ?encod‐
107 ingType_var?
108 ::asn::asnPeekTag data_var tag_var tagtype_var constr_var
110 ::asn::asnTag tagnumber ?class? ?tagstyle?
112 ::asn::asnRetag data_var newTag
114_________________________________________________________________
116
118 The asn package provides partial de- and encoder commands for BER
119 encoded ASN.1 data. It can also be used for decoding DER, which is a
120 restricted subset of BER.
121 ASN.1 is a standard Abstract Syntax Notation, and BER are its Basic
123 Encoding Rules.
124 See http://asn1.elibel.tm.fr/en/standards/index.htm for more informa‐
126 tion about the standard.
127 Also see http://luca.ntop.org/Teaching/Appunti/asn1.html for A Layman's
129 Guide to a Subset of ASN.1, BER, and DER, an RSA Laboratories Technical
130 Note by Burton S. Kaliski Jr. (Revised November 1, 1993). A text ver‐
131 sion of this note is part of the module sources and should be read by
132 any implementor.
133
135 ENCODER
136 ::asn::asnSequence evalue...
137 Takes zero or more encoded values, packs them into an ASN
138 sequence and returns its encoded binary form.
139 ::asn::asnSequenceFromList elist
141 Takes a list of encoded values, packs them into an ASN sequence
142 and returns its encoded binary form.
143 ::asn::asnSet evalue...
145 Takes zero or more encoded values, packs them into an ASN set
146 and returns its encoded binary form.
147 ::asn::asnSetFromList elist
149 Takes a list of encoded values, packs them into an ASN set and
150 returns its encoded binary form.
151 ::asn::asnApplicationConstr appNumber evalue...
153 Takes zero or more encoded values, packs them into an ASN appli‐
154 cation construct and returns its encoded binary form.
155 ::asn::asnApplication appNumber data
157 Takes a single encoded value data, packs it into an ASN applica‐
158 tion construct and returns its encoded binary form.
159 ::asn::asnChoice appNumber evalue...
161 Takes zero or more encoded values, packs them into an ASN choice
162 construct and returns its encoded binary form.
163 ::asn::asnChoiceConstr appNumber evalue...
165 Takes zero or more encoded values, packs them into an ASN choice
166 construct and returns its encoded binary form.
167 ::asn::asnInteger number
169 Returns the encoded form of the specified integer number.
170 ::asn::asnEnumeration number
172 Returns the encoded form of the specified enumeration id number.
173 ::asn::asnBoolean bool
175 Returns the encoded form of the specified boolean value bool.
176 ::asn::asnContext context data
178 Takes an encoded value and packs it into a constructed value
179 with application tag, the context number.
180 ::asn::asnContextConstr context evalue...
182 Takes zero or more encoded values and packs them into a con‐
183 structed value with application tag, the context number.
184 ::asn::asnObjectIdentifier idlist
186 Takes a list of at least 2 integers describing an object identi‐
187 fier (OID) value, and returns the encoded value.
188 ::asn::asnUTCTime utcstring
190 Returns the encoded form of the specified UTC time string.
191 ::asn::asnNull
193 Returns the NULL encoding.
194 ::asn::asnBitString string
196 Returns the encoded form of the specified string.
197 ::asn::asnOctetString string
199 Returns the encoded form of the specified string.
200 ::asn::asnNumericString string
202 Returns the string encoded as ASN.1 NumericString. Raises an
203 error if the string contains characters other than decimal num‐
204 bers and space.
205 ::asn::asnPrintableString string
207 Returns the string encoding as ASN.1 PrintableString. Raises an
208 error if the string contains characters which are not allowed by
209 the Printable String datatype. The allowed characters are A-Z,
210 a-z, 0-9, space, apostrophe, colon, parentheses, plus, minus,
211 comma, period, forward slash, question mark, and the equals
212 sign.
213 ::asn::asnIA5String string
215 Returns the string encoded as ASN.1 IA5String. Raises an error
216 if the string contains any characters outside of the US-ASCII
217 range.
218 ::asn::asnBMPString string
220 Returns the string encoded as ASN.1 Basic Multilingual Plane
221 string (Which is essentialy big-endian UCS2).
222 ::asn::asnUTF8String string
224 Returns the string encoded as UTF8 String. Note that some legacy
225 applications such as Windows CryptoAPI do not like UTF8 strings.
226 Use BMPStrings if you are not sure.
227 ::asn::asnString string
229 Returns an encoded form of string, choosing the most restricted
230 ASN.1 string type possible. If the string contains non-ASCII
231 characters, then there is more than one string type which can be
232 used. See ::asn::defaultStringType.
233 ::asn::defaultStringType ?type?
235 Selects the string type to use for the encoding of non-ASCII
236 strings. Returns current default when called without argument.
237 If the argument type is supplied, it should be either UTF8 or
238 BMP to choose UTF8String or BMPString respectively.
239 DECODER
241 General notes:
242 [1] Nearly all decoder commands take two arguments. These arguments
244 are variable names, except for ::asn::asnGetResponse. The first
245 variable contains the encoded ASN value to decode at the begin‐
246 ning, and more, and the second variable is where the value is
247 stored to. The remainder of the input after the decoded value is
248 stored back into the datavariable.
249 [2] After extraction the data variable is always modified first,
251 before by writing the extracted value to its variable. This
252 means that if both arguments refer to the same variable, it will
253 always contain the extracted value after the call, and not the
254 remainder of the input.
255 ::asn::asnPeekByte data_var byte_var
257 Retrieve the first byte of the data, without modifing data_var.
258 This can be used to check for implicit tags.
259 ::asn::asnGetLength data_var length_var
261 Decode the length information for a block of BER data. The tag
262 has already to be removed from the data.
263 ::asn::asnGetResponse chan data_var
265 Reads an encoded ASN sequence from the channel chan and stores
266 it into the variable named by data_var.
267 ::asn::asnGetInteger data_var int_var
269 Assumes that an encoded integer value is at the front of the
270 data stored in the variable named data_var, extracts and stores
271 it into the variable named by int_var. Additionally removes all
272 bytes associated with the value from the data for further pro‐
273 cessing by the following decoder commands.
274 ::asn::asnGetEnumeration data_var enum_var
276 Assumes that an enumeration id is at the front of the data
277 stored in the variable named data_var, and stores it into the
278 variable named by enum_var. Additionally removes all bytes asso‐
279 ciated with the value from the data for further processing by
280 the following decoder commands.
281 ::asn::asnGetOctetString data_var string_var
283 Assumes that a string is at the front of the data stored in the
284 variable named data_var, and stores it into the variable named
285 by string_var. Additionally removes all bytes associated with
286 the value from the data for further processing by the following
287 decoder commands.
288 ::asn::asnGetString data_var string_var ?type_var?
290 Decodes a user-readable string. This is a convenience function
291 which is able to automatically distinguish all supported ASN.1
292 string types and convert the input value appropriately. See
293 ::asn::asnGetPrintableString, ::asnGetIA5String, etc. below for
294 the type-specific conversion commands.
295 If the optional third argument type_var is supplied, then the
297 type of the incoming string is stored in the variable named by
298 it.
299 The function throws the error "Invalid command name asnGetSome‐
301 UnsupportedString" if the unsupported string type Unsupported is
302 encountered. You can create the appropriate function
303 "asn::asnGetSomeUnsupportedString" in your application if nec‐
304 cessary.
305 ::asn::asnGetNumericString data_var string_var
307 Assumes that a numeric string value is at the front of the data
308 stored in the variable named data_var, and stores it into the
309 variable named by string_var. Additionally removes all bytes
310 associated with the value from the data for further processing
311 by the following decoder commands.
312 ::asn::asnGetPrintableString data_var string_var
314 Assumes that a printable string value is at the front of the
315 data stored in the variable named data_var, and stores it into
316 the variable named by string_var. Additionally removes all bytes
317 associated with the value from the data for further processing
318 by the following decoder commands.
319 ::asn::asnGetIA5String data_var string_var
321 Assumes that a IA5 (ASCII) string value is at the front of the
322 data stored in the variable named data_var, and stores it into
323 the variable named by string_var. Additionally removes all bytes
324 associated with the value from the data for further processing
325 by the following decoder commands.
326 ::asn::asnGetBMPString data_var string_var
328 Assumes that a BMP (two-byte unicode) string value is at the
329 front of the data stored in the variable named data_var, and
330 stores it into the variable named by string_var, converting it
331 into a proper Tcl string. Additionally removes all bytes associ‐
332 ated with the value from the data for further processing by the
333 following decoder commands.
334 ::asn::asnGetUTF8String data_var string_var
336 Assumes that a UTF8 string value is at the front of the data
337 stored in the variable named data_var, and stores it into the
338 variable named by string_var, converting it into a proper Tcl
339 string. Additionally removes all bytes associated with the
340 value from the data for further processing by the following
341 decoder commands.
342 ::asn::asnGetUTCTime data_var utc_var
344 Assumes that a UTC time value is at the front of the data stored
345 in the variable named data_var, and stores it into the variable
346 named by utc_var. The UTC time value is stored as a string,
347 which has to be decoded with the usual clock scan commands.
348 Additionally removes all bytes associated with the value from
349 the data for further processing by the following decoder com‐
350 mands.
351 ::asn::asnGetBitString data_var bits_var
353 Assumes that a bit string value is at the front of the data
354 stored in the variable named data_var, and stores it into the
355 variable named by bits_var as a string containing only 0 and 1.
356 Additionally removes all bytes associated with the value from
357 the data for further processing by the following decoder com‐
358 mands.
359 ::asn::asnGetObjectIdentifier data_var oid_var
361 Assumes that a object identifier (OID) value is at the front of
362 the data stored in the variable named data_var, and stores it
363 into the variable named by oid_var as a list of integers. Addi‐
364 tionally removes all bytes associated with the value from the
365 data for further processing by the following decoder commands.
366 ::asn::asnGetBoolean data_var bool_var
368 Assumes that a boolean value is at the front of the data stored
369 in the variable named data_var, and stores it into the variable
370 named by bool_var. Additionally removes all bytes associated
371 with the value from the data for further processing by the fol‐
372 lowing decoder commands.
373 ::asn::asnGetNull data_var
375 Assumes that a NULL value is at the front of the data stored in
376 the variable named data_var and removes the bytes used to encode
377 it from the data.
378 ::asn::asnGetSequence data_var sequence_var
380 Assumes that an ASN sequence is at the front of the data stored
381 in the variable named data_var, and stores it into the variable
382 named by sequence_var. Additionally removes all bytes associated
383 with the value from the data for further processing by the fol‐
384 lowing decoder commands.
385 The data in sequence_var is encoded binary and has to be further
387 decoded according to the definition of the sequence, using the
388 decoder commands here.
389 ::asn::asnGetSet data_var set_var
391 Assumes that an ASN set is at the front of the data stored in
392 the variable named data_var, and stores it into the variable
393 named by set_var. Additionally removes all bytes associated with
394 the value from the data for further processing by the following
395 decoder commands.
396 The data in set_var is encoded binary and has to be further
398 decoded according to the definition of the set, using the
399 decoder commands here.
400 ::asn::asnGetApplication data_var appNumber_var ?content_var? ?encod‐
402 ingType_var?
403 Assumes that an ASN application construct is at the front of the
404 data stored in the variable named data_var, and stores its id
405 into the variable named by appNumber_var. Additionally removes
406 all bytes associated with the value from the data for further
407 processing by the following decoder commands. If a content_var
408 is specified, then the command places all data associated with
409 it into the named variable, in the binary form which can be pro‐
410 cessed using the decoder commands of this package. If a encod‐
411 ingType_var is specified, then that var is set to 1 if the
412 encoding is constructed and 0 if it is primitive.
413 Otherwise it is the responsibility of the caller to decode the
415 remainder of the application construct based on the id retrieved
416 by this command, using the decoder commands of this package.
417 ::asn::asnGetContext data_var contextNumber_var ?content_var? ?encod‐
419 ingType_var?
420 Assumes that an ASN context tag construct is at the front of the
421 data stored in the variable named data_var, and stores its id
422 into the variable named by contextNumber_var. Additionally
423 removes all bytes associated with the value from the data for
424 further processing by the following decoder commands. If a con‐
425 tent_var is specified, then the command places all data associ‐
426 ated with it into the named variable, in the binary form which
427 can be processed using the decoder commands of this package. If
428 a encodingType_var is specified, then that var is set to 1 if
429 the encoding is constructed and 0 if it is primitive.
430 Otherwise it is the responsibility of the caller to decode the
432 remainder of the construct based on the id retrieved by this
433 command, using the decoder commands of this package.
434 HANDLING TAGS
436 Working with ASN.1 you often need to decode tagged values, which use a
437 tag thats different from the universal tag for a type. In those cases
438 you have to replace the tag with the universal tag used for the type,
439 to decode the value. To decode a tagged value use the ::asn::asnRetag
440 to change the tag to the appropriate type to use one of the decoders
441 for primitive values. To help with this the module contains three
442 functions:
443 ::asn::asnPeekTag data_var tag_var tagtype_var constr_var
445 The ::asn::asnPeekTag command can be used to take a peek at the
446 data and decode the tag value, without removing it from the
447 data. The tag_var gets set to the tag number, while the tag‐
448 type_var gets set to the class of the tag. (Either UNIVERSAL,
449 CONTEXT, APPLICATION or PRIVATE). The constr_var is set to 1 if
450 the tag is for a constructed value, and to 0 for not con‐
451 structed. It returns the length of the tag.
452 ::asn::asnTag tagnumber ?class? ?tagstyle?
454 The ::asn::asnTag can be used to create a tag value. The tagnum‐
455 ber gives the number of the tag, while the class gives one of
456 the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The
457 class may be abbreviated to just the first letter (U,C,A,P),
458 default is UNIVERSAL. The tagstyle is either C for Constructed
459 encoding, or P for primitve encoding. It defaults to P. You can
460 also use 1 instead of C and 0 instead of P for direct use of the
461 values returned by ::asn::asnPeekTag.
462 ::asn::asnRetag data_var newTag
464 Replaces the tag in front of the data in data_var with newTag.
465 The new Tag can be created using the ::asn::asnTag command.
466
468 Examples for the usage of this package can be found in the implementa‐
469 tion of package ldap.
470
472 This document, and the package it describes, will undoubtedly contain
473 bugs and other problems. Please report such in the category asn of the
474 Tcllib SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
475 Please also report any ideas for enhancements you may have for either
476 package and/or documentation.
477
479 asn, ber, cer, der, internet, protocol, x.208, x.209
480
482 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
483 Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
484 Copyright (c) 2004-2008 Michael Schlenker <mic42@users.sourceforge.net>
485asn 0.8 asn(n)