Sign

API for signing artifacts.

Example:

from pathlib import Path

from sigstore.sign import SigningContext
from sigstore.oidc import Issuer

issuer = Issuer.production()
identity = issuer.identity_token()

# The artifact to sign
artifact = Path("foo.txt").read_bytes()

signing_ctx = SigningContext.production()
with signing_ctx.signer(identity, cache=True) as signer:
    result = signer.sign_artifact(artifact)
    print(result)

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: Optional[ec.EllipticCurvePrivateKey] = None
    self.__cached_signing_certificate: Optional[x509.Certificate] = 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()

    # Prepare inputs
    b64_cert = base64.b64encode(
        cert.public_bytes(encoding=serialization.Encoding.PEM)
    )

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

    # Create the proposed DSSE log entry
    proposed_entry = rekor_types.Dsse(
        spec=rekor_types.dsse.DsseSchema(
            # NOTE: mypy can't see that this kwarg is correct due to two interacting
            # behaviors/bugs (one pydantic, one datamodel-codegen):
            # See: <https://github.com/pydantic/pydantic/discussions/7418#discussioncomment-9024927>
            # See: <https://github.com/koxudaxi/datamodel-code-generator/issues/1903>
            proposed_content=rekor_types.dsse.ProposedContent(  # type: ignore[call-arg]
                envelope=content.to_json(),
                verifiers=[b64_cert.decode()],
            ),
        ),
    )

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

    # Prepare inputs
    b64_cert = base64.b64encode(
        cert.public_bytes(encoding=serialization.Encoding.PEM)
    )

    # 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=hashed_input.digest,
        ),
        signature=artifact_signature,
    )

    # Create the proposed hashedrekord entry
    proposed_entry = rekor_types.Hashedrekord(
        spec=rekor_types.hashedrekord.HashedrekordV001Schema(
            signature=rekor_types.hashedrekord.Signature(
                content=base64.b64encode(artifact_signature).decode(),
                public_key=rekor_types.hashedrekord.PublicKey(
                    content=b64_cert.decode()
                ),
            ),
            data=rekor_types.hashedrekord.Data(
                hash=rekor_types.hashedrekord.Hash(
                    algorithm=hashed_input._as_hashedrekord_algorithm(),
                    value=hashed_input.digest.hex(),
                )
            ),
        ),
    )

    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: RekorClient,
    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 []

production() classmethod

Return a SigningContext instance configured against Sigstore's production-level services.

Source code in sigstore/sign.py

@classmethod
def production(cls) -> SigningContext:
    """
    Return a `SigningContext` instance configured against Sigstore's production-level services.
    """
    return cls(
        fulcio=FulcioClient.production(),
        rekor=RekorClient.production(),
        trusted_root=TrustedRoot.production(),
    )

staging() classmethod

Return a SignerContext instance configured against Sigstore's staging-level services.

Source code in sigstore/sign.py

@classmethod
def staging(cls) -> SigningContext:
    """
    Return a `SignerContext` instance configured against Sigstore's staging-level services.
    """
    return cls(
        fulcio=FulcioClient.staging(),
        rekor=RekorClient.staging(),
        trusted_root=TrustedRoot.staging(),
    )

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)