Skip to content

Models

Common models shared between signing and verification.

TransparencyLogEntry(inner)

Represents a transparency log entry.

Creates a new TransparencyLogEntry from the given inner object.

@private

Source code in sigstore/models.py
83
84
85
86
87
88
89
90
def __init__(self, inner: _TransparencyLogEntry) -> None:
    """
    Creates a new `TransparencyLogEntry` from the given inner object.

    @private
    """
    self._inner = inner
    self._validate()

TimestampVerificationData(inner)

Represents a TimestampVerificationData structure.

@private

Init method.

Source code in sigstore/models.py
249
250
251
252
def __init__(self, inner: _TimestampVerificationData) -> None:
    """Init method."""
    self._inner = inner
    self._verify()

rfc3161_timestamps property

Returns a list of signed timestamp.

from_json(raw) classmethod

Deserialize the given timestamp verification data.

Source code in sigstore/models.py
276
277
278
279
280
281
282
@classmethod
def from_json(cls, raw: str | bytes) -> TimestampVerificationData:
    """
    Deserialize the given timestamp verification data.
    """
    inner = _TimestampVerificationData.from_json(raw)
    return cls(inner)

VerificationMaterial(inner)

Represents a VerificationMaterial structure.

Init method.

Source code in sigstore/models.py
290
291
292
def __init__(self, inner: _VerificationMaterial) -> None:
    """Init method."""
    self._inner = inner

timestamp_verification_data property

Returns the Timestamp Verification Data, if present.

InvalidBundle

Bases: Error

Raised when the associated Bundle is invalid in some way.

diagnostics()

Returns diagnostics for the error.

Source code in sigstore/models.py
312
313
314
315
316
317
318
319
320
321
322
323
324
325
def diagnostics(self) -> str:
    """Returns diagnostics for the error."""

    return dedent(
        f"""\
    An issue occurred while parsing the Sigstore bundle.

    The provided bundle is malformed and may have been modified maliciously.

    Additional context:

    {self}
    """
    )

Bundle(inner)

Represents a Sigstore bundle.

Creates a new bundle. This is not a public API; use from_json instead.

@private

Source code in sigstore/models.py
347
348
349
350
351
352
353
354
355
def __init__(self, inner: _Bundle) -> None:
    """
    Creates a new bundle. This is not a public API; use
    `from_json` instead.

    @private
    """
    self._inner = inner
    self._verify()

signing_certificate property

Returns the bundle's contained signing (i.e. leaf) certificate.

log_entry property

Returns the bundle's log entry, containing an inclusion proof (with checkpoint) and an inclusion promise (if the latter is present).

signature property

Returns the signature bytes of this bundle. Either from the DSSE Envelope or from the message itself.

verification_material property

Returns the bundle's verification material.

BundleType

Bases: str, Enum

Known Sigstore bundle media types.

from_json(raw) classmethod

Deserialize the given Sigstore bundle.

Source code in sigstore/models.py
515
516
517
518
519
520
521
522
523
524
@classmethod
def from_json(cls, raw: bytes | str) -> Bundle:
    """
    Deserialize the given Sigstore bundle.
    """
    try:
        inner = _Bundle.from_json(raw)
    except ValueError as exc:
        raise InvalidBundle(f"failed to load bundle: {exc}")
    return cls(inner)

to_json()

Return a JSON encoding of this bundle.

Source code in sigstore/models.py
526
527
528
529
530
def to_json(self) -> str:
    """
    Return a JSON encoding of this bundle.
    """
    return self._inner.to_json()

from_parts(cert, sig, log_entry) classmethod

Construct a Sigstore bundle (of hashedrekord type) from its constituent parts.

Source code in sigstore/models.py
549
550
551
552
553
554
555
556
557
558
559
560
@classmethod
def from_parts(
    cls, cert: Certificate, sig: bytes, log_entry: TransparencyLogEntry
) -> Bundle:
    """
    Construct a Sigstore bundle (of `hashedrekord` type) from its
    constituent parts.
    """

    return cls._from_parts(
        cert, MessageSignature(signature=base64.b64encode(sig)), log_entry
    )

SigningConfig(inner, tlog_version=None)

Signing configuration for a Sigstore instance.

Construct a new SigningConfig.

tlog_version is an optional argument that enforces that only specified versions of rekor are included in the transparency logs.

@api private

