synta 0.1.11

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
109
110
111
112
113
114

# ACE-88 Authentication Context Extension (RFC 7773)

`synta.AuthenticationContextsBuilder` constructs DER-encoded
`AuthenticationContexts` structures for the `id-ce-authContext` X.509v3
extension (OID `1.2.752.201.5.1`), as defined in RFC 7773.  The builder is
exported directly from the top-level `synta` module.

The authentication context extension binds one or more authentication context
identifiers to an end-entity certificate.  Each context entry has a mandatory
`contextType` URI and an optional `contextInfo` URL pointing to a machine- or
human-readable document that describes the context.  The resulting DER bytes go
inside the OCTET STRING wrapper of an `Extension` SEQUENCE.

This extension is used by the Swedish e-ID infrastructure
(e-Legitimationsnämnden) to link certificates to specific authentication
frameworks.

## AuthenticationContextsBuilder

Fluent builder for an `AuthenticationContexts` DER SEQUENCE OF (RFC 7773 /
ACE-88).

At least one entry must be added before calling `build()`.

```python
class AuthenticationContextsBuilder:
    def __init__(self) -> None: ...

    def add(
        self,
        context_type: str,
        context_info: str | None = None,
    ) -> AuthenticationContextsBuilder: ...
    # Add an AuthenticationContext entry.
    # context_type: URI string identifying the authentication context,
    #   e.g. "urn:id:skatteverket:2:1.0".
    # context_info: optional URL pointing to a document describing the context,
    #   or None to omit the field.
    # Raises ValueError if DER encoding fails (deferred to build()).

    def build(self) -> bytes: ...
    # Build the DER-encoded AuthenticationContexts SEQUENCE OF.
    # Raises ValueError if no entries were added or DER encoding fails.
```

## Extension OID

| OID | Name | Description |
|-----|------|-------------|
| `1.2.752.201.5.1` | `id-ce-authContext` | Authentication Contexts extension |

## Usage

### Single context, no context info

```python,ignore
import synta

extn_der = (
    synta.AuthenticationContextsBuilder()
    .add("urn:id:skatteverket:2:1.0")
    .build()
)
```

### Multiple contexts with context info URLs

```python,ignore
import synta

extn_der = (
    synta.AuthenticationContextsBuilder()
    .add(
        "urn:id:skatteverket:2:1.0",
        "https://www.skatteverket.se/ac/context2.xml",
    )
    .add(
        "urn:id:skatteverket:1:1.0",
        "https://www.skatteverket.se/ac/context1.xml",
    )
    .build()
)
```

### Embedding in a certificate extension

The bytes from `build()` are the raw `extnValue` content.  To embed the
extension in a certificate, wrap the DER in an OCTET STRING and encode the
`Extension` SEQUENCE:

```python,ignore
import synta

extn_der = (
    synta.AuthenticationContextsBuilder()
    .add("urn:id:skatteverket:2:1.0")
    .build()
)

# OID arc components for id-ce-authContext
ID_CE_AUTH_CONTEXT = [1, 2, 752, 201, 5, 1]

# Build the Extension SEQUENCE and add it to a certificate builder
cert_der = (
    synta.CertificateBuilder()
    # ... set subject, issuer, validity, public key ...
    .extension(ID_CE_AUTH_CONTEXT, critical=False, value=extn_der)
    .build()
)
```

See also [X.509 Extension Value Builders](ext-builders.md) for the standard
extension value helpers, and [Logotype Extension](logotype.md) for another
X.509v3 extension builder.