asn1: Add tutorial to the docs (#14624)

* asn1: Update CHANGELOG

* asn1: Add tutorial doc

* add 'declaratively' to spelling wordlist

Author: facutuesca

CHANGELOG.rst

@@ -91,6 +91,8 @@ Changelog
   hybrid authenticated encryption.
 * Added new :doc:`/hazmat/primitives/asymmetric/mldsa` module with
   support for ML-DSA signing and verification with the AWS-LC backend.
+* Added new :doc:`/hazmat/asn1/index` module with support for declaratively
+  defining custom ASN.1 types and encoding/decoding them.
 
 .. v46-0-7:
 

docs/hazmat/asn1/index.rst

@@ -10,4 +10,5 @@ ASN.1
 .. toctree::
     :maxdepth: 2
 
+    tutorial
     reference

docs/hazmat/asn1/reference.rst

@@ -3,7 +3,7 @@
 ASN.1 Reference
 ===============
 
-.. currentmodule:: cryptography.hazmat.asn1
+.. module:: cryptography.hazmat.asn1
 
 This module provides a declarative interface for defining ASN.1 structures
 and serializing/deserializing them to/from DER-encoded data.

docs/hazmat/asn1/tutorial.rst

@@ -0,0 +1,343 @@
+.. hazmat::
+
+Tutorial
+========
+
+.. note::
+    While usable, these APIs should be considered unstable and not yet
+    subject to our backwards compatibility policy.
+
+The :mod:`cryptography.hazmat.asn1` module provides a declarative API for
+working with ASN.1 data. ASN.1 structures are defined as Python classes
+with type annotations, and the module uses those definitions to
+serialize and deserialize instances to and from DER-encoded bytes.
+
+Type mapping
+------------
+
+The following table shows how ASN.1 types map to Python types:
+
+.. list-table::
+   :header-rows: 1
+
+   * - ASN.1 type
+     - Python type
+   * - ``BOOLEAN``
+     - :class:`bool`
+   * - ``INTEGER``
+     - :class:`int`
+   * - ``BIT STRING``
+     - :class:`~cryptography.hazmat.asn1.BitString`
+   * - ``OCTET STRING``
+     - :class:`bytes`
+   * - ``NULL``
+     - :class:`~cryptography.hazmat.asn1.Null`
+   * - ``OBJECT IDENTIFIER``
+     - :class:`~cryptography.x509.ObjectIdentifier`
+   * - ``UTF8String``
+     - :class:`str`
+   * - ``PrintableString``
+     - :class:`~cryptography.hazmat.asn1.PrintableString`
+   * - ``IA5String``
+     - :class:`~cryptography.hazmat.asn1.IA5String`
+   * - ``UTCTime``
+     - :class:`~cryptography.hazmat.asn1.UTCTime`
+   * - ``GeneralizedTime``
+     - :class:`~cryptography.hazmat.asn1.GeneralizedTime`
+   * - ``SEQUENCE``
+     - :func:`@sequence <cryptography.hazmat.asn1.sequence>`-decorated class
+   * - ``SEQUENCE OF``
+     - :class:`list`\[T]
+   * - ``SET OF``
+     - :class:`~cryptography.hazmat.asn1.SetOf`\[T]
+   * - ``CHOICE``
+     - ``X | Y | ...``
+   * - ``ANY``
+     - :class:`~cryptography.hazmat.asn1.TLV`
+   * - ``OPTIONAL``
+     - ``X | None``
+
+Defining a SEQUENCE
+-------------------
+
+ASN.1 ``SEQUENCE`` types map to Python classes decorated with
+:func:`@sequence <cryptography.hazmat.asn1.sequence>`. Fields are defined as type annotations. For example,
+given the following ASN.1 definition:
+
+.. code-block:: none
+
+    Point ::= SEQUENCE {
+         x      INTEGER,
+         y      INTEGER }
+
+The corresponding Python definition is:
+
+.. doctest::
+
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Point:
+    ...     x: int
+    ...     y: int
+
+The decorator adds an ``__init__`` with keyword-only parameters:
+
+.. doctest::
+
+    >>> p = Point(x=3, y=7)
+    >>> p.x
+    3
+
+Encoding and decoding
+---------------------
+
+Use :func:`~cryptography.hazmat.asn1.encode_der` to serialize an ASN.1 object to DER bytes, and
+:func:`~cryptography.hazmat.asn1.decode_der` to deserialize:
+
+.. doctest::
+
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Point:
+    ...     x: int
+    ...     y: int
+    >>> encoded = asn1.encode_der(Point(x=1, y=2))
+    >>> encoded
+    b'0\x06\x02\x01\x01\x02\x01\x02'
+    >>> point = asn1.decode_der(Point, encoded)
+    >>> point.x
+    1
+    >>> point.y
+    2
+
+Primitive types can also be encoded and decoded directly, without wrapping
+them in a sequence:
+
+.. doctest::
+
+    >>> asn1.encode_der(42)
+    b'\x02\x01*'
+    >>> asn1.decode_der(int, b'\x02\x01*')
+    42
+
+Nested sequences
+----------------
+
+Sequences can contain other sequences as field types:
+
+.. doctest::
+
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Name:
+    ...     value: str
+    >>> @asn1.sequence
+    ... class Certificate:
+    ...     version: int
+    ...     subject: Name
+    >>> cert = Certificate(version=1, subject=Name(value="Alice"))
+    >>> decoded = asn1.decode_der(Certificate, asn1.encode_der(cert))
+    >>> decoded.subject.value
+    'Alice'
+
+OPTIONAL fields
+---------------
+
+A field with a ``Union[X, None]`` (or ``X | None``) type annotation is
+treated as ASN.1 ``OPTIONAL``. When the value is ``None``, the field is
+omitted from the encoding:
+
+.. doctest::
+
+    >>> import typing
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Record:
+    ...     required: int
+    ...     optional: typing.Union[str, None]
+    >>> asn1.encode_der(Record(required=1, optional="hi"))
+    b'0\x07\x02\x01\x01\x0c\x02hi'
+    >>> asn1.encode_der(Record(required=1, optional=None))
+    b'0\x03\x02\x01\x01'
+
+DEFAULT values
+--------------
+
+Use :class:`~cryptography.hazmat.asn1.Default` with :data:`typing.Annotated` to specify a default
+value for a field. When encoding, if the field's value equals the default,
+it is omitted. When decoding, if the field is absent, the default is used:
+
+.. doctest::
+
+    >>> from typing import Annotated
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class VersionedRecord:
+    ...     version: Annotated[int, asn1.Default(0)]
+    ...     data: bytes
+    >>> asn1.encode_der(VersionedRecord(version=1, data=b"\x01"))
+    b'0\x06\x02\x01\x01\x04\x01\x01'
+    >>> # version=0 equals the default, so it is omitted from the encoding
+    >>> asn1.encode_der(VersionedRecord(version=0, data=b"\x01"))
+    b'0\x03\x04\x01\x01'
+
+CHOICE fields
+-------------
+
+A field with a ``Union`` of multiple non-``None`` types is treated as an
+ASN.1 ``CHOICE``. Each variant must have a distinct ASN.1 tag:
+
+.. doctest::
+
+    >>> import typing
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Example:
+    ...     value: typing.Union[int, bool, str]
+    >>> asn1.decode_der(Example, asn1.encode_der(Example(value=42))).value
+    42
+    >>> asn1.decode_der(Example, asn1.encode_der(Example(value=True))).value
+    True
+
+When multiple alternatives share the same underlying type, a plain union
+can't distinguish them (``Union[int, int]`` is just ``int``). Wrap the types with
+:class:`~cryptography.hazmat.asn1.Variant` and add
+:class:`~cryptography.hazmat.asn1.Implicit` tags to differentiate
+between them:
+
+.. doctest::
+
+    >>> import typing
+    >>> from typing import Annotated
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Example:
+    ...     field: typing.Union[
+    ...         Annotated[asn1.Variant[int, typing.Literal["IntA"]], asn1.Implicit(0)],
+    ...         Annotated[asn1.Variant[int, typing.Literal["IntB"]], asn1.Implicit(1)],
+    ...     ]
+    >>> obj = Example(field=asn1.Variant(9, "IntA"))
+    >>> decoded = asn1.decode_der(Example, asn1.encode_der(obj))
+    >>> decoded.field.value
+    9
+    >>> decoded.field.tag
+    'IntA'
+
+EXPLICIT and IMPLICIT tagging
+------------------------------
+
+Use :class:`~cryptography.hazmat.asn1.Explicit` and :class:`~cryptography.hazmat.asn1.Implicit` annotations to apply ASN.1
+context-specific tags to fields:
+
+.. doctest::
+
+    >>> from typing import Annotated
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Tagged:
+    ...     explicit_field: Annotated[int, asn1.Explicit(0)]
+    ...     implicit_field: Annotated[int, asn1.Implicit(1)]
+    >>> encoded = asn1.encode_der(Tagged(explicit_field=5, implicit_field=10))
+    >>> decoded = asn1.decode_der(Tagged, encoded)
+    >>> decoded.explicit_field
+    5
+    >>> decoded.implicit_field
+    10
+
+Tagging is typically needed to disambiguate ``OPTIONAL`` fields that would
+otherwise share the same tag:
+
+.. doctest::
+
+    >>> import typing
+    >>> from typing import Annotated
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Example:
+    ...     a: Annotated[typing.Union[int, None], asn1.Implicit(0)]
+    ...     b: Annotated[typing.Union[int, None], asn1.Implicit(1)]
+    >>> asn1.decode_der(Example, asn1.encode_der(Example(a=9, b=None))).a
+    9
+    >>> asn1.decode_der(Example, asn1.encode_der(Example(a=None, b=9))).b
+    9
+
+SEQUENCE OF and SET OF
+----------------------
+
+Use :class:`list`\[T] for ``SEQUENCE OF`` and :class:`~cryptography.hazmat.asn1.SetOf` for
+``SET OF``:
+
+.. doctest::
+
+    >>> import typing
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class IntList:
+    ...     values: typing.List[int]
+    >>> decoded = asn1.decode_der(IntList, asn1.encode_der(IntList(values=[1, 2, 3])))
+    >>> decoded.values
+    [1, 2, 3]
+
+``SET OF`` elements are sorted in DER encoding:
+
+.. doctest::
+
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class IntSet:
+    ...     values: asn1.SetOf[int]
+    >>> decoded = asn1.decode_der(IntSet, asn1.encode_der(IntSet(values=asn1.SetOf([3, 1, 2]))))
+    >>> decoded.values.as_list()
+    [1, 2, 3]
+
+Size constraints
+----------------
+
+Use :class:`~cryptography.hazmat.asn1.Size` to restrict the length of collection and string fields:
+
+.. doctest::
+
+    >>> import typing
+    >>> from typing import Annotated
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class BoundedList:
+    ...     values: Annotated[typing.List[int], asn1.Size(min=1, max=4)]
+    >>> asn1.encode_der(BoundedList(values=[1, 2]))
+    b'0\x080\x06\x02\x01\x01\x02\x01\x02'
+
+A real-world example
+--------------------
+
+Here is a more complete example modeling the X.509 ``Validity`` structure:
+
+.. code-block:: none
+
+    Validity ::= SEQUENCE {
+         notBefore      Time,
+         notAfter       Time  }
+
+    Time ::= CHOICE {
+         utcTime        UTCTime,
+         generalTime    GeneralizedTime }
+
+This translates to:
+
+.. doctest::
+
+    >>> import typing
+    >>> import datetime
+    >>> from typing import Annotated
+    >>> from cryptography.hazmat import asn1
+    >>> @asn1.sequence
+    ... class Validity:
+    ...     not_before: typing.Union[asn1.UTCTime, asn1.GeneralizedTime]
+    ...     not_after: typing.Union[asn1.UTCTime, asn1.GeneralizedTime]
+    >>> not_before = asn1.UTCTime(datetime.datetime(2025, 1, 1, tzinfo=datetime.timezone.utc))
+    >>> not_after = asn1.UTCTime(datetime.datetime(2026, 1, 1, tzinfo=datetime.timezone.utc))
+    >>> validity = Validity(not_before=not_before, not_after=not_after)
+    >>> decoded = asn1.decode_der(Validity, asn1.encode_der(validity))
+    >>> decoded.not_before.as_datetime().year
+    2025
+    >>> decoded.not_after.as_datetime().year
+    2026

docs/spelling_wordlist.txt

@@ -36,6 +36,7 @@ cryptographically
 de
 Debian
 deallocated
+declaratively
 decrypt
 decrypts
 Decrypts