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

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

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

@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

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

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}
    """
    )

IncompatibleEntry

Bases: InvalidBundle

Raised when the log entry within the Bundle has an incompatible KindVersion.

diagnostics()

Returns diagnostics for the error.

Source code in sigstore/models.py

def diagnostics(self) -> str:
    """Returns diagnostics for the error."""

    return dedent(
        f"""\
    The provided bundle contains a transparency log entry that is incompatible with this version of sigstore-python. Please upgrade your verifying client.

    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

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

@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

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

@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

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

@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

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

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

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

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

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

@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

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

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

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

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

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

@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

@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

@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, bootstrap_root=None) 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

@classmethod
def from_tuf(
    cls,
    url: str,
    offline: bool = False,
    bootstrap_root: Path | None = None,
) -> 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, bootstrap_root)

    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,
        )
    )