Edit on GitHub

model_signing.signing

High level API for the signing interface of model_signing library.

The module allows signing a model with a default configuration:

model_signing.signing.sign("finbert", "finbert.sig")

The module allows customizing the signing configuration before signing:

model_signing.signing.Config().use_elliptic_key_signer(private_key="key").sign(
    "finbert", "finbert.sig"
)

The same signing configuration can be used to sign multiple models:

signing_config = model_signing.signing.Config().use_elliptic_key_signer(
    private_key="key"
)

for model in all_models:
    signing_config.sign(model, f"{model}_sharded.sig")

The API defined here is stable and backwards compatible.

  1# Copyright 2024 The Sigstore Authors
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7#      http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15"""High level API for the signing interface of `model_signing` library.
 16
 17The module allows signing a model with a default configuration:
 18
 19```python
 20model_signing.signing.sign("finbert", "finbert.sig")
 21```
 22
 23The module allows customizing the signing configuration before signing:
 24
 25```python
 26model_signing.signing.Config().use_elliptic_key_signer(private_key="key").sign(
 27    "finbert", "finbert.sig"
 28)
 29```
 30
 31The same signing configuration can be used to sign multiple models:
 32
 33```python
 34signing_config = model_signing.signing.Config().use_elliptic_key_signer(
 35    private_key="key"
 36)
 37
 38for model in all_models:
 39    signing_config.sign(model, f"{model}_sharded.sig")
 40```
 41
 42The API defined here is stable and backwards compatible.
 43"""
 44
 45from collections.abc import Iterable
 46import pathlib
 47from typing import Self
 48
 49from model_signing import hashing
 50from model_signing._signing import sign_certificate as certificate
 51from model_signing._signing import sign_ec_key as ec_key
 52from model_signing._signing import sign_sigstore as sigstore
 53from model_signing._signing import signing
 54
 55
 56def sign(model_path: hashing.PathLike, signature_path: hashing.PathLike):
 57    """Signs a model using the default configuration.
 58
 59    In this default configuration we sign using Sigstore and the default hashing
 60    configuration from `model_signing.hashing`.
 61
 62    The resulting signature is in the Sigstore bundle format.
 63
 64    Args:
 65        model_path: the path to the model to sign.
 66        signature_path: the path of the resulting signature.
 67    """
 68    Config().sign(model_path, signature_path)
 69
 70
 71def sign_to_bytes(model_path: hashing.PathLike) -> bytes:
 72    """Signs a model using the default configuration and returns the signature.
 73
 74    In this default configuration we sign using Sigstore and the default hashing
 75    configuration from `model_signing.hashing`.
 76
 77    The resulting signature is the Sigstore bundle, returned in memory as UTF-8
 78    encoded JSON bytes instead of being written to disk.
 79
 80    Args:
 81        model_path: the path to the model to sign.
 82
 83    Returns:
 84        The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.
 85    """
 86    return Config().sign_to_bytes(model_path)
 87
 88
 89class Config:
 90    """Configuration to use when signing models.
 91
 92    Currently, we support signing with Sigstore (both the public
 93    instance and staging instance), signing with private keys,
 94    signing with signing certificates, and signing with custom
 95    PKI configurations using the `--trust_config` option.
 96    This allows users to bring their own trust configuration
 97    to sign and verify models. Other signing modes may be
 98    added in the future.
 99    """
100
101    def __init__(self):
102        """Initializes the default configuration for signing."""
103        self._hashing_config = hashing.Config()
104        # lazy initialize default signer at signing to avoid network calls
105        self._signer = None
106
107    def sign(
108        self, model_path: hashing.PathLike, signature_path: hashing.PathLike
109    ):
110        """Signs a model using the current configuration.
111
112        Args:
113            model_path: The path to the model to sign.
114            signature_path: The path of the resulting signature.
115        """
116        signature = self._sign(model_path)
117        signature.write(pathlib.Path(signature_path))
118
119    def sign_to_bytes(self, model_path: hashing.PathLike) -> bytes:
120        """Signs a model and returns the signature as bytes.
121
122        This mirrors `sign`, but instead of writing the signature to disk it
123        returns the Sigstore bundle in memory. This is useful in serverless or
124        pipeline contexts where writing to the filesystem is undesirable or
125        impossible, and the bundle needs to be streamed, persisted to an object
126        store, or passed directly to another process.
127
128        The returned bytes are the UTF-8 encoded Sigstore bundle, identical to
129        what `sign` would have written to the signature path.
130
131        Args:
132            model_path: The path to the model to sign.
133
134        Returns:
135            The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.
136        """
137        return self._sign(model_path).to_bytes()
138
139    def _sign(self, model_path: hashing.PathLike) -> signing.Signature:
140        """Hashes and signs a model, returning the in-memory signature.
141
142        Args:
143            model_path: The path to the model to sign.
144
145        Returns:
146            The `Signature` produced by the configured signer.
147        """
148        if self._signer is None:
149            self.use_sigstore_signer()
150        manifest = self._hashing_config.hash(model_path)
151        payload = signing.Payload(manifest)
152        return self._signer.sign(payload)
153
154    def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
155        """Sets the new configuration for hashing models.
156
157        Args:
158            hashing_config: The new hashing configuration.
159
160        Returns:
161            The new signing configuration.
162        """
163        self._hashing_config = hashing_config
164        return self
165
166    def use_sigstore_signer(
167        self,
168        *,
169        oidc_issuer: str | None = None,
170        use_ambient_credentials: bool = False,
171        use_staging: bool = False,
172        force_oob: bool = False,
173        identity_token: str | None = None,
174        client_id: str | None = None,
175        client_secret: str | None = None,
176        trust_config: pathlib.Path | None = None,
177    ) -> Self:
178        """Configures the signing to be performed with Sigstore.
179
180        The signer in this configuration is changed to one that performs signing
181        with Sigstore.
182
183        Args:
184            oidc_issuer: An optional OpenID Connect issuer to use instead of the
185              default production one. Only relevant if `use_staging = False`.
186              Default is empty, relying on the Sigstore configuration.
187            use_ambient_credentials: Use ambient credentials (also known as
188              Workload Identity). Default is False. If ambient credentials
189              cannot be used (not available, or option disabled), a flow to get
190              signer identity via OIDC will start.
191            use_staging: Use staging configurations, instead of production. This
192              is supposed to be set to True only when testing. Default is False.
193            force_oob: If True, forces an out-of-band (OOB) OAuth flow. If set,
194              the OAuth authentication will not attempt to open the default web
195              browser. Instead, it will display a URL and code for manual
196              authentication. Default is False, which means the browser will be
197              opened automatically if possible.
198            identity_token: An explicit identity token to use when signing,
199              taking precedence over any ambient credential or OAuth workflow.
200            client_id: An optional client ID to use when performing OIDC-based
201              authentication. This is typically used to identify the
202              application making the request to the OIDC provider. If not
203              provided, the default client ID configured by Sigstore will be
204              used.
205            client_secret: An optional client secret to use along with the
206              client ID when authenticating with the OIDC provider. This is
207              required for confidential clients that need to prove their
208              identity to the OIDC provider. If not provided, it is assumed
209              that the client is public or the provider does not require a
210              secret.
211            trust_config: A path to a custom trust configuration. When provided,
212              the signature verification process will rely on the supplied
213              PKI and trust configurations, instead of the default Sigstore
214              setup. If not specified, the default Sigstore configuration
215              is used.
216
217        Return:
218            The new signing configuration.
219        """
220        self._signer = sigstore.Signer(
221            oidc_issuer=oidc_issuer,
222            use_ambient_credentials=use_ambient_credentials,
223            use_staging=use_staging,
224            identity_token=identity_token,
225            force_oob=force_oob,
226            client_id=client_id,
227            client_secret=client_secret,
228            trust_config=trust_config,
229        )
230        return self
231
232    def use_elliptic_key_signer(
233        self,
234        *,
235        private_key: hashing.PathLike,
236        password: str | None = None,
237        tsa_url: str | None = None,
238    ) -> Self:
239        """Configures the signing to be performed using elliptic curve keys.
240
241        The signer in this configuration is changed to one that performs signing
242        using a private key based on elliptic curve cryptography.
243
244        Args:
245            private_key: The path to the private key to use for signing.
246            password: An optional password for the key, if encrypted.
247            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
248              provided, the signature will include a trusted timestamp.
249
250        Return:
251            The new signing configuration.
252        """
253        self._signer = ec_key.Signer(
254            pathlib.Path(private_key), password, tsa_url=tsa_url
255        )
256        return self
257
258    def use_certificate_signer(
259        self,
260        *,
261        private_key: hashing.PathLike,
262        signing_certificate: hashing.PathLike,
263        certificate_chain: Iterable[hashing.PathLike],
264        tsa_url: str | None = None,
265    ) -> Self:
266        """Configures the signing to be performed using signing certificates.
267
268        The signer in this configuration is changed to one that performs signing
269        using cryptographic signing certificates.
270
271        Args:
272            private_key: The path to the private key to use for signing.
273            signing_certificate: The path to the signing certificate.
274            certificate_chain: Optional paths to other certificates to establish
275              a chain of trust.
276            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
277              provided, the signature will include a trusted timestamp.
278
279        Return:
280            The new signing configuration.
281        """
282        self._signer = certificate.Signer(
283            pathlib.Path(private_key),
284            pathlib.Path(signing_certificate),
285            [pathlib.Path(c) for c in certificate_chain],
286            tsa_url=tsa_url,
287        )
288        return self
289
290    def use_pkcs11_signer(
291        self,
292        *,
293        pkcs11_uri: str,
294        module_paths: Iterable[str] = frozenset(),
295        tsa_url: str | None = None,
296    ) -> Self:
297        """Configures the signing to be performed using PKCS #11.
298
299        The signer in this configuration is changed to one that performs signing
300        using a private key based on elliptic curve cryptography.
301
302        Args:
303            pkcs11_uri: The PKCS11 URI.
304            module_paths: Optional list of paths of PKCS #11 modules.
305            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
306              provided, the signature will include a trusted timestamp.
307
308        Return:
309            The new signing configuration.
310        """
311        try:
312            from model_signing._signing import sign_pkcs11 as pkcs11
313        except ImportError as e:
314            raise RuntimeError(
315                "PKCS #11 functionality requires the 'pkcs11' extra. "
316                "Install with 'pip install model-signing[pkcs11]'."
317            ) from e
318        self._signer = pkcs11.Signer(pkcs11_uri, module_paths, tsa_url=tsa_url)
319        return self
320
321    def use_pkcs11_certificate_signer(
322        self,
323        *,
324        pkcs11_uri: str,
325        signing_certificate: pathlib.Path,
326        certificate_chain: Iterable[pathlib.Path],
327        module_paths: Iterable[str] = frozenset(),
328        tsa_url: str | None = None,
329    ) -> Self:
330        """Configures the signing to be performed using signing certificates.
331
332        The signer in this configuration is changed to one that performs signing
333        using cryptographic certificates.
334
335        Args:
336            pkcs11_uri: The PKCS #11 URI.
337            signing_certificate: The path to the signing certificate.
338            certificate_chain: Optional paths to other certificates to establish
339              a chain of trust.
340            module_paths: Optional list of paths of PKCS #11 modules.
341            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
342              provided, the signature will include a trusted timestamp.
343
344        Return:
345            The new signing configuration.
346        """
347        try:
348            from model_signing._signing import sign_pkcs11 as pkcs11
349        except ImportError as e:
350            raise RuntimeError(
351                "PKCS #11 functionality requires the 'pkcs11' extra. "
352                "Install with 'pip install model-signing[pkcs11]'."
353            ) from e
354
355        self._signer = pkcs11.CertSigner(
356            pkcs11_uri,
357            signing_certificate,
358            certificate_chain,
359            module_paths=module_paths,
360            tsa_url=tsa_url,
361        )
362        return self
def sign( model_path: str | bytes | os.PathLike, signature_path: str | bytes | os.PathLike): 
57def sign(model_path: hashing.PathLike, signature_path: hashing.PathLike):
58    """Signs a model using the default configuration.
59
60    In this default configuration we sign using Sigstore and the default hashing
61    configuration from `model_signing.hashing`.
62
63    The resulting signature is in the Sigstore bundle format.
64
65    Args:
66        model_path: the path to the model to sign.
67        signature_path: the path of the resulting signature.
68    """
69    Config().sign(model_path, signature_path)

Signs a model using the default configuration.

In this default configuration we sign using Sigstore and the default hashing configuration from model_signing.hashing.

The resulting signature is in the Sigstore bundle format.

Arguments:
  • model_path: the path to the model to sign.
  • signature_path: the path of the resulting signature.
def sign_to_bytes(model_path: str | bytes | os.PathLike) -> bytes: 
72def sign_to_bytes(model_path: hashing.PathLike) -> bytes:
73    """Signs a model using the default configuration and returns the signature.
74
75    In this default configuration we sign using Sigstore and the default hashing
76    configuration from `model_signing.hashing`.
77
78    The resulting signature is the Sigstore bundle, returned in memory as UTF-8
79    encoded JSON bytes instead of being written to disk.
80
81    Args:
82        model_path: the path to the model to sign.
83
84    Returns:
85        The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.
86    """
87    return Config().sign_to_bytes(model_path)

Signs a model using the default configuration and returns the signature.

In this default configuration we sign using Sigstore and the default hashing configuration from model_signing.hashing.

The resulting signature is the Sigstore bundle, returned in memory as UTF-8 encoded JSON bytes instead of being written to disk.

Arguments:
  • model_path: the path to the model to sign.
Returns:

The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.

class Config: 
 90class Config:
 91    """Configuration to use when signing models.
 92
 93    Currently, we support signing with Sigstore (both the public
 94    instance and staging instance), signing with private keys,
 95    signing with signing certificates, and signing with custom
 96    PKI configurations using the `--trust_config` option.
 97    This allows users to bring their own trust configuration
 98    to sign and verify models. Other signing modes may be
 99    added in the future.
