synta 0.2.5

ASN.1 parser, decoder, and encoder library with DER/BER support and C FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# GeneralName Constants


`synta.general_name` provides:

- **Integer tag constants** for the `GeneralName` CHOICE type (RFC 5280 §4.2.1.6),
  used when dispatching on results from the low-level `synta.parse_general_names()`.
- **Typed Python classes** — one per `GeneralName` alternative — returned by the
  high-level `Certificate.subject_alt_names()` and `Certificate.general_names()` methods.

```python
import synta.general_name as gn
```

## Typed GeneralName classes

`Certificate.subject_alt_names()` returns a list of instances of these classes:

| Class | `GeneralName` alternative | Key properties |
|---|---|---|
| `OtherName` | `otherName` | `.type_id` (OID), `.value` (raw DER bytes of the ANY value) |
| `RFC822Name` | `rfc822Name` | `.value` (str — e-mail address) |
| `DNSName` | `dNSName` | `.value` (str — DNS host name) |
| `X400Address` | `x400Address` | `.raw_der` (bytes) |
| `DirectoryName` | `directoryName` | `.name_der` (bytes — complete Name SEQUENCE TLV) |
| `EDIPartyName` | `ediPartyName` | `.raw_der` (bytes) |
| `UniformResourceIdentifier` | `uniformResourceIdentifier` | `.value` (str — URI) |
| `IPAddress` | `iPAddress` | `.address` (bytes — 4 for IPv4, 16 for IPv6) |
| `RegisteredID` | `registeredID` | `.oid` (ObjectIdentifier) |

## Integer tag constants

These integer constants correspond to the first element of tuples returned by the
low-level `synta.parse_general_names()`:

| Constant | Value | `GeneralName` alternative |
|---|---|---|
| `OTHER_NAME` | 0 | `otherName` |
| `RFC822_NAME` | 1 | `rfc822Name` |
| `DNS_NAME` | 2 | `dNSName` |
| `X400_ADDRESS` | 3 | `x400Address` |
| `DIRECTORY_NAME` | 4 | `directoryName` |
| `EDI_PARTY_NAME` | 5 | `ediPartyName` |
| `URI` | 6 | `uniformResourceIdentifier` |
| `IP_ADDRESS` | 7 | `iPAddress` |
| `REGISTERED_ID` | 8 | `registeredID` |

## parse_general_names

```text
synta.parse_general_names(san_der: bytes) -> list[tuple[int, bytes]]
```

Low-level function: parses a DER `SEQUENCE OF GeneralName` into `(tag_number, content)`
pairs. Use the integer tag constants above to dispatch on `tag_number`. This function is
the low-level alternative to `Certificate.subject_alt_names()` — use it when you have raw
extension value bytes from `cert.get_extension_value_der(...)` and do not need typed objects.

## parse_name_attrs

```text
synta.parse_name_attrs(name_der: bytes) -> list[tuple[str, str]]
```

Walk a DER Name SEQUENCE and return `(dotted_oid, value_str)` pairs in traversal order.
Pass `DirectoryName.name_der` (a complete Name SEQUENCE TLV) to this function.

## High-level dispatch pattern

```python
import ipaddress
import synta
import synta.general_name as gn

# subject_alt_names() returns typed objects — use isinstance for dispatch
for name in cert.subject_alt_names():
    if isinstance(name, gn.DNSName):
        print("DNS:", name.value)
    elif isinstance(name, gn.IPAddress):
        print("IP:", ipaddress.ip_address(name.address))
    elif isinstance(name, gn.RFC822Name):
        print("email:", name.value)
    elif isinstance(name, gn.UniformResourceIdentifier):
        print("URI:", name.value)
    elif isinstance(name, gn.DirectoryName):
        attrs = synta.parse_name_attrs(name.name_der)   # [(oid_str, value_str), …]
        print("DirName:", attrs)
    elif isinstance(name, gn.OtherName):
        print("OtherName type_id:", name.type_id)
```

## Low-level dispatch (tag/bytes pairs)

Use `synta.parse_general_names(san_der)` directly on raw `extnValue` bytes when you
want `(tag_number, content_bytes)` tuples rather than typed objects:

```python
san_der = cert.get_extension_value_der(synta.oids.SUBJECT_ALT_NAME)
if san_der:
    for tag_num, content in synta.parse_general_names(san_der):
        if tag_num == gn.DNS_NAME:
            print("DNS:", content.decode("ascii"))
        elif tag_num == gn.IP_ADDRESS:
            print("IP:", ipaddress.ip_address(content))
```

See also [Certificate](certificate.md) for `subject_alt_names()` and the
[Well-known OIDs](../oids/oids.md) page for `synta.oids.SUBJECT_ALT_NAME` and related constants.