Catalog Files and Certificate Trust Lists

Microsoft has developed a mechanism to provide lists of trusted objects through so-called Certificate Trust Lists. These CTLs are used to distribute the trusted certificates in Microsoft’s own Certificate Authority program, but also for catalog files that can contain signatures for any type of file on a Windows system.

Certificate Trust Lists are not very well documented, but a 2009 whitepaper does a semi-decent job of defining the used structures. Basically, it is a SignedData object that contains a list of trusted subjects. Both purposes of CTLs use distinct sets of attributes for their trusted subjects.

Root Program Trust Lists

The Microsoft Root Program used to be distributed through Windows Update, although they are now updated independently. The files used for this are named authroot.stl, and the subjects are the root certificates being trusted.

Additional attributes in the CTL describe specific conditions for which the root certificates are valid, allowing selective deprecation of CAs when the need arises. These are described on the Microsoft website, with them being mapped as follows:

Removal

The root is removed from the CTL, and it is no longer trusted. Since the entry is simply removed, we do not need to perform further checks.

EKU Removal

Specific extended key usages are removed from the root certificate. The EKU is no longer available (including for timestamped objects), and is removed from the set of allowed EKU’s in CertificateTrustSubject.extended_key_usages or added to the set of disallowed EKU’s in CertificateTrustSubject.disallowed_extended_key_usages.

Disallow

Disallowed certificates are removed from the CTL and added to a separate Disallow CTL, preventing them from being installed manually. Since the entry is removed from the CTL, we do not need to perform further checks.

Disable

Disabled certificates are no longer trusted, but digital signatures with a timestamp prior to the date of disabling continue to validate. In this case, CertificateTrustSubject.disallowed_filetime will be set.

In the case that only a specific EKU is disabled, it is removed from the set of allowed EKU’s in CertificateTrustSubject.extended_key_usages or added to the set of disallowed EKU’s in CertificateTrustSubject.disallowed_extended_key_usages.

NotBefore

When a root certificate is set to NotBefore, a specific EKU capability of a root certificate is disabled. Certificates issued after the NotBefore date are no longer trusted; certificates issued before the date and digital signatures timestamped before this date are still valid. In this case, the CertificateTrustSubject.not_before_filetime will be set. In the case that this applies to a single EKU, CertificateTrustSubject.not_before_extended_key_usages will be set as well.

The CertificateTrustList object can be used in combination with a signify.x509.CertificateStore to make sure that the certificates in the store are valid according to the additional conditions in the CTL. Use TRUSTED_CERTIFICATE_STORE for a certificate store with associated CTL.

Signify uses a separate project (mscerts) to ensure an up-to-date certificate bundle. This project is maintained by the same authors as Signify.

signify.authenticode.TRUSTED_CERTIFICATE_STORE: A signify.x509.CertificateStore with associated CertificateTrustList.

signify.authenticode.TRUSTED_CERTIFICATE_STORE_NO_CTL: A signify.x509.CertificateStore without an associated CertificateTrustList.

Catalog Files

A special type of CTL-files Windows catalog files (.cat).

Catalog Files (.cat) are used for externally signing files, mostly used in the case of driver files. They can be used to sign virtually any type of file. They are usually found in a subdirectory of C:\Windows\System32\CatRoot.

CertificateTrustList objects

class signify.authenticode.CertificateTrustList(asn1: SignedData)

A subclass of signify.pkcs7.SignedData, containing a list of trusted root certificates. It is based on the following ASN.1 structure:

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
}
CTLVersion ::= INTEGER {v1(0)}
SubjectUsage ::= EnhancedKeyUsage
ListIdentifier ::= OCTETSTRING
TrustedSubjects ::= SEQUENCE OF TrustedSubject
TrustedSubject ::= SEQUENCE{
  subjectIdentifier SubjectIdentifier,
  subjectAttributes Attributes OPTIONAL
}
SubjectIdentifier ::= OCTETSTRING

Warning

The CTL itself is currently not verifiable.

find_subject(subject: Certificate | signed_file.AuthenticodeFile | bytes) → CertificateTrustSubject | None

Finds the CertificateTrustSubject belonging to the provided signify.x509.Certificate or signed_file.AuthenticodeFile.

Parameters:: subject – The certificate or file to look for.

