Models

Common models shared between signing and verification.

LogInclusionProof

Bases: BaseModel

Represents an inclusion proof for a transparency log entry.

LogEntry

Represents a transparency log entry.

Log entries are retrieved from the transparency log after signing or verification events, or loaded from "Sigstore" bundles provided by the user.

This representation allows for either a missing inclusion promise or a missing inclusion proof, but not both: attempting to construct a LogEntry without at least one will fail.

uuid instance-attribute

This entry's unique ID in the log instance it was retrieved from.

For sharded log deployments, IDs are unique per-shard.

Not present for LogEntry instances loaded from Sigstore bundles.

body instance-attribute

The base64-encoded body of the transparency log entry.

integrated_time instance-attribute

The UNIX time at which this entry was integrated into the transparency log.

log_id instance-attribute

The log's ID (as the SHA256 hash of the DER-encoded public key for the log at the time of entry inclusion).

log_index instance-attribute

The index of this entry within the log.

inclusion_proof instance-attribute

An inclusion proof for this log entry.

inclusion_promise instance-attribute

An inclusion promise for this log entry, if present.

Internally, this is a base64-encoded Signed Entry Timestamp (SET) for this log entry.

encode_canonical()

Returns a canonicalized JSON (RFC 8785) representation of the transparency log entry.

This encoded representation is suitable for verification against the Signed Entry Timestamp.

Source code in sigstore/models.py

def encode_canonical(self) -> bytes:
    """
    Returns a canonicalized JSON (RFC 8785) representation of the transparency log entry.

    This encoded representation is suitable for verification against
    the Signed Entry Timestamp.
    """
    payload: dict[str, int | str] = {
        "body": self.body,
        "integratedTime": self.integrated_time,
        "logID": self.log_id,
        "logIndex": self.log_index,
    }

    return rfc8785.dumps(payload)

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.

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

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.
    """
    inner = _Bundle.from_dict(json.loads(raw))
    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: LogEntry) -> Bundle:
    """
    Construct a Sigstore bundle (of `hashedrekord` type) from its
    constituent parts.
    """

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