asn1: Add support for CHOICE fields by facutuesca · Pull Request #14201 · pyca/cryptography

facutuesca · 2026-01-24T15:36:58Z

Following the discussion in #14183, here's an alternative implementation for CHOICE fields.
If one of the types inside the union is a asn1.Variant, all the other types should be too.

# all types in the union are asn1.Variant
@asn1.sequence
class Example:
    foo: (
        Annotated[Variant[int, typing.Literal["Tag1"]], asn1.Implicit(0)]
        | Annotated[Variant[int, typing.Literal["Tag2"]], asn1.Implicit(1)]
        | Annotated[Variant[str, typing.Literal["Tag3"]], asn1.Implicit(2)]
        | Annotated[Variant[bool, typing.Literal["Tag4"]], asn1.Implicit(3)]
    )

obj = Example(foo=Variant(42, "Tag1"))
encoded = encode_der(obj)

decoded = decode(Example, encoded)
assert isinstance(decoded.foo.value, int)
assert decoded.foo.tag == "Tag1"
assert decoded.foo.value == 42


# none of the types in the union are asn1.Variant
@asn1.sequence
class Example:
    foo: (
        | Annotated[str, asn1.Implicit(0)]
        | Annotated[bool, asn1.Implicit(1)]
    )

Part of #12283

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

alex · 2026-01-25T14:27:04Z

I haven't reviewed the impl closely yet, but this is probably my favorite of the various APIs we've brainstormed. @reaperhulk wdyt?

reaperhulk · 2026-01-25T15:01:55Z

Hmm, what does this look like when applied to the basic real world example of a generalname? (I would actually do this myself but am currently mobile)

facutuesca · 2026-01-25T17:46:56Z

Hmm, what does this look like when applied to the basic real world example of a generalname? (I would actually do this myself but am currently mobile)

Something like this (assuming the non-trivial types are defined elsewhere):

#   GeneralName ::= CHOICE {
#        otherName                       [0]     OtherName,
#        rfc822Name                      [1]     IA5String,
#        dNSName                         [2]     IA5String,
#        x400Address                     [3]     ORAddress,
#        directoryName                   [4]     Name,
#        ediPartyName                    [5]     EDIPartyName,
#        uniformResourceIdentifier       [6]     IA5String,
#        iPAddress                       [7]     OCTET STRING,
#        registeredID                    [8]     OBJECT IDENTIFIER }

GeneralName: typing.TypeAlias = (
    Annotated[OtherName, asn1.Implicit(0)]
    | Annotated[
        asn1.Variant[asn1.IA5String, typing.Literal["rfc822Name"]],
        asn1.Implicit(1),
    ]
    | Annotated[
        asn1.Variant[asn1.IA5String, typing.Literal["dNSName"]],
        asn1.Implicit(2),
    ]
    | Annotated[ORAddress, asn1.Implicit(3)]
    | Annotated[Name, asn1.Implicit(4)]
    | Annotated[EDIPartyName, asn1.Implicit(5)]
    | Annotated[
        asn1.Variant[
            asn1.IA5String, typing.Literal["uniformResourceIdentifier"]
        ],
        asn1.Implicit(6),
    ]
    | Annotated[bytes, asn1.Implicit(7)]
    | Annotated[x509.ObjectIdentifier, asn1.Implicit(8)]
)

@asn1.sequence
class Example:
    name: GeneralName

obj = Example(name=asn1.Variant(asn1.IA5String("abcd"), "dNSName"))
encoded = encode_der(obj)

decoded = decode(Example, encoded)
assert isinstance(decoded.name.value, asn1.IA5String)
assert decoded.name.tag == "dNSName"
assert decoded.name.value.as_str() == "abcd"

facutuesca · 2026-01-25T18:11:28Z

I wonder if maybe we should require the use of Variant with a tag for all the possible types? Makes the API more uniform, both when declaring the types but also when the user needs to get the type and value from a decoded variant. Downside is that it's more verbose.

# current API, this would be the `iPAddress [7] OCTET STRING` variant
obj = Example(name=b"\x01\x02")
encoded = encode_der(obj)

