Debian Codegraph @

src/spnego/_asn1.py

raw
1 # Copyright: (c) 2020, Jordan Borean (@jborean93) <[email protected]>
2 # MIT License (see LICENSE or https://opensource.org/licenses/MIT)
3
4 import collections
5 import datetime
6 import enum
7 import struct
8 import typing
9
10 from spnego._text import to_bytes, to_text
11
12 ASN1Value = collections.namedtuple("ASN1Value", ["tag_class", "constructed", "tag_number", "b_data"])
13 """A representation of an ASN.1 TLV as a Python object.
14
15 Defines the ASN.1 Type Length Value (TLV) values as separate objects for easier parsing. This is returned by
16 :method:`unpack_asn1`.
17
18 Attributes:
19 tag_class (TagClass): The tag class of the TLV.
20 constructed (bool): Whether the value is constructed or 0, 1, or more element encodings (True) or not (False).
21 tag_number (Union[TypeTagNumber, int]): The tag number of the value, can be a TypeTagNumber if the tag_class
22 is `universal` otherwise it's an explicit tag number value.
23 b_data (bytes): The raw byes of the TLV value.
24 """
25
26
27 class TagClass(enum.IntEnum):
28 universal = 0
29 application = 1
30 context_specific = 2
31 private = 3
32
33 @classmethod
34 def native_labels(cls) -> typing.Dict["TagClass", str]:
35 return {
36 TagClass.universal: "Universal",
37 TagClass.application: "Application",
38 TagClass.context_specific: "Context-specific",
39 TagClass.private: "Private",
40 }
41
42
43 class TypeTagNumber(enum.IntEnum):
44 end_of_content = 0
45 boolean = 1
46 integer = 2
47 bit_string = 3
48 octet_string = 4
49 null = 5
50 object_identifier = 6
51 object_descriptor = 7
52 external = 8
53 real = 9
54 enumerated = 10
55 embedded_pdv = 11
56 utf8_string = 12
57 relative_oid = 13
58 time = 14
59 reserved = 15
60 sequence = 16
61 sequence_of = 16
62 set = 17
63 set_of = 17
64 numeric_string = 18
65 printable_string = 19
66 t61_string = 20
67 videotex_string = 21
68 ia5_string = 22
69 utc_time = 23
70 generalized_time = 24
71 graphic_string = 25
72 visible_string = 26
73 general_string = 27
74 universal_string = 28
75 character_string = 29
76 bmp_string = 30
77 date = 31
78 time_of_day = 32
79 date_time = 33
80 duration = 34
81 oid_iri = 35
82 relative_oid_iri = 36
83
84 @classmethod
85 def native_labels(cls) -> typing.Dict[int, str]:
86 return {
87 TypeTagNumber.end_of_content: "End-of-Content (EOC)",
88 TypeTagNumber.boolean: "BOOLEAN",
89 TypeTagNumber.integer: "INTEGER",
90 TypeTagNumber.bit_string: "BIT STRING",
91 TypeTagNumber.octet_string: "OCTET STRING",
92 TypeTagNumber.null: "NULL",
93 TypeTagNumber.object_identifier: "OBJECT IDENTIFIER",
94 TypeTagNumber.object_descriptor: "Object Descriptor",
95 TypeTagNumber.external: "EXTERNAL",
96 TypeTagNumber.real: "REAL (float)",
97 TypeTagNumber.enumerated: "ENUMERATED",
98 TypeTagNumber.embedded_pdv: "EMBEDDED PDV",
99 TypeTagNumber.utf8_string: "UTF8String",
100 TypeTagNumber.relative_oid: "RELATIVE-OID",
101 TypeTagNumber.time: "TIME",
102 TypeTagNumber.reserved: "RESERVED",
103 TypeTagNumber.sequence: "SEQUENCE or SEQUENCE OF",
104 TypeTagNumber.set: "SET or SET OF",
105 TypeTagNumber.numeric_string: "NumericString",
106 TypeTagNumber.printable_string: "PrintableString",
107 TypeTagNumber.t61_string: "T61String",
108 TypeTagNumber.videotex_string: "VideotexString",
109 TypeTagNumber.ia5_string: "IA5String",
110 TypeTagNumber.utc_time: "UTCTime",
111 TypeTagNumber.generalized_time: "GeneralizedTime",
112 TypeTagNumber.graphic_string: "GraphicString",
113 TypeTagNumber.visible_string: "VisibleString",
114 TypeTagNumber.general_string: "GeneralString",
115 TypeTagNumber.universal_string: "UniversalString",
116 TypeTagNumber.character_string: "CHARACTER",
117 TypeTagNumber.bmp_string: "BMPString",
118 TypeTagNumber.date: "DATE",
119 TypeTagNumber.time_of_day: "TIME-OF-DAY",
120 TypeTagNumber.date_time: "DATE-TIME",
121 TypeTagNumber.duration: "DURATION",
122 TypeTagNumber.oid_iri: "OID-IRI",
123 TypeTagNumber.relative_oid_iri: "RELATIVE-OID-IRI",
124 }
125
126
127 def extract_asn1_tlv(
128 tlv: typing.Union[bytes, ASN1Value],
129 tag_class: TagClass,
130 tag_number: typing.Union[int, TypeTagNumber],
131 ) -> bytes:
132 """Extract the bytes and validates the existing tag of an ASN.1 value."""
133 if isinstance(tlv, ASN1Value):
134 if tag_class == TagClass.universal:
135 label_name = TypeTagNumber.native_labels().get(tag_number, "Unknown tag type")
136 msg = "Invalid ASN.1 %s tags, actual tag class %s and tag number %s" % (
137 label_name,
138 f"{type(tlv.tag_class).__name__}.{tlv.tag_class.name}",
139 f"{type(tlv.tag_number).__name__}.{tlv.tag_number.name}"
140 if isinstance(tlv.tag_number, TypeTagNumber)
141 else tlv.tag_number,
142 )
143
144 else:
145 msg = "Invalid ASN.1 tags, actual tag %s and number %s, expecting class %s and number %s" % (
146 f"{type(tlv.tag_class).__name__}.{tlv.tag_class.name}",
147 f"{type(tlv.tag_number).__name__}.{tlv.tag_number.name}"
148 if isinstance(tlv.tag_number, TypeTagNumber)
149 else tlv.tag_number,
150 f"{type(tag_class).__name__}.{tag_class.name}",
151 f"{type(tag_number).__name__}.{tag_number.name}"
152 if isinstance(tag_number, TypeTagNumber)
153 else tag_number,
154 )
155
156 if tlv.tag_class != tag_class or tlv.tag_number != tag_number:
157 raise ValueError(msg)
158
159 return tlv.b_data
160
161 return tlv
162
163
164 def get_sequence_value(
165 sequence: typing.Dict[int, ASN1Value],
166 tag: int,
167 structure_name: str,
168 field_name: typing.Optional[str] = None,
169 unpack_func: typing.Optional[typing.Callable[[typing.Union[bytes, ASN1Value]], typing.Any]] = None,
170 ) -> typing.Any:
171 """Gets an optional tag entry in a tagged sequence will a further unpacking of the value."""
172 if tag not in sequence:
173 return
174
175 if not unpack_func:
176 return sequence[tag]
177
178 try:
179 return unpack_func(sequence[tag])
180 except ValueError as e:
181 where = "%s in %s" % (field_name, structure_name) if field_name else structure_name
182 raise ValueError("Failed unpacking %s: %s" % (where, str(e))) from e
183
184
185 def pack_asn1(
186 tag_class: TagClass,
187 constructed: bool,
188 tag_number: typing.Union[TypeTagNumber, int],
189 b_data: bytes,
190 ) -> bytes:
191 """Pack the ASN.1 value into the ASN.1 bytes.
192
193 Will pack the raw bytes into an ASN.1 Type Length Value (TLV) value. A TLV is in the form:
194
195 | Identifier Octet(s) | Length Octet(s) | Data Octet(s) |
196
197 Args:
198 tag_class: The tag class of the data.
199 constructed: Whether the data is constructed (True), i.e. contains 0, 1, or more element encodings, or is
200 primitive (False).
201 tag_number: The type tag number if tag_class is universal else the explicit tag number of the TLV.
202 b_data: The encoded value to pack into the ASN.1 TLV.
203
204 Returns:
205 bytes: The ASN.1 value as raw bytes.
206 """
207 b_asn1_data = bytearray()
208
209 # ASN.1 Identifier octet is
210 #
211 # | Octet 1 | | Octet 2 |
212 # | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
213 # | Class | P/C | Tag Number (0-30) | | More | Tag number |
214 #
215 # If Tag Number is >= 31 the first 5 bits are 1 and the 2nd octet is used to encode the length.
216 if tag_class < 0 or tag_class > 3:
217 raise ValueError("tag_class must be between 0 and 3")
218
219 identifier_octets = tag_class << 6
220 identifier_octets |= (1 if constructed else 0) << 5
221
222 if tag_number < 31:
223 identifier_octets |= tag_number
224 b_asn1_data.append(identifier_octets)
225 else:
226 # Set the first 5 bits of the first octet to 1 and encode the tag number in subsequent octets.
227 identifier_octets |= 31
228 b_asn1_data.append(identifier_octets)
229 b_asn1_data.extend(_pack_asn1_octet_number(tag_number))
230
231 # ASN.1 Length octet for DER encoding is always in the definite form. This form packs the lengths in the following
232 # octet structure:
233 #
234 # | Octet 1 | | Octet n |
235 # | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 |
236 # | Long form | Short = length, Long = num octets | | Big endian length for long |
237 #
238 # Basically if the length < 127 it's encoded in the first octet, otherwise the first octet 7 bits indicates how
239 # many subsequent octets were used to encode the length.
240 length = len(b_data)
241 if length < 128:
242 b_asn1_data.append(length)
243 else:
244 length_octets = bytearray()
245 while length:
246 length_octets.append(length & 0b11111111)
247 length >>= 8
248
249 # Reverse the octets so the higher octets are first, add the initial length octet with the MSB set and add them
250 # all to the main ASN.1 byte array.
251 length_octets.reverse()
252 b_asn1_data.append(len(length_octets) | 0b10000000)
253 b_asn1_data.extend(length_octets)
254
255 return bytes(b_asn1_data) + b_data
256
257
258 def pack_asn1_bit_string(
259 value: bytes,
260 tag: bool = True,
261 ) -> bytes:
262 # First octet is the number of unused bits in the last octet from the LSB.
263 b_data = b"\x00" + value
264 if tag:
265 b_data = pack_asn1(TagClass.universal, False, TypeTagNumber.bit_string, b_data)
266
267 return b_data
268
269
270 def pack_asn1_enumerated(
271 value: int,
272 tag: bool = True,
273 ) -> bytes:
274 """Packs an int into an ASN.1 ENUMERATED byte value with optional universal tagging."""
275 b_data = pack_asn1_integer(value, tag=False)
276 if tag:
277 b_data = pack_asn1(TagClass.universal, False, TypeTagNumber.enumerated, b_data)
278
279 return b_data
280
281
282 def pack_asn1_general_string(
283 value: typing.Union[str, bytes],
284 tag: bool = True,
285 encoding: str = "ascii",
286 ) -> bytes:
287 """Packs an string value into an ASN.1 GeneralString byte value with optional universal tagging."""
288 b_data = to_bytes(value, encoding=encoding)
289 if tag:
290 b_data = pack_asn1(TagClass.universal, False, TypeTagNumber.general_string, b_data)
291
292 return b_data
293
294
295 def pack_asn1_integer(
296 value: int,
297 tag: bool = True,
298 ) -> bytes:
299 """Packs an int value into an ASN.1 INTEGER byte value with optional universal tagging."""
300 # Thanks to https://github.com/andrivet/python-asn1 for help with the negative value logic.
301 is_negative = False
302 limit = 0x7F
303 if value < 0:
304 value = -value
305 is_negative = True
306 limit = 0x80
307
308 b_int = bytearray()
309 while value > limit:
310 val = value & 0xFF
311
312 if is_negative:
313 val = 0xFF - val
314
315 b_int.append(val)
316 value >>= 8
317
318 b_int.append(((0xFF - value) if is_negative else value) & 0xFF)
319
320 if is_negative:
321 for idx, val in enumerate(b_int):
322 if val < 0xFF:
323 b_int[idx] += 1
324 break
325
326 b_int[idx] = 0
327
328 if is_negative and b_int[-1] == 0x7F: # Two's complement corner case
329 b_int.append(0xFF)
330
331 b_int.reverse()
332
333 b_value = bytes(b_int)
334 if tag:
335 b_value = pack_asn1(TagClass.universal, False, TypeTagNumber.integer, b_value)
336
337 return b_value
338
339
340 def pack_asn1_object_identifier(
341 oid: str,
342 tag: bool = True,
343 ) -> bytes:
344 """Packs an str value into an ASN.1 OBJECT IDENTIFIER byte value with optional universal tagging."""
345 b_oid = bytearray()
346 oid_split = [int(i) for i in oid.split(".")]
347
348 if len(oid_split) < 2:
349 raise ValueError("An OID must have 2 or more elements split by '.'")
350
351 # The first byte of the OID is the first 2 elements (x.y) as (x * 40) + y
352 b_oid.append((oid_split[0] * 40) + oid_split[1])
353
354 for val in oid_split[2:]:
355 b_oid.extend(_pack_asn1_octet_number(val))
356
357 b_value = bytes(b_oid)
358 if tag:
359 b_value = pack_asn1(TagClass.universal, False, TypeTagNumber.object_identifier, b_value)
360
361 return b_value
362
363
364 def pack_asn1_octet_string(
365 b_data: bytes,
366 tag: bool = True,
367 ) -> bytes:
368 """Packs an bytes value into an ASN.1 OCTET STRING byte value with optional universal tagging."""
369 if tag:
370 b_data = pack_asn1(TagClass.universal, False, TypeTagNumber.octet_string, b_data)
371
372 return b_data
373
374
375 def pack_asn1_sequence(
376 sequence: typing.List[bytes],
377 tag: bool = True,
378 ) -> bytes:
379 """Packs a list of encoded bytes into an ASN.1 SEQUENCE byte value with optional universal tagging."""
380 b_data = b"".join(sequence)
381 if tag:
382 b_data = pack_asn1(TagClass.universal, True, TypeTagNumber.sequence, b_data)
383
384 return b_data
385
386
387 def _pack_asn1_octet_number(num: int) -> bytes:
388 """Packs an int number into an ASN.1 integer value that spans multiple octets."""
389 num_octets = bytearray()
390
391 while num:
392 # Get the 7 bit value of the number.
393 octet_value = num & 0b01111111
394
395 # Set the MSB if this isn't the first octet we are processing (overall last octet)
396 if len(num_octets):
397 octet_value |= 0b10000000
398
399 num_octets.append(octet_value)
400
401 # Shift the number by 7 bits as we've just processed them.
402 num >>= 7
403
404 # Finally we reverse the order so the higher octets are first.
405 num_octets.reverse()
406
407 return num_octets
408
409
410 def unpack_asn1(b_data: bytes) -> typing.Tuple[ASN1Value, bytes]:
411 """Unpacks an ASN.1 TLV into each element.
412
413 Unpacks the raw ASN.1 value into a `ASN1Value` tuple and returns the remaining bytes that are not part of the
414 ASN.1 TLV.
415
416 Args:
417 b_data: The raw bytes to unpack as an ASN.1 TLV.
418
419 Returns:
420 ASN1Value: The ASN.1 value that is unpacked from the raw bytes passed in.
421 bytes: Any remaining bytes that are not part of the ASN1Value.
422 """
423 octet1 = struct.unpack("B", b_data[:1])[0]
424 tag_class = TagClass((octet1 & 0b11000000) >> 6)
425 constructed = bool(octet1 & 0b00100000)
426 tag_number = octet1 & 0b00011111
427
428 length_offset = 1
429 if tag_number == 31:
430 tag_number, octet_count = _unpack_asn1_octet_number(b_data[1:])
431 length_offset += octet_count
432
433 if tag_class == TagClass.universal:
434 tag_number = TypeTagNumber(tag_number)
435
436 b_data = b_data[length_offset:]
437
438 length = struct.unpack("B", b_data[:1])[0]
439 length_octets = 1
440
441 if length & 0b10000000:
442 # If the MSB is set then the length octet just contains the number of octets that encodes the actual length.
443 length_octets += length & 0b01111111
444 length = 0
445
446 for idx in range(1, length_octets):
447 octet_val = struct.unpack("B", b_data[idx : idx + 1])[0]
448 length += octet_val << (8 * (length_octets - 1 - idx))
449
450 value = ASN1Value(
451 tag_class=tag_class,
452 constructed=constructed,
453 tag_number=tag_number,
454 b_data=b_data[length_octets : length_octets + length],
455 )
456
457 return value, b_data[length_octets + length :]
458
459
460 def unpack_asn1_bit_string(value: typing.Union[ASN1Value, bytes]) -> bytes:
461 """Unpacks an ASN.1 BIT STRING value."""
462 b_data = extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.bit_string)
463
464 # First octet is the number of unused bits in the last octet from the LSB.
465 unused_bits = struct.unpack("B", b_data[:1])[0]
466 last_octet = struct.unpack("B", b_data[-2:-1])[0]
467 last_octet = (last_octet >> unused_bits) << unused_bits
468
469 return b_data[1:-1] + struct.pack("B", last_octet)
470
471
472 def unpack_asn1_boolean(value: typing.Union[ASN1Value, bytes]) -> bool:
473 """Unpacks an ASN.1 BOOLEAN value."""
474 b_data = extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.boolean)
475
476 return b_data != b"\x00"
477
478
479 def unpack_asn1_enumerated(value: typing.Union[ASN1Value, bytes]) -> int:
480 """Unpacks an ASN.1 ENUMERATED value."""
481 b_data = extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.enumerated)
482
483 return unpack_asn1_integer(b_data)
484
485
486 def unpack_asn1_general_string(value: typing.Union[ASN1Value, bytes]) -> bytes:
487 """Unpacks an ASN.1 GeneralString value."""
488 return extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.general_string)
489
490
491 def unpack_asn1_generalized_time(value: typing.Union[ASN1Value, bytes]) -> datetime.datetime:
492 """Unpacks an ASN.1 GeneralizedTime value."""
493 data = to_text(extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.generalized_time))
494
495 # While ASN.1 can have a timezone encoded, KerberosTime is the only thing we use and it is always in UTC with the
496 # Z prefix. We strip out the Z because Python 2 doesn't support the %z identifier and add the UTC tz to the object.
497 # https://www.rfc-editor.org/rfc/rfc4120#section-5.2.3
498 if data.endswith("Z"):
499 data = data[:-1]
500
501 err = None
502 for datetime_format in ["%Y%m%d%H%M%S.%f", "%Y%m%d%H%M%S"]:
503 try:
504 dt = datetime.datetime.strptime(data, datetime_format)
505 return dt.replace(tzinfo=datetime.timezone.utc)
506 except ValueError as e:
507 err = e
508
509 else:
510 raise err # type: ignore
511
512
513 def unpack_asn1_integer(value: typing.Union[ASN1Value, bytes]) -> int:
514 """Unpacks an ASN.1 INTEGER value."""
515 b_int = bytearray(extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.integer))
516
517 is_negative = b_int[0] & 0b10000000
518 if is_negative:
519 # Get the two's compliment.
520 for i in range(len(b_int)):
521 b_int[i] = 0xFF - b_int[i]
522
523 for i in range(len(b_int) - 1, -1, -1):
524 if b_int[i] == 0xFF:
525 b_int[i - 1] += 1
526 b_int[i] = 0
527 break
528
529 else:
530 b_int[i] += 1
531 break
532
533 int_value = 0
534 for val in b_int:
535 int_value = (int_value << 8) | val
536
537 if is_negative:
538 int_value *= -1
539
540 return int_value
541
542
543 def unpack_asn1_object_identifier(value: typing.Union[ASN1Value, bytes]) -> str:
544 """Unpacks an ASN.1 OBJECT IDENTIFIER value."""
545 b_data = extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.object_identifier)
546
547 first_element = struct.unpack("B", b_data[:1])[0]
548 second_element = first_element % 40
549 ids = [(first_element - second_element) // 40, second_element]
550
551 idx = 1
552 while idx != len(b_data):
553 oid, octet_len = _unpack_asn1_octet_number(b_data[idx:])
554 ids.append(oid)
555 idx += octet_len
556
557 return ".".join([str(i) for i in ids])
558
559
560 def unpack_asn1_octet_string(value: typing.Union[ASN1Value, bytes]) -> bytes:
561 """Unpacks an ASN.1 OCTET STRING value."""
562 return extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.octet_string)
563
564
565 def unpack_asn1_sequence(value: typing.Union[ASN1Value, bytes]) -> typing.List[ASN1Value]:
566 """Unpacks an ASN.1 SEQUENCE value."""
567 b_data = extract_asn1_tlv(value, TagClass.universal, TypeTagNumber.sequence)
568
569 values = []
570 while b_data:
571 v, b_data = unpack_asn1(b_data)
572 values.append(v)
573
574 return values
575
576
577 def unpack_asn1_tagged_sequence(value: typing.Union[ASN1Value, bytes]) -> typing.Dict[int, ASN1Value]:
578 """Unpacks an ASN.1 SEQUENCE value as a dictionary."""
579 return dict([(e.tag_number, unpack_asn1(e.b_data)[0]) for e in unpack_asn1_sequence(value)])
580
581
582 def _unpack_asn1_octet_number(b_data: bytes) -> typing.Tuple[int, int]:
583 """Unpacks an ASN.1 INTEGER value that can span across multiple octets."""
584 i = 0
585 idx = 0
586 while True:
587 element = struct.unpack("B", b_data[idx : idx + 1])[0]
588 idx += 1
589
590 i = (i << 7) + (element & 0b01111111)
591 if not element & 0b10000000:
592 break
593
594 return i, idx # int value and the number of octets used.