Sign

API for signing artifacts.

Example:

from pathlib import Path
from sigstore.models import ClientTrustConfig
from sigstore.oidc import Issuer
from sigstore.sign import SigningContext

artifact_path = Path("README.md")

# Construct OIDC Issuer and SigningContext for the
# Sigstore Public Good instance
trust_config = ClientTrustConfig.production()
issuer = Issuer(trust_config.signing_config.get_oidc_url())
context = SigningContext.from_trust_config(trust_config)

# Get an identity token from OIDC provider using interactive auth
token = issuer.identity_token()

# Sign artifact with the identity
with context.signer(token, cache = True) as signer:
    bundle = signer.sign_artifact(artifact_path.read_bytes())

with Path("README.md.sigstore.json").open("w") as f:
    f.write(bundle.to_json())

Signer(identity_token, signing_ctx, cache=True)

The primary API for signing operations.

Create a new Signer.

identity_token is the identity token used to request a signing certificate from Fulcio.

signing_ctx is a SigningContext that keeps information about the signing configuration.

cache determines whether the signing certificate and ephemeral private key should be reused (until the certificate expires) to sign different artifacts. Default is True.

Source code in sigstore/sign.py

def __init__(
    self,
    identity_token: IdentityToken,
    signing_ctx: SigningContext,
    cache: bool = True,
) -> None:
    """
    Create a new `Signer`.

    `identity_token` is the identity token used to request a signing certificate
    from Fulcio.

    `signing_ctx` is a `SigningContext` that keeps information about the signing
    configuration.

    `cache` determines whether the signing certificate and ephemeral private key
    should be reused (until the certificate expires) to sign different artifacts.
    Default is `True`.
    """
    self._identity_token = identity_token
    self._signing_ctx: SigningContext = signing_ctx
    self.__cached_private_key: ec.EllipticCurvePrivateKey | None = None
    self.__cached_signing_certificate: x509.Certificate | None = None
    if cache:
        _logger.debug("Generating ephemeral keys...")
        self.__cached_private_key = ec.generate_private_key(ec.SECP256R1())
        _logger.debug("Requesting ephemeral certificate...")
        self.__cached_signing_certificate = self._signing_cert()

sign_dsse(input_)

Sign the given in-toto statement as a DSSE envelope, and return a Bundle containing the signed result.

This API is only for in-toto statements; to sign arbitrary artifacts, use sign_artifact instead.

Source code in sigstore/sign.py

def sign_dsse(
    self,
    input_: dsse.Statement,
) -> Bundle:
    """
    Sign the given in-toto statement as a DSSE envelope, and return a
    `Bundle` containing the signed result.

    This API is **only** for in-toto statements; to sign arbitrary artifacts,
    use `sign_artifact` instead.
    """
    cert = self._signing_cert()

    # Sign the statement, producing a DSSE envelope
    content = dsse._sign(self._private_key, input_)

    # Create the proposed DSSE log entry
    proposed_entry = self._signing_ctx._rekor._build_dsse_request(
        envelope=content, certificate=cert
    )

    return self._finalize_sign(cert, content, proposed_entry)

sign_artifact(input_)

Sign an artifact, and return a Bundle corresponding to the signed result.

The input can be one of two forms:

1. A bytes buffer;
2. A Hashed object, containing a pre-hashed input (e.g., for inputs that are too large to buffer into memory).

Regardless of the input format, the signing operation will produce a hashedrekord entry within the bundle. No other entry types are supported by this API.

Source code in sigstore/sign.py

def sign_artifact(
    self,
    input_: bytes | sigstore_hashes.Hashed,
) -> Bundle:
    """
    Sign an artifact, and return a `Bundle` corresponding to the signed result.

    The input can be one of two forms:

    1. A `bytes` buffer;
    2. A `Hashed` object, containing a pre-hashed input (e.g., for inputs
       that are too large to buffer into memory).

    Regardless of the input format, the signing operation will produce a
    `hashedrekord` entry within the bundle. No other entry types
    are supported by this API.
    """

    cert = self._signing_cert()

    # Sign artifact
    hashed_input = sha256_digest(input_)

    artifact_signature = self._private_key.sign(
        hashed_input.digest, ec.ECDSA(hashed_input._as_prehashed())
    )

    content = MessageSignature(
        message_digest=HashOutput(
            algorithm=hashed_input.algorithm,
            digest=base64.b64encode(hashed_input.digest),
        ),
        signature=base64.b64encode(artifact_signature),
    )

    # Create the proposed hashedrekord entry
    proposed_entry = self._signing_ctx._rekor._build_hashed_rekord_request(
        hashed_input=hashed_input, signature=artifact_signature, certificate=cert
    )

    return self._finalize_sign(cert, content, proposed_entry)

SigningContext(*, fulcio, rekor, trusted_root, tsa_clients=None)

Keep a context between signing operations.

Create a new SigningContext.

fulcio is a FulcioClient capable of connecting to a Fulcio instance and returning signing certificates.

rekor is a RekorClient capable of connecting to a Rekor instance and creating transparency log entries.

Source code in sigstore/sign.py

def __init__(
    self,
    *,
    fulcio: FulcioClient,
    rekor: RekorLogSubmitter,
    trusted_root: TrustedRoot,
    tsa_clients: list[TimestampAuthorityClient] | None = None,
):
    """
    Create a new `SigningContext`.

    `fulcio` is a `FulcioClient` capable of connecting to a Fulcio instance
    and returning signing certificates.

    `rekor` is a `RekorClient` capable of connecting to a Rekor instance
    and creating transparency log entries.
    """
    self._fulcio = fulcio
    self._rekor = rekor
    self._trusted_root = trusted_root
    self._tsa_clients = tsa_clients or []

from_trust_config(trust_config) classmethod

Create a SigningContext from the given ClientTrustConfig.

@api private

Source code in sigstore/sign.py

@classmethod
def from_trust_config(cls, trust_config: ClientTrustConfig) -> SigningContext:
    """
    Create a `SigningContext` from the given `ClientTrustConfig`.

    @api private
    """
    signing_config = trust_config.signing_config
    return cls(
        fulcio=signing_config.get_fulcio(),
        rekor=signing_config.get_tlogs()[0],
        trusted_root=trust_config.trusted_root,
        tsa_clients=signing_config.get_tsas(),
    )

signer(identity_token, *, cache=True)

A context manager for signing operations.

identity_token is the identity token passed to the Signer instance and used to request a signing certificate from Fulcio.

cache determines whether the signing certificate and ephemeral private key generated by the Signer instance should be reused (until the certificate expires) to sign different artifacts. Default is True.

Source code in sigstore/sign.py

@contextmanager
def signer(
    self, identity_token: IdentityToken, *, cache: bool = True
) -> Iterator[Signer]:
    """
    A context manager for signing operations.

    `identity_token` is the identity token passed to the `Signer` instance
    and used to request a signing certificate from Fulcio.

    `cache` determines whether the signing certificate and ephemeral private key
    generated by the `Signer` instance should be reused (until the certificate expires)
    to sign different artifacts.
    Default is `True`.
    """
    yield Signer(identity_token, self, cache)