classmethod from_stl_file(path: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/signify/envs/v0.9.1/lib/python3.13/site-packages/mscerts/authroot.stl')) → Self: Loads a CertificateTrustList from a specified path.

iter_recursive_nested() → Iterator[CertificateTrustList]: Returns an iterator over the current object. Included for compatibility with AuthenticodeSignature.

property list_identifier: bytes | None: The name of the template of the list.

property next_update: datetime | None: The date of the next CTL.

property sequence_number: int: The unique number of this list

property subject_algorithm: HashFunction: Digest algorithm of identifying subjects in the list.

property subject_usage: list[str]: Defines the EKU of the Certificate Trust List.

property subjects: Iterable[CertificateTrustSubject]: A list of CertificateTrustSubject s in this list.

property this_update: datetime | None: The date of the current CTL.

verify(*args: Any, **kwargs: Any) → Iterable[list[Certificate]]: Override to make sure that the TRUSTED_CERTIFICATE_STORE is set properly and that the proper exceptions are raised.

verify_trust(chain: list[Certificate], *args: Any, **kwargs: Any) → bool

Checks whether the specified certificate is valid in the given conditions according to this Certificate Trust List.

Parameters:: chain – The certificate chain to verify

class signify.authenticode.CertificateTrustSubject(asn1: TrustedSubject, parent: CertificateTrustList)

A subject listed in a CertificateTrustList. The structure in this object has mostly been reverse-engineered using Windows tooling such as certutil -dump. We do not pretend to have a complete picture of all the edge-cases that are considered.

Warning

The interpretation of the various attributes and their implications has been reverse-engineered. Though we seem to have a fairly solid understanding, various edge-cases may not have been considered.

__init__(asn1: TrustedSubject, parent: CertificateTrustList)

property attributes: dict[str, Any]: A dictionary mapping of attribute types to singular native values.

property attributes_asn1: dict[str, Any]: A dictionary mapping of attribute types to ASN.1 values.

property auth_root_sha256: bytes

The sha256 fingerprint of the certificate.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property catalog_memberinfo: dict[str, str | int] | None

Return information about the CAT entry.

Typically available for catalog files (i.e. not CTLs).

property catalog_namevalue: dict[str, str | int] | None

Return information about the CAT entry.

Typically available for catalog files (i.e. not CTLs).

property disallowed_extended_key_usages: list[str] | None

Defines the EKU’s the certificate is not valid for. When used in combination with disallowed_filetime, the disabled EKU’s are only disabled from that date onwards, otherwise, it means since the beginning of time.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property disallowed_filetime: datetime | None

The time since when a certificate has been disabled. Digital signatures with a timestamp prior to this date continue to be valid, but use cases after this date are prohibited. It may be used in conjunction with disallowed_extended_key_usages to define specific EKU’s to be disabled.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property extended_key_usages: list[str] | None

Defines the EKU’s the certificate is valid for. It may be empty, which we take as ‘all is acceptable’.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property friendly_name: str | None

The friendly name of the certificate.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property identifier_str: str: Return identifier as a string. This is usually the hex encoding of the byte string, but in the case of microsoft_catalog_list, this can be a UTF-16 encoded string if indirect_data is present.

property indirect_data: IndirectData | None

Return the indirect data for this subject.

Typically available for catalog files (i.e. not CTLs).

property key_identifier: bytes

The sha1 fingerprint of the certificate.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property not_before_extended_key_usages: list[str] | None

Defines the EKU’s for which the not_before_filetime is considered. If that attribute is not defined, we assume that it means since the beginning of time.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property not_before_filetime: datetime | None

The time since when new certificates from this CA are not trusted. Certificates from prior the date will continue to validate. When used in conjunction with not_before_extended_key_usages, this only concerns certificates issued after this date for the defined EKU’s.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property root_program_cert_policies: list[dict[str, Any]] | None

The policies applicable to the root certificate.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property root_program_chain_policies: list[str] | None

A list of EKU’s probably used for EV certificates.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

property subject_name_md5: bytes

The md5 of the subject name.

Typically available for Certificate Trust Lists (i.e. non-catalog files).

verify_trust(chain: list[Certificate], context: VerificationContext) → bool

Checks whether the specified certificate is valid in the given conditions according to this Certificate Trust List.

Parameters:

chain – The certificate chain to verify.
context – The context to verify with. Mainly the VerificationContext.timestamp and VerificationContext.extended_key_usages are used.