Source code in sigstore/models.py
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
def __init__(
    self, inner: trustroot_v1.SigningConfig, tlog_version: int | None = None
):
    """
    Construct a new `SigningConfig`.

    tlog_version is an optional argument that enforces that only specified
    versions of rekor are included in the transparency logs.

    @api private
    """
    self._inner = inner

    # must have a recognized media type.
    try:
        SigningConfig.SigningConfigType(self._inner.media_type)
    except ValueError:
        raise Error(f"unsupported signing config format: {self._inner.media_type}")

    # Create lists of service protos that are valid, selected by the service
    # configuration & supported by this client
    if tlog_version is None:
        tlog_versions = REKOR_VERSIONS
    else:
        tlog_versions = [tlog_version]

    self._tlogs = self._get_valid_services(
        self._inner.rekor_tlog_urls, tlog_versions, self._inner.rekor_tlog_config
    )
    if not self._tlogs:
        raise Error("No valid Rekor transparency log found in signing config")

    self._tsas = self._get_valid_services(
        self._inner.tsa_urls, TSA_VERSIONS, self._inner.tsa_config
    )

    self._fulcios = self._get_valid_services(
        self._inner.ca_urls, FULCIO_VERSIONS, None
    )
    if not self._fulcios:
        raise Error("No valid Fulcio CA found in signing config")

    self._oidcs = self._get_valid_services(
        self._inner.oidc_urls, OIDC_VERSIONS, None
    )

SigningConfigType

Bases: str, Enum

Known Sigstore signing config media types.

from_file(path) classmethod

Create a new signing config from file

Source code in sigstore/models.py
673
674
675
676
677
678
679
680
@classmethod
def from_file(
    cls,
    path: str,
) -> SigningConfig:
    """Create a new signing config from file"""
    inner = trustroot_v1.SigningConfig.from_json(Path(path).read_bytes())
    return cls(inner)

get_tlogs()

Returns the rekor transparency log clients to sign with.

Source code in sigstore/models.py
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
def get_tlogs(self) -> list[RekorLogSubmitter]:
    """
    Returns the rekor transparency log clients to sign with.
    """
    result: list[RekorLogSubmitter] = []
    for tlog in self._tlogs:
        if tlog.major_api_version == 1:
            from sigstore._internal.rekor.client import RekorClient

            result.append(RekorClient(tlog.url))
        elif tlog.major_api_version == 2:
            from sigstore._internal.rekor.client_v2 import RekorV2Client

            result.append(RekorV2Client(tlog.url))
        else:
            raise AssertionError(f"Unexpected Rekor v{tlog.major_api_version}")
    return result

get_fulcio()

Returns a Fulcio client to get a signing certificate from

Source code in sigstore/models.py
747
748
749
750
751
def get_fulcio(self) -> FulcioClient:
    """
    Returns a Fulcio client to get a signing certificate from
    """
    return FulcioClient(self._fulcios[0].url)

get_oidc_url()

Returns url for the OIDC provider that client should use to interactively authenticate.

Source code in sigstore/models.py
753
754
755
756
757
758
759
760
def get_oidc_url(self) -> str:
    """
    Returns url for the OIDC provider that client should use to interactively
    authenticate.
    """
    if not self._oidcs:
        raise Error("No valid OIDC provider found in signing config")
    return self._oidcs[0].url

get_tsas()

Returns timestamp authority clients for urls configured in signing config.

Source code in sigstore/models.py
762
763
764
765
766
def get_tsas(self) -> list[TimestampAuthorityClient]:
    """
    Returns timestamp authority clients for urls configured in signing config.
    """
    return [TimestampAuthorityClient(s.url) for s in self._tsas]

TrustedRoot(inner)

The cryptographic root(s) of trust for a Sigstore instance.

Construct a new TrustedRoot.

@api private

Source code in sigstore/models.py
785
786
787
788
789
790
791
792
def __init__(self, inner: trustroot_v1.TrustedRoot):
    """
    Construct a new `TrustedRoot`.

    @api private
    """
    self._inner = inner
    self._verify()

TrustedRootType

Bases: str, Enum

Known Sigstore trusted root media types.

from_file(path) classmethod

Create a new trust root from file

Source code in sigstore/models.py
806
807
808
809
810
811
812
813
@classmethod
def from_file(
    cls,
    path: str,
) -> TrustedRoot:
    """Create a new trust root from file"""
    inner = trustroot_v1.TrustedRoot.from_json(Path(path).read_bytes())
    return cls(inner)

rekor_keyring(purpose)

Return keyring with keys for Rekor.

Source code in sigstore/models.py
831
832
833
834
835
836
837
838
839
def rekor_keyring(self, purpose: KeyringPurpose) -> RekorKeyring:
    """Return keyring with keys for Rekor."""

    keys: list[common_v1.PublicKey] = list(
        self._get_tlog_keys(self._inner.tlogs, purpose)
    )
    if len(keys) == 0:
        raise MetadataError("Did not find any Rekor keys in trusted root")
    return RekorKeyring(Keyring(keys))

ct_keyring(purpose)

Return keyring with key for CTFE.

