Certificate Trust Lists (authroot.stl)

Microsoft has its own root CA verification program. More information about this root program can be found on Microsoft’s website.

Trust of certificates is distributed to Windows computers using Certificate Trust Lists. They used to be updated through Windows Update, though they are now updated independently. Certificate Trust Lists are not very well documented, but a 2009 whitepaper does a decent job of defining the used structures.

For interpreting the various attributes, we had to do some more extended research. The following lists the deprecation policies in place and how we have found that they are mapped to attributes in the CTL.

CTL deprecation policies

Removal: Removal of a root from the CTL. All certificates that chain to the root are no longer trusted.

In this case, the entry will be removed from the CTL; we do not need to perform further checks.
EKU Removal: Removal of a specific EKU from a root certificate. All End entity certificates that chain to this root can no longer utilize the removed EKU, independent of whether or not the digital signature was timestamped.

The EKU 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: This feature involves adding the certificate to the Disallow CTL. This feature effectively revokes the certificate. Users cannot manually install the root and continue to have trust.

Disallowed certificates are put in a separate authroot.stl file, and removed from the normal CTL. We do not verify disallowed certificates.
Disable: All certificates that chain to a disabled root will no longer be trusted with a very important exception; digital signatures with a timestamp prior to the disable date will continue to validate successfully.

Empirical evidence has shown that in this case, CertificateTrustSubject.disallowed_filetime will be set. In the case that only an 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: Allows granular disabling of a root certificate or specific EKU capability of a root certificate. Certificates issued AFTER the NotBefore date will no longer be trusted, however certificates issued BEFORE to the NotBefore date will continue to be trusted. Digital signatures with a timestamp set before the NotBefore date will continue to successfully validate.

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.

class signify.authenticode.CertificateTrustList(data: SignedData | 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

data: The underlying ASN.1 data object

subject_usage: Defines the EKU of the Certificate Trust List. Should be 1.3.6.1.4.1.311.20.1.

list_identifier: The name of the template of the list.

sequence_number: The unique number of this list

this_update: The date of the current CTL.

next_update: The date of the next CTL.

subject_algorithm: Digest algorithm of verifying the list.

Warning

The CTL itself is currently not verifiable.

Parameters:: data – The ASN.1 structure of the SignedData object

find_subject(certificate: Certificate) → CertificateTrustSubject | None

Finds the CertificateTrustSubject belonging to the provided signify.x509.Certificate.

Parameters:: certificate (signify.x509.Certificate) – The certificate to look for.
Return type:: CertificateTrustSubject

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

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

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 (List[Certificate]) – The certificate chain to verify

class signify.authenticode.CertificateTrustSubject(data: TrustedSubject)

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.

data: The underlying ASN.1 data object

attributes: A dictionary mapping of attribute types to values.

The following values are extracted from the attributes:

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

friendly_name: The friendly name of the certificate.

key_identifier: The sha1 fingerprint of the certificate.

subject_name_md5: The md5 of the subject name.

auth_root_sha256: The sha256 fingerprint of the certificate.

disallowed_filetime: 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.

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

disallowed_extended_key_usages: 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.

not_before_filetime: 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.

not_before_extended_key_usages: 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.

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.

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 (List[Certificate]) – The certificate chain to verify.
context (VerificationContext) – The context to verify with. Mainly the timestamp and extended_key_usages are used.

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.

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