Add parsing for SpcPeImageData, SpcFinancialCriteria and SpcSpAgencyInfo

docs/changelog.rst

@@ -4,14 +4,29 @@ This page contains the most significant changes in Signify between each release.
 
 v0.7.0 (unreleased)
 -------------------
-* Remove dependency of ``pyasn1`` and ``pyasn1-modules`` entirely to provide more robust parsing. The replacement,
-  ``asn1crypto``, was already a dependency of this project, so we are mostly slimming down. This does have a serious
-  impact if you use certain functions to deeply inspect the original data (as all these structures have now changed)
-  and on some parts of the API to better align with the new dependency. Most notably, all OIDs are now strings,
-  rather than integer tuples, and references to attributes and subclasses are now strings as well (such as in
-  attribute lists).
-
-* Add support for SignedData versions other than v1
+* Remove dependency of ``pyasn1`` and ``pyasn1-modules`` entirely to provide more robust
+  parsing of ASN.1 structures, adding the ability to parse structures independent of
+  RFC version. Certain bugs bugs we've encountered in the past, have now been resolved
+  as a result of this. On top of that, structures defined in the replacement,
+  ``asn1crypto`` are a lot more Pythonic, and parsing speed has been sliced in more
+  than half.
+* This does have a serious impact if you use certain functions to deeply inspect the
+  original data (as all these structures have now changed) and on some parts of the API
+  to better align with the new dependency. Most notably, all OIDs are now strings,
+  rather than integer tuples, and references to attributes and subclasses are now
+  strings as well (such as in attribute lists).
+
+* Add support for ``SignedData`` versions other than v1
+* Add support for ``SignerInfo`` versions other than v1
+* Parse the ``SpcPeImageData`` as part of the SpcInfo. This adds the attributes
+  ``image_flags`` and ``image_publisher``, although this information is never used.
+* Parse the ``SpcStatementType`` as part of the authenticated attributes of the
+  ``AuthenticodeSignerInfo``. This adds the attribute ``statement_types``, although this
+  information is never used.
+* Parse the ``SpcFinancialCriteria`` (``microsoft_spc_financial_criteria``) and
+  (partially) ``SpcSpAgencyInfo`` (``microsoft_spc_sp_agency_info``) as part of the
+  ``extensions`` of ``Certificate``. These extensions are poorly documented, but may
+  provide some additional information, such as when researching CVE-2019–1388.
 
 v0.6.1 (2024-03-21)
 -------------------

signify/asn1/ctl.py

@@ -19,25 +19,51 @@
 from asn1crypto.util import utc_with_dst
 from asn1crypto.x509 import Extensions, ExtKeyUsageSyntax, Time
 
-# Based on http://download.microsoft.com/download/C/8/8/C8862966-5948-444D-87BD-07B976ADA28C/%5BMS-CAESO%5D.pdf
+# Based on https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf
 
 
 class CTLVersion(Integer):  # type: ignore[misc]
+    """Version of the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+        CTLVersion ::= INTEGER {v1(0)}
+    """
+
     _map = {
         0: "v1",
     }
 
 
 class SubjectUsage(ExtKeyUsageSyntax):  # type: ignore[misc]
-    pass
+    """Subject usage of the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+        SubjectUsage ::= EnhancedKeyUsage
+    """
 
 
 class ListIdentifier(OctetString):  # type: ignore[misc]
-    pass
+    """List identifier of the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+         ListIdentifier ::= OCTETSTRING
+    """
 
 
 class SubjectIdentifier(OctetString):  # type: ignore[misc]
-    pass
+    """Subject identifier of the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+         SubjectIdentifier ::= OCTETSTRING
+    """
 
 
 class SubjectAttributeType(ObjectIdentifier):  # type: ignore[misc]
@@ -57,6 +83,10 @@ class SubjectAttributeType(ObjectIdentifier):  # type: ignore[misc]
 
 
 class SetOfSpecificOctetString(SetOf):  # type: ignore[misc]
+    """Specific implementation of a SetOf OctetString that allows parsing directly as
+    a value, or as a sequence, depending on the child type.
+    """
+
     _child_spec = OctetString
     children: Any
 
@@ -105,6 +135,12 @@ def set(self, value: Any) -> None:
 
 
 class SubjectAttribute(Sequence):  # type: ignore[misc]
+    """Subject attributes of the trusted subject in the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_.
+    """
+
     _fields = [
         ("type", SubjectAttributeType),
         ("values", SetOfSpecificOctetString),
@@ -130,21 +166,64 @@ def _values_spec(self) -> type[Asn1Value] | None:
 
 
 class SubjectAttributes(SetOf):  # type: ignore[misc]
+    """Subject attributes of the trusted subject in the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_.
+    """
+
     _child_spec = SubjectAttribute
 
 
 class TrustedSubject(Sequence):  # type: ignore[misc]
+    """Trusted subject in the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+         TrustedSubject ::= SEQUENCE{
+            subjectIdentifier SubjectIdentifier,
+            subjectAttributes Attributes OPTIONAL
+         }
+    """
+
     _fields = [
         ("subject_identifier", SubjectIdentifier),
         ("subject_attributes", SubjectAttributes, {"optional": True}),
     ]
 
 
 class TrustedSubjects(SequenceOf):  # type: ignore[misc]
+    """Trusted subjects in the CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+        TrustedSubjects ::= SEQUENCE OF TrustedSubject
+    """
+
     _child_spec = TrustedSubject
 
 
 class CertificateTrustList(Sequence):  # type: ignore[misc]
+    """CTL structure.
+
+    Based on `MS-CAESO
+    <https://winprotocoldoc.blob.core.windows.net/productionwindowsarchives/WinArchive/%5bMS-CAESO%5d.pdf>`_::
+
+         CertificateTrustList ::= SEQUENCE {
+             version CTLVersion DEFAULT v1,
+             subjectUsage SubjectUsage,
+             listIdentifier ListIdentifier OPTIONAL,
+             sequenceNumber HUGEINTEGER OPTIONAL,
+             ctlThisUpdate ChoiceOfTime,
+             ctlNextUpdate ChoiceOfTime OPTIONAL,
+             subjectAlgorithm AlgorithmIdentifier,
+             trustedSubjects TrustedSubjects OPTIONAL,
+             ctlExtensions [0] EXPLICIT Extensions OPTIONAL
+         }
+    """
+
     _fields = [
         ("version", CTLVersion, {"default": "v1"}),
         ("subject_usage", SubjectUsage),