Source code in sigstore/models.py
841
842
843
844
845
846
847
848
def ct_keyring(self, purpose: KeyringPurpose) -> CTKeyring:
    """Return keyring with key for CTFE."""
    ctfes: list[common_v1.PublicKey] = list(
        self._get_tlog_keys(self._inner.ctlogs, purpose)
    )
    if not ctfes:
        raise MetadataError("CTFE keys not found in trusted root")
    return CTKeyring(Keyring(ctfes))

get_fulcio_certs()

Return the Fulcio certificates.

Source code in sigstore/models.py
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def get_fulcio_certs(self) -> list[Certificate]:
    """Return the Fulcio certificates."""

    certs: list[Certificate] = []

    # Return expired certificates too: they are expired now but may have
    # been active when the certificate was used to sign.
    for authority in self._inner.certificate_authorities:
        certificate_authority = CertificateAuthority(authority)
        certs.extend(certificate_authority.certificates(allow_expired=True))

    if not certs:
        raise MetadataError("Fulcio certificates not found in trusted root")
    return certs

get_timestamp_authorities()

Return the TSA present in the trusted root.

This list may be empty and in this case, no timestamp verification can be performed.

Source code in sigstore/models.py
865
866
867
868
869
870
871
872
873
874
875
876
def get_timestamp_authorities(self) -> list[CertificateAuthority]:
    """
    Return the TSA present in the trusted root.

    This list may be empty and in this case, no timestamp verification can be
    performed.
    """
    certificate_authorities: list[CertificateAuthority] = [
        CertificateAuthority(cert_chain)
        for cert_chain in self._inner.timestamp_authorities
    ]
    return certificate_authorities

ClientTrustConfig(inner)

Represents a Sigstore client's trust configuration, including a root of trust.

@api private

Source code in sigstore/models.py
957
958
959
960
961
962
963
964
def __init__(self, inner: trustroot_v1.ClientTrustConfig) -> None:
    """
    @api private
    """
    self._inner = inner

    # This can be used to enforce a specific rekor major version in signingconfig
    self.force_tlog_version: int | None = None

trusted_root property

Return the interior root of trust, as a TrustedRoot.

signing_config property

Return the interior root of trust, as a SigningConfig.

ClientTrustConfigType

Bases: str, Enum

Known Sigstore client trust config media types.

from_json(raw) classmethod

Deserialize the given client trust config.

Source code in sigstore/models.py
895
896
897
898
899
900
901
@classmethod
def from_json(cls, raw: str) -> ClientTrustConfig:
    """
    Deserialize the given client trust config.
    """
    inner = trustroot_v1.ClientTrustConfig.from_json(raw)
    return cls(inner)

production(offline=False) classmethod

Create new trust config from Sigstore production TUF repository.

If offline, will use data in local TUF cache. Otherwise will update the data from remote TUF repository.

Source code in sigstore/models.py
903
904
905
906
907
908
909
910
911
912
913
@classmethod
def production(
    cls,
    offline: bool = False,
) -> ClientTrustConfig:
    """Create new trust config from Sigstore production TUF repository.

    If `offline`, will use data in local TUF cache. Otherwise will
    update the data from remote TUF repository.
    """
    return cls.from_tuf(DEFAULT_TUF_URL, offline)

staging(offline=False) classmethod

Create new trust config from Sigstore staging TUF repository.

If offline, will use data in local TUF cache. Otherwise will update the data from remote TUF repository.

Source code in sigstore/models.py
915
916
917
918
919
920
921
922
923
924
925
@classmethod
def staging(
    cls,
    offline: bool = False,
) -> ClientTrustConfig:
    """Create new trust config from Sigstore staging TUF repository.

    If `offline`, will use data in local TUF cache. Otherwise will
    update the data from remote TUF repository.
    """
    return cls.from_tuf(STAGING_TUF_URL, offline)

from_tuf(url, offline=False) classmethod

Create a new trust config from a TUF repository.

If offline, will use data in local TUF cache. Otherwise will update the trust config from remote TUF repository.

Source code in sigstore/models.py
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
@classmethod
def from_tuf(
    cls,
    url: str,
    offline: bool = False,
) -> ClientTrustConfig:
    """Create a new trust config from a TUF repository.

    If `offline`, will use data in local TUF cache. Otherwise will
    update the trust config from remote TUF repository.
    """
    updater = TrustUpdater(url, offline)

    tr_path = updater.get_trusted_root_path()
    inner_tr = trustroot_v1.TrustedRoot.from_json(Path(tr_path).read_bytes())

    try:
        sc_path = updater.get_signing_config_path()
        inner_sc = trustroot_v1.SigningConfig.from_json(Path(sc_path).read_bytes())
    except TUFError as e:
        raise e

    return cls(
        trustroot_v1.ClientTrustConfig(
            media_type=ClientTrustConfig.ClientTrustConfigType.CONFIG_0_1.value,
            trusted_root=inner_tr,
            signing_config=inner_sc,
        )
    )