1DERUNPACK(3)                     derunpack 1.0                    DERUNPACK(3)
2
3
4

NAME

6       packet.derunpack - DER decoding module
7

DESCRIPTION

9       Decode  using  ASN.1 DER (Distinguished Encoding Representation) ASN.1:
10       Abstract Syntax Notation 1
11
12       This module does not completely decode all DER data types, the  follow‐
13       ing is a list of supported data types in this implementation:
14           INTEGER,
15           BIT_STRING,
16           NULL,
17           OBJECT_IDENTIFIER,
18           GeneralizedTime,
19           Strings (OCTET STRING, PrintableString, etc.)
20           SEQUENCE OF,
21           SEQUENCE,
22

CLASSES

24   class DERunpack(packet.unpack.Unpack)
25       DER unpack object
26
27       Usage:
28           from packet.derunpack import DERunpack
29
30           x = DERunpack(buffer)
31
32           # Get the decoded object structure for the stream bytes in buffer
33           obj = x.get_item()
34
35           Where obj is of the form:
36               obj = {
37                   application = {
38                       context-tag0 = int|list|dictionary,
39                       context-tag1 = int|list|dictionary,
40                       ...
41                       context-tagN = int|list|dictionary,
42                   }
43               }
44
45           Example:
46             For the following ASN.1 definition:
47               TEST ::= [APPLICATION 10] SEQUENCE {
48                   id       [0] INTEGER,
49                   numbers  [1] SEQUENCE OF INTEGER,
50                   data     [2] SEQUENCE {
51                       -- NOTE: first tag is [1], not [0]
52                       type   [1] INTEGER,
53                       value  [2] PrintableString,
54                   },
55               }
56
57             Using the streamed bytes of the above ASN.1 definition,
58             the following is returned by get_item():
59               obj = {
60                   10 = {              # Application 10
61                       0: 53,          # id: context-tag=0, value=53
62                       1: [1,2,3],     # numbers: context-tag=1, value=[1,2,3]
63                       2: {            # data: context-tag=1, value=structure
64                           1: 2,       # id: context-tag=1, value=2
65                           2: "test",  # id: context-tag=2, value="test"
66                       }
67                   }
68               }
69
70
71       Methods defined here:
72       ---------------------
73
74       der_date(self, size)
75       Return a date time of type GeneralizedTime
76       Type GeneralizedTime takes values of the year, month, day, hour,
77       minute, second, and second fraction in any of following three forms:
78
79       Local time: "YYYYMMDDHH[MM[SS[.fff]]]"
80       Universal time (UTC): "YYYYMMDDHH[MM[SS[.fff]]]Z"
81       Difference between local and UTC times" "YYYYMMDDHH[MM[SS[.fff]]]+|-HHMM".
82
83       Where the optional fff is accurate to three decimal places
84
85       der_integer(self, size=None, unsigned=False)
86       Return an integer given the size of the integer in bytes
87
88
89              size:  Number of bytes for the integer, if this option is not given
90                     the method get_size() is used to get the size of the integer
91
92              unsigned:
93                     Usually an unsigned integer is encoded with a leading byte
94                     of all zeros but when decoding data of BIT_STRING type all
95                     decoded bytes must be unsigned so they can be concatenated
96                     correctly
97
98       der_oid(self, size)
99       Return an object identifier (OID)
100
101       get_item(self, oid=None)
102       Get item from the byte stream using TLV
103       This is a recursive function where the tag and length are decoded
104       and then this function is called to get the value if tag is one of
105       primitive or non-constructed types.
106
107       Calling this method right after instantiation of the object will
108       decode the whole ASN.1 representation
109
110       get_size(self)
111       Get the size of element (length in TLV)
112
113       Short form: bit8=0, one octet, length given by bits 7-1 (0-127)
114       Long form:  bit8=1, 2-127 octet, bits 7-1 give number of length
115                   objects
116
117       Example:
118         Short form (bit8=0):
119           0x0f (0b00001111): length is 0x0f (15)
120         Long form (bit8=1 of first byte):
121           0x820123 (0b100000100000000100100011):
122           length is given by the next 2 bytes (first 7-1 bits 0x02)
123           Next two bytes gives the length 0x0123 = 291
124
125       get_tag(self)
126       Get the tag along with the tag class and form or P/C bit
127
128       The first byte(s) of the TLV (Type, Length, Value) is the type
129       which has the following format:
130         First byte:
131           bits 8-7: tag class
132           bit 6:    form or P/C (Constructed if bit is set)
133           bits 5-1: tag number (0-30)
134                     if all bits are 1's (decimal 31) then one or more
135                     bytes are required for the tag
136
137         If bits 5-1 are all 1's in the first byte, the tag is given
138         in the following bytes:
139         Extra byes for tag:
140           bit 8:    next byte is part of tag
141           bits 7-1: tag bits
142
143       Examples:
144         0xa1 (0b10100001): Short form
145           tag class: 0b10 = 2 (CONTEXT)
146           P/C:       0b0  = 0 (not constructed)
147
148         0x1f8107 (0b000111111000000100000111): Long form
149           tag class: 0b00 = 0 (UNIVERSAL -- standard tag)
150           P/C:       0b0  = 0 (not constructed)
151           tag:   0b11111 = 31 (tag is given in following bytes)
152           First extra byte: 0x81 (0b10000001)
153             bit8=1  : there is an extra byte after this
154             bits 7-1: 0b0000001 (0x01 most significant 7 bits of tag)
155           Second extra byte: 0x07 (0b00000111)
156             bit8=1  : this is the last byte
157             bits 7-1: 0b0000111 (0x07 least significant 7 bits of tag)
158           Tag number: big-endian bits from extra bytes (7 bits each)
159                      14 bits: 0x0087 (0x01 << 7 + 0x07) = 135
160

SEE ALSO

162       packet.unpack(3)
163
164

BUGS

166       No known bugs.
167

AUTHOR

169       Jorge Mora (mora@netapp.com)
170
171
172
173NFStest 3.2                      21 March 2023                    DERUNPACK(3)
Impressum