1asn(n)                         ASN.1 processing                         asn(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       asn - ASN.1 BER encoder/decoder
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require asn  ?0.8.4?
14
15       ::asn::asnSequence evalue...
16
17       ::asn::asnSequenceFromList elist
18
19       ::asn::asnSet evalue...
20
21       ::asn::asnSetFromList elist
22
23       ::asn::asnApplicationConstr appNumber evalue...
24
25       ::asn::asnApplication appNumber data
26
27       ::asn::asnChoice appNumber evalue...
28
29       ::asn::asnChoiceConstr appNumber evalue...
30
31       ::asn::asnInteger number
32
33       ::asn::asnEnumeration number
34
35       ::asn::asnBoolean bool
36
37       ::asn::asnContext context data
38
39       ::asn::asnContextConstr context evalue...
40
41       ::asn::asnObjectIdentifier idlist
42
43       ::asn::asnUTCTime utcstring
44
45       ::asn::asnNull
46
47       ::asn::asnBitString string
48
49       ::asn::asnOctetString string
50
51       ::asn::asnNumericString string
52
53       ::asn::asnPrintableString string
54
55       ::asn::asnIA5String string
56
57       ::asn::asnBMPString string
58
59       ::asn::asnUTF8String string
60
61       ::asn::asnString string
62
63       ::asn::defaultStringType ?type?
64
65       ::asn::asnPeekByte data_var byte_var
66
67       ::asn::asnGetLength data_var length_var
68
69       ::asn::asnGetResponse chan data_var
70
71       ::asn::asnGetInteger data_var int_var
72
73       ::asn::asnGetEnumeration data_var enum_var
74
75       ::asn::asnGetOctetString data_var string_var
76
77       ::asn::asnGetString data_var string_var ?type_var?
78
79       ::asn::asnGetNumericString data_var string_var
80
81       ::asn::asnGetPrintableString data_var string_var
82
83       ::asn::asnGetIA5String data_var string_var
84
85       ::asn::asnGetBMPString data_var string_var
86
87       ::asn::asnGetUTF8String data_var string_var
88
89       ::asn::asnGetUTCTime data_var utc_var
90
91       ::asn::asnGetBitString data_var bits_var
92
93       ::asn::asnGetObjectIdentifier data_var oid_var
94
95       ::asn::asnGetBoolean data_var bool_var
96
97       ::asn::asnGetNull data_var
98
99       ::asn::asnGetSequence data_var sequence_var
100
101       ::asn::asnGetSet data_var set_var
102
103       ::asn::asnGetApplication  data_var  appNumber_var ?content_var? ?encod‐
104       ingType_var?
105
106       ::asn::asnGetContext data_var contextNumber_var  ?content_var?  ?encod‐
107       ingType_var?
108
109       ::asn::asnPeekTag data_var tag_var tagtype_var constr_var
110
111       ::asn::asnTag tagnumber ?class? ?tagstyle?
112
113       ::asn::asnRetag data_var newTag
114
115______________________________________________________________________________
116

DESCRIPTION

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
122       ASN.1  is  a  standard  Abstract Syntax Notation, and BER are its Basic
123       Encoding Rules.
124
125       See http://asn1.elibel.tm.fr/en/standards/index.htm for  more  informa‐
126       tion about the standard.
127
128       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

PUBLIC API

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
140       ::asn::asnSequenceFromList elist
141              Takes a list of encoded values, packs them into an ASN  sequence
142              and returns its encoded binary form.
143
144       ::asn::asnSet evalue...
145              Takes  zero  or  more encoded values, packs them into an ASN set
146              and returns its encoded binary form.
147
148       ::asn::asnSetFromList elist
149              Takes a list of encoded values, packs them into an ASN  set  and
150              returns its encoded binary form.
151
152       ::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
156       ::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
160       ::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
164       ::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
168       ::asn::asnInteger number
169              Returns the encoded form of the specified integer number.
170
171       ::asn::asnEnumeration number
172              Returns the encoded form of the specified enumeration id number.
173
174       ::asn::asnBoolean bool
175              Returns the encoded form of the specified boolean value bool.
176
177       ::asn::asnContext context data
178              Takes  an  encoded  value  and packs it into a constructed value
179              with application tag, the context number.
180
181       ::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
185       ::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
189       ::asn::asnUTCTime utcstring
190              Returns the encoded form of the specified UTC time string.
191
192       ::asn::asnNull
193              Returns the NULL encoding.
194
195       ::asn::asnBitString string
196              Returns the encoded form of the specified string.
197
198       ::asn::asnOctetString string
199              Returns the encoded form of the specified string.
200
201       ::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
206       ::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
214       ::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
219       ::asn::asnBMPString string
220              Returns  the  string  encoded  as ASN.1 Basic Multilingual Plane
221              string (Which is essentialy big-endian UCS2).
222
223       ::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
228       ::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
234       ::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
240   DECODER
241       General notes:
242
243       [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
250       [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
256       ::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
260       ::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
264       ::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
268       ::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
275       ::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
282       ::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
289       ::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
296              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
300              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
306       ::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
313       ::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
320       ::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
327       ::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
335       ::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
343       ::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
352       ::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
360       ::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
367       ::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
374       ::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
379       ::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
386              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
390       ::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
397              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
401       ::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
414              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
418       ::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
431              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
435   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
444       ::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
453       ::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
463       ::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

EXAMPLES

468       Examples  for the usage of this package can be found in the implementa‐
469       tion of package ldap.
470

BUGS, IDEAS, FEEDBACK

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 Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please  also
475       report  any  ideas  for  enhancements  you  may have for either package
476       and/or documentation.
477
478       When proposing code changes, please provide unified diffs, i.e the out‐
479       put of diff -u.
480
481       Note  further  that  attachments  are  strongly  preferred over inlined
482       patches. Attachments can be made by going  to  the  Edit  form  of  the
483       ticket  immediately  after  its  creation, and then using the left-most
484       button in the secondary navigation bar.
485

KEYWORDS

487       asn, ber, cer, der, internet, protocol, x.208, x.209
488

CATEGORY

490       Networking
491
493       Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
494       Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
495       Copyright (c) 2004-2011 Michael Schlenker <mic42@users.sourceforge.net>
496
497
498
499
500tcllib                                0.8                               asn(n)
Impressum