decoded = decode(Example, encoded)
assert isinstance(decoded.name, bytes)
assert decoded.name == b"\x01\x02"


# API where every variant is defined with a `Variant(type, tag)` annotation
GeneralName: typing.TypeAlias = (
#...
    | Annotated[
        asn1.Variant[bytes, typing.Literal["iPAddress"]],
        asn1.Implicit(7),
    ]
# ...

obj = Example(name=asn1.Variant(b"\x01\x02", "iPAddress"))
encoded = encode_der(obj)

decoded = decode(Example, encoded)

assert isinstance(decoded.name.value, bytes)
assert decoded.name.tag == "ipAddress"
assert decoded.name.value == b"\x01\x02"

alex · 2026-01-25T18:47:35Z

Either all variant or no-variant perhaps.

facutuesca · 2026-01-25T18:50:44Z

Either all variant or no-variant perhaps.

how would no-variant work?

alex · 2026-01-25T18:53:41Z

Would be fine for cases where all the variants have different types, and therefore don't need anything to disambiguate them.

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

facutuesca · 2026-01-25T21:35:43Z

Would be fine for cases where all the variants have different types, and therefore don't need anything to disambiguate them.

Done, I also updated the PR description with the changes.

alex · 2026-01-27T01:32:51Z

src/cryptography/hazmat/asn1/asn1.py

+Tag = typing.TypeVar("Tag")
+
+
+@dataclasses.dataclass(frozen=True)
+class Variant(typing.Generic[U, Tag]):
+    """
+    A tagged variant for CHOICE fields with the same underlying type.
+
+    Use this when you have multiple CHOICE alternatives with the same type
+    and need to distinguish between them:
+
+        foo: (
+            Annotated[Variant[int, "IntA"], Implicit(0)]
+            | Annotated[Variant[int, "IntB"], Implicit(1)]
+        )
+
+    Usage:
+        example = Example(foo=Variant(5, "IntA"))
+        decoded.foo.value  # The int value
+        decoded.foo.tag    # "IntA" or "IntB"
+    """
+
+    value: U
+    tag: str


Does Tag either need to be annotated to indicate its a Literal[str], or should we just allow arbitrary tag types?

the docstring is wrong, fixed

My question was more about the Tag TypeVar.

How would you annotate it? Literal[str] is not a valid expression

I'm not sure! The answer is maybe that this is all correct -- but I was wondering if the Tag typevar should have a bound of some sort on it?

We can add a bound of LiteralString. It's not perfect, str and any subclass of str will pass the type check if passed as a Tag, but we can catch those at runtime.

So something like:

Tag = typing.TypeVar("Tag", bound=typing.LiteralString) @dataclasses.dataclass(frozen=True) class Variant(typing.Generic[U, Tag]):

and we keep the runtime check for Tag being a typing.Literal.

I pushed a commit with this ^ change

src/cryptography/hazmat/asn1/asn1.py

alex · 2026-01-27T01:36:17Z

src/rust/src/declarative_asn1/decode.rs

+        let expected_tags = expected_tags_for_type(py, inner, encoding);
+        match parser.peek_tag() {
+            Some(next_tag) if expected_tags.contains(&next_tag) => (),
+            _ => return Ok(default.clone_ref(py).into_bound(py)),


this seems bad, in that it's going to result in tons of allocations, can we instead have an is_tag_valid_for_type or something?

ah good catch, fixed

src/rust/src/declarative_asn1/decode.rs

alex · 2026-01-27T01:38:46Z

tests/hazmat/asn1/test_serialization.py

+        assert_roundtrips([(Example(foo=9), b"\x30\x03\x02\x01\x09")])
+        assert_roundtrips([(Example(foo=True), b"\x30\x03\x01\x01\xff")])
+        assert_roundtrips([(Example(foo="a"), b"\x30\x03\x0c\x01a")])


Why three cals to assert_roundtrips, rather than passing a list to the function.

Co-authored-by: Alex Gaynor <alex.gaynor@gmail.com>

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

alex · 2026-01-29T12:55:33Z

src/cryptography/hazmat/asn1/asn1.py

+Tag = typing.TypeVar("Tag")
+
+
+@dataclasses.dataclass(frozen=True)
+class Variant(typing.Generic[U, Tag]):
+    """
+    A tagged variant for CHOICE fields with the same underlying type.
+
+    Use this when you have multiple CHOICE alternatives with the same type
+    and need to distinguish between them:
+
+        foo: (
+            Annotated[Variant[int, "IntA"], Implicit(0)]
+            | Annotated[Variant[int, "IntB"], Implicit(1)]
+        )
+
+    Usage:
+        example = Example(foo=Variant(5, "IntA"))
+        decoded.foo.value  # The int value
+        decoded.foo.tag    # "IntA" or "IntB"
+    """
+
+    value: U
+    tag: str


My question was more about the Tag TypeVar.

src/rust/src/declarative_asn1/decode.rs

src/rust/src/declarative_asn1/types.rs

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

alex · 2026-01-31T16:24:41Z

tests/hazmat/asn1/test_serialization.py

+        assert_roundtrips(
+            [(Example(foo=True, bar=1), b"\x30\x06\x01\x01\xff\x02\x01\x01")]
+        )
+
+        assert_roundtrips(
+            [(Example(foo=None, bar=1), b"\x30\x03\x02\x01\x01")]
+        )


ni: merge into single call to assert_roundtrips

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

asn1: Add support for CHOICE fields

db9795f

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

facutuesca force-pushed the ft/asn1-choice-2 branch from a4d382e to db9795f Compare January 24, 2026 15:58

facutuesca marked this pull request as ready for review January 24, 2026 16:05

facutuesca mentioned this pull request Jan 24, 2026

asn1 : Add support for CHOICE fields #14183

Closed

facutuesca mentioned this pull request Jan 25, 2026

[META] Declarative API for ASN.1 in Python #12283

Open

only support all Variant, or all non-Variant types

518a166

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

alex reviewed Jan 27, 2026

View reviewed changes

facutuesca and others added 6 commits January 27, 2026 19:25

Update src/cryptography/hazmat/asn1/asn1.py

f6bdd28

Co-authored-by: Alex Gaynor <alex.gaynor@gmail.com>

simplify tests

5d4deb7

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

add comment about implicit CHOICEs

7055eed

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

check that tags are Literal types

9506b46

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

refactor tag check

3c6db8c

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

add tests for missing coverage

35a56da

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

facutuesca force-pushed the ft/asn1-choice-2 branch from 2ce5211 to 35a56da Compare January 27, 2026 21:56

alex reviewed Jan 29, 2026

View reviewed changes

add bound to Tag type

a221748

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

facutuesca mentioned this pull request Jan 29, 2026

asn1: refactor expected tag logic #14231

Merged

facutuesca added 2 commits January 29, 2026 21:50

fix LiteralString usage in Python < 3.11

66b62b8

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

Merge branch 'main' into ft/asn1-choice-2

f8cf5b1

facutuesca changed the title ~~asn1: Add support for CHOICE fields (alternative impl)~~ asn1: Add support for CHOICE fields Jan 29, 2026

alex reviewed Jan 31, 2026

View reviewed changes

remove redundant assert_roundtrips call

1840dd2

Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>

alex approved these changes Jan 31, 2026

View reviewed changes

alex enabled auto-merge (squash) January 31, 2026 22:10

alex merged commit a930581 into pyca:main Jan 31, 2026
67 checks passed

facutuesca deleted the ft/asn1-choice-2 branch January 31, 2026 22:15

Conversation

facutuesca commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alex commented Jan 25, 2026

Uh oh!

reaperhulk commented Jan 25, 2026

Uh oh!

facutuesca commented Jan 25, 2026

Uh oh!

facutuesca commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alex commented Jan 25, 2026

Uh oh!

facutuesca commented Jan 25, 2026

Uh oh!

alex commented Jan 25, 2026

Uh oh!

facutuesca commented Jan 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

facutuesca Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

facutuesca Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

facutuesca commented Jan 24, 2026 •

edited

Loading

facutuesca commented Jan 25, 2026 •

edited

Loading

facutuesca Jan 29, 2026 •

edited

Loading

facutuesca Jan 31, 2026 •

edited

Loading