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.4?
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 en‐
119 coded ASN.1 data. It can also be used for decoding DER, which is a re‐
120 stricted subset of BER.
121 ASN.1 is a standard Abstract Syntax Notation, and BER are its Basic En‐
123 coding 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 se‐
138 quence 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 er‐
203 ror if the string contains characters other than decimal numbers
204 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, be‐
251 fore by writing the extracted value to its variable. This means
252 that if both arguments refer to the same variable, it will al‐
253 ways contain the extracted value after the call, and not the re‐
254 mainder 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 "asn::as‐
303 nGetSomeUnsupportedString" in your application if neccessary.
304 ::asn::asnGetNumericString data_var string_var
306 Assumes that a numeric string value is at the front of the data
307 stored in the variable named data_var, and stores it into the
308 variable named by string_var. Additionally removes all bytes as‐
309 sociated with the value from the data for further processing by
310 the following decoder commands.
311 ::asn::asnGetPrintableString data_var string_var
313 Assumes that a printable string value is at the front of the
314 data stored in the variable named data_var, and stores it into
315 the variable named by string_var. Additionally removes all bytes
316 associated with the value from the data for further processing
317 by the following decoder commands.
318 ::asn::asnGetIA5String data_var string_var
320 Assumes that a IA5 (ASCII) string value is at the front of the
321 data stored in the variable named data_var, and stores it into
322 the variable named by string_var. Additionally removes all bytes
323 associated with the value from the data for further processing
324 by the following decoder commands.
325 ::asn::asnGetBMPString data_var string_var
327 Assumes that a BMP (two-byte unicode) string value is at the
328 front of the data stored in the variable named data_var, and
329 stores it into the variable named by string_var, converting it
330 into a proper Tcl string. Additionally removes all bytes associ‐
331 ated with the value from the data for further processing by the
332 following decoder commands.
333 ::asn::asnGetUTF8String data_var string_var
335 Assumes that a UTF8 string value is at the front of the data
336 stored in the variable named data_var, and stores it into the
337 variable named by string_var, converting it into a proper Tcl
338 string. Additionally removes all bytes associated with the
339 value from the data for further processing by the following de‐
340 coder commands.
341 ::asn::asnGetUTCTime data_var utc_var
343 Assumes that a UTC time value is at the front of the data stored
344 in the variable named data_var, and stores it into the variable
345 named by utc_var. The UTC time value is stored as a string,
346 which has to be decoded with the usual clock scan commands. Ad‐
347 ditionally removes all bytes associated with the value from the
348 data for further processing by the following decoder commands.
349 ::asn::asnGetBitString data_var bits_var
351 Assumes that a bit string value is at the front of the data
352 stored in the variable named data_var, and stores it into the
353 variable named by bits_var as a string containing only 0 and 1.
354 Additionally removes all bytes associated with the value from
355 the data for further processing by the following decoder com‐
356 mands.
357 ::asn::asnGetObjectIdentifier data_var oid_var
359 Assumes that a object identifier (OID) value is at the front of
360 the data stored in the variable named data_var, and stores it
361 into the variable named by oid_var as a list of integers. Addi‐
362 tionally removes all bytes associated with the value from the
363 data for further processing by the following decoder commands.
364 ::asn::asnGetBoolean data_var bool_var
366 Assumes that a boolean value is at the front of the data stored
367 in the variable named data_var, and stores it into the variable
368 named by bool_var. Additionally removes all bytes associated
369 with the value from the data for further processing by the fol‐
370 lowing decoder commands.
371 ::asn::asnGetNull data_var
373 Assumes that a NULL value is at the front of the data stored in
374 the variable named data_var and removes the bytes used to encode
375 it from the data.
376 ::asn::asnGetSequence data_var sequence_var
378 Assumes that an ASN sequence is at the front of the data stored
379 in the variable named data_var, and stores it into the variable
380 named by sequence_var. Additionally removes all bytes associated
381 with the value from the data for further processing by the fol‐
382 lowing decoder commands.
383 The data in sequence_var is encoded binary and has to be further
385 decoded according to the definition of the sequence, using the
386 decoder commands here.
387 ::asn::asnGetSet data_var set_var
389 Assumes that an ASN set is at the front of the data stored in
390 the variable named data_var, and stores it into the variable
391 named by set_var. Additionally removes all bytes associated with
392 the value from the data for further processing by the following
393 decoder commands.
394 The data in set_var is encoded binary and has to be further de‐
396 coded according to the definition of the set, using the decoder
397 commands here.
398 ::asn::asnGetApplication data_var appNumber_var ?content_var? ?encod‐
400 ingType_var?
401 Assumes that an ASN application construct is at the front of the
402 data stored in the variable named data_var, and stores its id
403 into the variable named by appNumber_var. Additionally removes
404 all bytes associated with the value from the data for further
405 processing by the following decoder commands. If a content_var
406 is specified, then the command places all data associated with
407 it into the named variable, in the binary form which can be pro‐
408 cessed using the decoder commands of this package. If a encod‐
409 ingType_var is specified, then that var is set to 1 if the en‐
410 coding is constructed and 0 if it is primitive.
411 Otherwise it is the responsibility of the caller to decode the
413 remainder of the application construct based on the id retrieved
414 by this command, using the decoder commands of this package.
415 ::asn::asnGetContext data_var contextNumber_var ?content_var? ?encod‐
417 ingType_var?
418 Assumes that an ASN context tag construct is at the front of the
419 data stored in the variable named data_var, and stores its id
420 into the variable named by contextNumber_var. Additionally re‐
421 moves all bytes associated with the value from the data for fur‐
422 ther processing by the following decoder commands. If a con‐
423 tent_var is specified, then the command places all data associ‐
424 ated with it into the named variable, in the binary form which
425 can be processed using the decoder commands of this package. If
426 a encodingType_var is specified, then that var is set to 1 if
427 the encoding is constructed and 0 if it is primitive.
428 Otherwise it is the responsibility of the caller to decode the
430 remainder of the construct based on the id retrieved by this
431 command, using the decoder commands of this package.
432 HANDLING TAGS
434 Working with ASN.1 you often need to decode tagged values, which use a
435 tag thats different from the universal tag for a type. In those cases
436 you have to replace the tag with the universal tag used for the type,
437 to decode the value. To decode a tagged value use the ::asn::asnRetag
438 to change the tag to the appropriate type to use one of the decoders
439 for primitive values. To help with this the module contains three
440 functions:
441 ::asn::asnPeekTag data_var tag_var tagtype_var constr_var
443 The ::asn::asnPeekTag command can be used to take a peek at the
444 data and decode the tag value, without removing it from the
445 data. The tag_var gets set to the tag number, while the tag‐
446 type_var gets set to the class of the tag. (Either UNIVERSAL,
447 CONTEXT, APPLICATION or PRIVATE). The constr_var is set to 1 if
448 the tag is for a constructed value, and to 0 for not construc‐
449 ted. It returns the length of the tag.
450 ::asn::asnTag tagnumber ?class? ?tagstyle?
452 The ::asn::asnTag can be used to create a tag value. The tagnum‐
453 ber gives the number of the tag, while the class gives one of
454 the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The
455 class may be abbreviated to just the first letter (U,C,A,P), de‐
456 fault is UNIVERSAL. The tagstyle is either C for Constructed
457 encoding, or P for primitve encoding. It defaults to P. You can
458 also use 1 instead of C and 0 instead of P for direct use of the
459 values returned by ::asn::asnPeekTag.
460 ::asn::asnRetag data_var newTag
462 Replaces the tag in front of the data in data_var with newTag.
463 The new Tag can be created using the ::asn::asnTag command.
464
466 Examples for the usage of this package can be found in the implementa‐
467 tion of package ldap.
468
470 This document, and the package it describes, will undoubtedly contain
471 bugs and other problems. Please report such in the category asn of the
472 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
473 report any ideas for enhancements you may have for either package
474 and/or documentation.
475 When proposing code changes, please provide unified diffs, i.e the out‐
477 put of diff -u.
478 Note further that attachments are strongly preferred over inlined
480 patches. Attachments can be made by going to the Edit form of the
481 ticket immediately after its creation, and then using the left-most
482 button in the secondary navigation bar.
483
485 asn, ber, cer, der, internet, protocol, x.208, x.209
486
488 Networking
489
491 Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
492 Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
493 Copyright (c) 2004-2011 Michael Schlenker <mic42@users.sourceforge.net>
494tcllib 0.8 asn(n)