100    """
101
102    def __init__(self):
103        """Initializes the default configuration for signing."""
104        self._hashing_config = hashing.Config()
105        # lazy initialize default signer at signing to avoid network calls
106        self._signer = None
107
108    def sign(
109        self, model_path: hashing.PathLike, signature_path: hashing.PathLike
110    ):
111        """Signs a model using the current configuration.
112
113        Args:
114            model_path: The path to the model to sign.
115            signature_path: The path of the resulting signature.
116        """
117        signature = self._sign(model_path)
118        signature.write(pathlib.Path(signature_path))
119
120    def sign_to_bytes(self, model_path: hashing.PathLike) -> bytes:
121        """Signs a model and returns the signature as bytes.
122
123        This mirrors `sign`, but instead of writing the signature to disk it
124        returns the Sigstore bundle in memory. This is useful in serverless or
125        pipeline contexts where writing to the filesystem is undesirable or
126        impossible, and the bundle needs to be streamed, persisted to an object
127        store, or passed directly to another process.
128
129        The returned bytes are the UTF-8 encoded Sigstore bundle, identical to
130        what `sign` would have written to the signature path.
131
132        Args:
133            model_path: The path to the model to sign.
134
135        Returns:
136            The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.
137        """
138        return self._sign(model_path).to_bytes()
139
140    def _sign(self, model_path: hashing.PathLike) -> signing.Signature:
141        """Hashes and signs a model, returning the in-memory signature.
142
143        Args:
144            model_path: The path to the model to sign.
145
146        Returns:
147            The `Signature` produced by the configured signer.
148        """
149        if self._signer is None:
150            self.use_sigstore_signer()
151        manifest = self._hashing_config.hash(model_path)
152        payload = signing.Payload(manifest)
153        return self._signer.sign(payload)
154
155    def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
156        """Sets the new configuration for hashing models.
157
158        Args:
159            hashing_config: The new hashing configuration.
160
161        Returns:
162            The new signing configuration.
163        """
164        self._hashing_config = hashing_config
165        return self
166
167    def use_sigstore_signer(
168        self,
169        *,
170        oidc_issuer: str | None = None,
171        use_ambient_credentials: bool = False,
172        use_staging: bool = False,
173        force_oob: bool = False,
174        identity_token: str | None = None,
175        client_id: str | None = None,
176        client_secret: str | None = None,
177        trust_config: pathlib.Path | None = None,
178    ) -> Self:
179        """Configures the signing to be performed with Sigstore.
180
181        The signer in this configuration is changed to one that performs signing
182        with Sigstore.
183
184        Args:
185            oidc_issuer: An optional OpenID Connect issuer to use instead of the
186              default production one. Only relevant if `use_staging = False`.
187              Default is empty, relying on the Sigstore configuration.
188            use_ambient_credentials: Use ambient credentials (also known as
189              Workload Identity). Default is False. If ambient credentials
190              cannot be used (not available, or option disabled), a flow to get
191              signer identity via OIDC will start.
192            use_staging: Use staging configurations, instead of production. This
193              is supposed to be set to True only when testing. Default is False.
194            force_oob: If True, forces an out-of-band (OOB) OAuth flow. If set,
195              the OAuth authentication will not attempt to open the default web
196              browser. Instead, it will display a URL and code for manual
197              authentication. Default is False, which means the browser will be
198              opened automatically if possible.
199            identity_token: An explicit identity token to use when signing,
200              taking precedence over any ambient credential or OAuth workflow.
201            client_id: An optional client ID to use when performing OIDC-based
202              authentication. This is typically used to identify the
203              application making the request to the OIDC provider. If not
204              provided, the default client ID configured by Sigstore will be
205              used.
206            client_secret: An optional client secret to use along with the
207              client ID when authenticating with the OIDC provider. This is
208              required for confidential clients that need to prove their
209              identity to the OIDC provider. If not provided, it is assumed
210              that the client is public or the provider does not require a
211              secret.
212            trust_config: A path to a custom trust configuration. When provided,
213              the signature verification process will rely on the supplied
214              PKI and trust configurations, instead of the default Sigstore
215              setup. If not specified, the default Sigstore configuration
216              is used.
217
218        Return:
219            The new signing configuration.
220        """
221        self._signer = sigstore.Signer(
222            oidc_issuer=oidc_issuer,
223            use_ambient_credentials=use_ambient_credentials,
224            use_staging=use_staging,
225            identity_token=identity_token,
226            force_oob=force_oob,
227            client_id=client_id,
228            client_secret=client_secret,
229            trust_config=trust_config,
230        )
231        return self
232
233    def use_elliptic_key_signer(
234        self,
235        *,
236        private_key: hashing.PathLike,
237        password: str | None = None,
238        tsa_url: str | None = None,
239    ) -> Self:
240        """Configures the signing to be performed using elliptic curve keys.
241
242        The signer in this configuration is changed to one that performs signing
243        using a private key based on elliptic curve cryptography.
244
245        Args:
246            private_key: The path to the private key to use for signing.
247            password: An optional password for the key, if encrypted.
248            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
249              provided, the signature will include a trusted timestamp.
250
251        Return:
252            The new signing configuration.
253        """
254        self._signer = ec_key.Signer(
255            pathlib.Path(private_key), password, tsa_url=tsa_url
256        )
257        return self
258
259    def use_certificate_signer(
260        self,
261        *,
262        private_key: hashing.PathLike,
263        signing_certificate: hashing.PathLike,
264        certificate_chain: Iterable[hashing.PathLike],
265        tsa_url: str | None = None,
266    ) -> Self:
267        """Configures the signing to be performed using signing certificates.
268
269        The signer in this configuration is changed to one that performs signing
270        using cryptographic signing certificates.
271
272        Args:
273            private_key: The path to the private key to use for signing.
274            signing_certificate: The path to the signing certificate.
275            certificate_chain: Optional paths to other certificates to establish
276              a chain of trust.
277            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
278              provided, the signature will include a trusted timestamp.
279
280        Return:
281            The new signing configuration.
282        """
283        self._signer = certificate.Signer(
284            pathlib.Path(private_key),
285            pathlib.Path(signing_certificate),
286            [pathlib.Path(c) for c in certificate_chain],
287            tsa_url=tsa_url,
288        )
289        return self
290
291    def use_pkcs11_signer(
292        self,
293        *,
294        pkcs11_uri: str,
295        module_paths: Iterable[str] = frozenset(),
296        tsa_url: str | None = None,
297    ) -> Self:
298        """Configures the signing to be performed using PKCS #11.
299
300        The signer in this configuration is changed to one that performs signing
301        using a private key based on elliptic curve cryptography.
302
303        Args:
304            pkcs11_uri: The PKCS11 URI.
305            module_paths: Optional list of paths of PKCS #11 modules.
306            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
307              provided, the signature will include a trusted timestamp.
308
309        Return:
310            The new signing configuration.
311        """
312        try:
313            from model_signing._signing import sign_pkcs11 as pkcs11
314        except ImportError as e:
315            raise RuntimeError(
316                "PKCS #11 functionality requires the 'pkcs11' extra. "
317                "Install with 'pip install model-signing[pkcs11]'."
318            ) from e
319        self._signer = pkcs11.Signer(pkcs11_uri, module_paths, tsa_url=tsa_url)
320        return self
321
322    def use_pkcs11_certificate_signer(
323        self,
324        *,
325        pkcs11_uri: str,
326        signing_certificate: pathlib.Path,
327        certificate_chain: Iterable[pathlib.Path],
328        module_paths: Iterable[str] = frozenset(),
329        tsa_url: str | None = None,
330    ) -> Self:
331        """Configures the signing to be performed using signing certificates.
332
333        The signer in this configuration is changed to one that performs signing
334        using cryptographic certificates.
335
336        Args:
337            pkcs11_uri: The PKCS #11 URI.
338            signing_certificate: The path to the signing certificate.
339            certificate_chain: Optional paths to other certificates to establish
340              a chain of trust.
341            module_paths: Optional list of paths of PKCS #11 modules.
342            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
343              provided, the signature will include a trusted timestamp.
344
345        Return:
346            The new signing configuration.
347        """
348        try:
349            from model_signing._signing import sign_pkcs11 as pkcs11
350        except ImportError as e:
351            raise RuntimeError(
352                "PKCS #11 functionality requires the 'pkcs11' extra. "
353                "Install with 'pip install model-signing[pkcs11]'."
354            ) from e
355
356        self._signer = pkcs11.CertSigner(
357            pkcs11_uri,
358            signing_certificate,
359            certificate_chain,
360            module_paths=module_paths,
361            tsa_url=tsa_url,
362        )
363        return self

Configuration to use when signing models.

Currently, we support signing with Sigstore (both the public instance and staging instance), signing with private keys, signing with signing certificates, and signing with custom PKI configurations using the --trust_config option. This allows users to bring their own trust configuration to sign and verify models. Other signing modes may be added in the future.

Config() 
102    def __init__(self):
103        """Initializes the default configuration for signing."""
104        self._hashing_config = hashing.Config()
105        # lazy initialize default signer at signing to avoid network calls
106        self._signer = None

Initializes the default configuration for signing.

def sign( self, model_path: str | bytes | os.PathLike, signature_path: str | bytes | os.PathLike): 
108    def sign(
109        self, model_path: hashing.PathLike, signature_path: hashing.PathLike
110    ):
111        """Signs a model using the current configuration.
112
113        Args:
114            model_path: The path to the model to sign.
115            signature_path: The path of the resulting signature.
116        """
117        signature = self._sign(model_path)
118        signature.write(pathlib.Path(signature_path))

Signs a model using the current configuration.

Arguments:
  • model_path: The path to the model to sign.
  • signature_path: The path of the resulting signature.
def sign_to_bytes(self, model_path: str | bytes | os.PathLike) -> bytes: 
120    def sign_to_bytes(self, model_path: hashing.PathLike) -> bytes:
121        """Signs a model and returns the signature as bytes.
122
123        This mirrors `sign`, but instead of writing the signature to disk it
124        returns the Sigstore bundle in memory. This is useful in serverless or
125        pipeline contexts where writing to the filesystem is undesirable or
126        impossible, and the bundle needs to be streamed, persisted to an object
127        store, or passed directly to another process.
128
129        The returned bytes are the UTF-8 encoded Sigstore bundle, identical to
130        what `sign` would have written to the signature path.
131
132        Args:
133            model_path: The path to the model to sign.
134
135        Returns:
136            The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.
137        """
138        return self._sign(model_path).to_bytes()

Signs a model and returns the signature as bytes.

This mirrors sign, but instead of writing the signature to disk it returns the Sigstore bundle in memory. This is useful in serverless or pipeline contexts where writing to the filesystem is undesirable or impossible, and the bundle needs to be streamed, persisted to an object store, or passed directly to another process.

The returned bytes are the UTF-8 encoded Sigstore bundle, identical to what sign would have written to the signature path.

Arguments:
  • model_path: The path to the model to sign.
Returns:

The signature, as a Sigstore bundle encoded in UTF-8 JSON bytes.

def set_hashing_config(self, hashing_config: model_signing.hashing.Config) -> Self: 
155    def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
156        """Sets the new configuration for hashing models.
157
158        Args:
159            hashing_config: The new hashing configuration.
160
161        Returns:
162            The new signing configuration.
163        """
164        self._hashing_config = hashing_config
165        return self

Sets the new configuration for hashing models.

Arguments:
  • hashing_config: The new hashing configuration.
Returns:

The new signing configuration.

def use_sigstore_signer( self, *, oidc_issuer: str | None = None, use_ambient_credentials: bool = False, use_staging: bool = False, force_oob: bool = False, identity_token: str | None = None, client_id: str | None = None, client_secret: str | None = None, trust_config: pathlib.Path | None = None) -> Self: 
167    def use_sigstore_signer(
168        self,
169        *,
170        oidc_issuer: str | None = None,
171        use_ambient_credentials: bool = False,
172        use_staging: bool = False,
173        force_oob: bool = False,
174        identity_token: str | None = None,
175        client_id: str | None = None,
176        client_secret: str | None = None,
177        trust_config: pathlib.Path | None = None,
178    ) -> Self:
179        """Configures the signing to be performed with Sigstore.
180
181        The signer in this configuration is changed to one that performs signing
182        with Sigstore.
183
184        Args:
185            oidc_issuer: An optional OpenID Connect issuer to use instead of the
186              default production one. Only relevant if `use_staging = False`.
187              Default is empty, relying on the Sigstore configuration.
188            use_ambient_credentials: Use ambient credentials (also known as
189              Workload Identity). Default is False. If ambient credentials
190              cannot be used (not available, or option disabled), a flow to get
191              signer identity via OIDC will start.
192            use_staging: Use staging configurations, instead of production. This
193              is supposed to be set to True only when testing. Default is False.
194            force_oob: If True, forces an out-of-band (OOB) OAuth flow. If set,
195              the OAuth authentication will not attempt to open the default web
196              browser. Instead, it will display a URL and code for manual
197              authentication. Default is False, which means the browser will be
198              opened automatically if possible.
199            identity_token: An explicit identity token to use when signing,
200              taking precedence over any ambient credential or OAuth workflow.
201            client_id: An optional client ID to use when performing OIDC-based
202              authentication. This is typically used to identify the
203              application making the request to the OIDC provider. If not
204              provided, the default client ID configured by Sigstore will be
205              used.
206            client_secret: An optional client secret to use along with the
207              client ID when authenticating with the OIDC provider. This is
208              required for confidential clients that need to prove their
209              identity to the OIDC provider. If not provided, it is assumed
210              that the client is public or the provider does not require a
211              secret.
212            trust_config: A path to a custom trust configuration. When provided,
213              the signature verification process will rely on the supplied
214              PKI and trust configurations, instead of the default Sigstore
215              setup. If not specified, the default Sigstore configuration
216              is used.
217
218        Return:
219            The new signing configuration.
220        """
221        self._signer = sigstore.Signer(
222            oidc_issuer=oidc_issuer,
223            use_ambient_credentials=use_ambient_credentials,
224            use_staging=use_staging,
225            identity_token=identity_token,
226            force_oob=force_oob,
227            client_id=client_id,
228            client_secret=client_secret,
229            trust_config=trust_config,
230        )
231        return self

Configures the signing to be performed with Sigstore.

The signer in this configuration is changed to one that performs signing with Sigstore.

Arguments:
  • oidc_issuer: An optional OpenID Connect issuer to use instead of the default production one. Only relevant if use_staging = False. Default is empty, relying on the Sigstore configuration.
  • use_ambient_credentials: Use ambient credentials (also known as Workload Identity). Default is False. If ambient credentials cannot be used (not available, or option disabled), a flow to get signer identity via OIDC will start.
  • use_staging: Use staging configurations, instead of production. This is supposed to be set to True only when testing. Default is False.
  • force_oob: If True, forces an out-of-band (OOB) OAuth flow. If set, the OAuth authentication will not attempt to open the default web browser. Instead, it will display a URL and code for manual authentication. Default is False, which means the browser will be opened automatically if possible.
  • identity_token: An explicit identity token to use when signing, taking precedence over any ambient credential or OAuth workflow.
  • client_id: An optional client ID to use when performing OIDC-based authentication. This is typically used to identify the application making the request to the OIDC provider. If not provided, the default client ID configured by Sigstore will be used.
  • client_secret: An optional client secret to use along with the client ID when authenticating with the OIDC provider. This is required for confidential clients that need to prove their identity to the OIDC provider. If not provided, it is assumed that the client is public or the provider does not require a secret.
  • trust_config: A path to a custom trust configuration. When provided, the signature verification process will rely on the supplied PKI and trust configurations, instead of the default Sigstore setup. If not specified, the default Sigstore configuration is used.
Return:

The new signing configuration.

def use_elliptic_key_signer( self, *, private_key: str | bytes | os.PathLike, password: str | None = None, tsa_url: str | None = None) -> Self: 
233    def use_elliptic_key_signer(
234        self,
235        *,
236        private_key: hashing.PathLike,
237        password: str | None = None,
238        tsa_url: str | None = None,
239    ) -> Self:
240        """Configures the signing to be performed using elliptic curve keys.
241
242        The signer in this configuration is changed to one that performs signing
243        using a private key based on elliptic curve cryptography.
244
245        Args:
246            private_key: The path to the private key to use for signing.
247            password: An optional password for the key, if encrypted.
248            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
249              provided, the signature will include a trusted timestamp.
250
251        Return:
252            The new signing configuration.
253        """
254        self._signer = ec_key.Signer(
255            pathlib.Path(private_key), password, tsa_url=tsa_url
256        )
257        return self

Configures the signing to be performed using elliptic curve keys.

The signer in this configuration is changed to one that performs signing using a private key based on elliptic curve cryptography.

Arguments:
  • private_key: The path to the private key to use for signing.
  • password: An optional password for the key, if encrypted.
  • tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When provided, the signature will include a trusted timestamp.
Return:

The new signing configuration.

def use_certificate_signer( self, *, private_key: str | bytes | os.PathLike, signing_certificate: str | bytes | os.PathLike, certificate_chain: Iterable[str | bytes | os.PathLike], tsa_url: str | None = None) -> Self: 
259    def use_certificate_signer(
260        self,
261        *,
262        private_key: hashing.PathLike,
263        signing_certificate: hashing.PathLike,
264        certificate_chain: Iterable[hashing.PathLike],
265        tsa_url: str | None = None,
266    ) -> Self:
267        """Configures the signing to be performed using signing certificates.
268
269        The signer in this configuration is changed to one that performs signing
270        using cryptographic signing certificates.
271
272        Args:
273            private_key: The path to the private key to use for signing.
274            signing_certificate: The path to the signing certificate.
275            certificate_chain: Optional paths to other certificates to establish
276              a chain of trust.
277            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
278              provided, the signature will include a trusted timestamp.
279
280        Return:
281            The new signing configuration.
282        """
283        self._signer = certificate.Signer(
284            pathlib.Path(private_key),
285            pathlib.Path(signing_certificate),
286            [pathlib.Path(c) for c in certificate_chain],
287            tsa_url=tsa_url,
288        )
289        return self

Configures the signing to be performed using signing certificates.

The signer in this configuration is changed to one that performs signing using cryptographic signing certificates.

Arguments:
  • private_key: The path to the private key to use for signing.
  • signing_certificate: The path to the signing certificate.
  • certificate_chain: Optional paths to other certificates to establish a chain of trust.
  • tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When provided, the signature will include a trusted timestamp.
Return:

The new signing configuration.

def use_pkcs11_signer( self, *, pkcs11_uri: str, module_paths: Iterable[str] = frozenset(), tsa_url: str | None = None) -> Self: 
291    def use_pkcs11_signer(
292        self,
293        *,
294        pkcs11_uri: str,
295        module_paths: Iterable[str] = frozenset(),
296        tsa_url: str | None = None,
297    ) -> Self:
298        """Configures the signing to be performed using PKCS #11.
299
300        The signer in this configuration is changed to one that performs signing
301        using a private key based on elliptic curve cryptography.
302
303        Args:
304            pkcs11_uri: The PKCS11 URI.
305            module_paths: Optional list of paths of PKCS #11 modules.
306            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
307              provided, the signature will include a trusted timestamp.
308
309        Return:
310            The new signing configuration.
311        """
312        try:
313            from model_signing._signing import sign_pkcs11 as pkcs11
314        except ImportError as e:
315            raise RuntimeError(
316                "PKCS #11 functionality requires the 'pkcs11' extra. "
317                "Install with 'pip install model-signing[pkcs11]'."
318            ) from e
319        self._signer = pkcs11.Signer(pkcs11_uri, module_paths, tsa_url=tsa_url)
320        return self

Configures the signing to be performed using PKCS #11.

The signer in this configuration is changed to one that performs signing using a private key based on elliptic curve cryptography.

Arguments:
  • pkcs11_uri: The PKCS11 URI.
  • module_paths: Optional list of paths of PKCS #11 modules.
  • tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When provided, the signature will include a trusted timestamp.
Return:

The new signing configuration.

def use_pkcs11_certificate_signer( self, *, pkcs11_uri: str, signing_certificate: pathlib.Path, certificate_chain: Iterable[pathlib.Path], module_paths: Iterable[str] = frozenset(), tsa_url: str | None = None) -> Self: 
322    def use_pkcs11_certificate_signer(
323        self,
324        *,
325        pkcs11_uri: str,
326        signing_certificate: pathlib.Path,
327        certificate_chain: Iterable[pathlib.Path],
328        module_paths: Iterable[str] = frozenset(),
329        tsa_url: str | None = None,
330    ) -> Self:
331        """Configures the signing to be performed using signing certificates.
332
333        The signer in this configuration is changed to one that performs signing
334        using cryptographic certificates.
335
336        Args:
337            pkcs11_uri: The PKCS #11 URI.
338            signing_certificate: The path to the signing certificate.
339            certificate_chain: Optional paths to other certificates to establish
340              a chain of trust.
341            module_paths: Optional list of paths of PKCS #11 modules.
342            tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When
343              provided, the signature will include a trusted timestamp.
344
345        Return:
346            The new signing configuration.
347        """
348        try:
349            from model_signing._signing import sign_pkcs11 as pkcs11
350        except ImportError as e:
351            raise RuntimeError(
352                "PKCS #11 functionality requires the 'pkcs11' extra. "
353                "Install with 'pip install model-signing[pkcs11]'."
354            ) from e
355
356        self._signer = pkcs11.CertSigner(
357            pkcs11_uri,
358            signing_certificate,
359            certificate_chain,
360            module_paths=module_paths,
361            tsa_url=tsa_url,
362        )
363        return self

Configures the signing to be performed using signing certificates.

The signer in this configuration is changed to one that performs signing using cryptographic certificates.

Arguments:
  • pkcs11_uri: The PKCS #11 URI.
  • signing_certificate: The path to the signing certificate.
  • certificate_chain: Optional paths to other certificates to establish a chain of trust.
  • module_paths: Optional list of paths of PKCS #11 modules.
  • tsa_url: Optional URL of an RFC 3161 Timestamp Authority. When provided, the signature will include a trusted timestamp.
Return:

The new signing configuration.