model_signing.verifying

  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 verification interface of `model_signing` library.
 16
 17This module supports configuring the verification method used to verify a model,
 18before performing the verification.
 19
 20```python
 21model_signing.verifying.Config().use_sigstore_verifier(
 22    identity=identity, oidc_issuer=oidc_provider
 23).verify("finbert", "finbert.sig")
 24```
 25
 26The same verification configuration can be used to verify multiple models:
 27
 28```python
 29verifying_config = model_signing.signing.Config().use_elliptic_key_verifier(
 30    public_key="key.pub"
 31)
 32
 33for model in all_models:
 34    verifying_config.verify(model, f"{model}_sharded.sig")
 35```
 36
 37The API defined here is stable and backwards compatible.
 38"""
 39
 40from collections.abc import Iterable
 41import pathlib
 42import sys
 43
 44from model_signing import hashing
 45from model_signing import manifest
 46from model_signing._signing import sign_certificate as certificate
 47from model_signing._signing import sign_ec_key as ec_key
 48from model_signing._signing import sign_sigstore as sigstore
 49from model_signing._signing import sign_sigstore_pb as sigstore_pb
 50
 51
 52if sys.version_info >= (3, 11):
 53    from typing import Self
 54else:
 55    from typing_extensions import Self
 56
 57
 58class Config:
 59    """Configuration to use when verifying models against signatures.
 60
 61    The verification configuration is needed to determine how to read and verify
 62    the signature. Given we support multiple signing format, the verification
 63    settings must match the signing ones.
 64
 65    The configuration also supports configuring the hashing configuration from
 66    `model_signing.hashing`. This should also match the configuration used
 67    during signing. However, by default, we can attempt to guess it from the
 68    signature.
 69    """
 70
 71    def __init__(self):
 72        """Initializes the default configuration for verification."""
 73        self._hashing_config = None
 74        self._verifier = None
 75        self._uses_sigstore = False
 76
 77    def verify(
 78        self, model_path: hashing.PathLike, signature_path: hashing.PathLike
 79    ):
 80        """Verifies that a model conforms to a signature.
 81
 82        Args:
 83            model_path: The path to the model to verify.
 84
 85        Raises:
 86            ValueError: No verifier has been configured.
 87        """
 88        if self._verifier is None:
 89            raise ValueError("Attempting to verify with no configured verifier")
 90
 91        if self._uses_sigstore:
 92            signature = sigstore.Signature.read(pathlib.Path(signature_path))
 93        else:
 94            signature = sigstore_pb.Signature.read(pathlib.Path(signature_path))
 95
 96        expected_manifest = self._verifier.verify(signature)
 97
 98        if self._hashing_config is None:
 99            self._guess_hashing_config(expected_manifest)
100        actual_manifest = self._hashing_config.hash(model_path)
101
102        if actual_manifest != expected_manifest:
103            raise ValueError("Signature mismatch")
104
105    def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
106        """Sets the new configuration for hashing models.
107
108        After calling this method, the automatic guessing of the hashing
109        configuration used during signing is no longer possible from within one
110        instance of this class.
111
112        Args:
113            hashing_config: The new hashing configuration.
114
115        Returns:
116            The new signing configuration.
117        """
118        self._hashing_config = hashing_config
119        return self
120
121    def _guess_hashing_config(self, source_manifest: manifest.Manifest) -> None:
122        """Attempts to guess the hashing config from a manifest."""
123        args = source_manifest.serialization_type
124        method = args["method"]
125        # TODO: Once Python 3.9 support is deprecated revert to using `match`
126        if method == "files":
127            self._hashing_config = hashing.Config().use_file_serialization(
128                hashing_algorithm=args["hash_type"],
129                allow_symlinks=args["allow_symlinks"],
130            )
131        elif method == "shards":
132            self._hashing_config = hashing.Config().use_shard_serialization(
133                hashing_algorithm=args["hash_type"],
134                shard_size=args["shard_size"],
135                allow_symlinks=args["allow_symlinks"],
136            )
137        else:
138            raise ValueError("Cannot guess the hashing configuration")
139
140    def use_sigstore_verifier(
141        self, *, identity: str, oidc_issuer: str, use_staging: bool = False
142    ) -> Self:
143        """Configures the verification of signatures produced by Sigstore.
144
145        The verifier in this configuration is changed to one that performs
146        verification of Sigstore signatures (sigstore bundles signed by
147        keyless signing via Sigstore).
148
149        Args:
150            identity: The expected identity that has signed the model.
151            oidc_issuer: The expected OpenID Connect issuer that provided the
152              certificate used for the signature.
153            use_staging: Use staging configurations, instead of production. This
154              is supposed to be set to True only when testing. Default is False.
155
156        Return:
157            The new verification configuration.
158        """
159        self._uses_sigstore = True
160        self._verifier = sigstore.Verifier(
161            identity=identity, oidc_issuer=oidc_issuer, use_staging=use_staging
162        )
163        return self
164
165    def use_elliptic_key_verifier(
166        self, *, public_key: hashing.PathLike
167    ) -> Self:
168        """Configures the verification of signatures generated by a private key.
169
170        The verifier in this configuration is changed to one that performs
171        verification of sgistore bundles signed by an elliptic curve private
172        key. The public key used in the configuration must match the private key
173        used during signing.
174
175        Args:
176            public_key: The path to the public key to verify with.
177
178        Return:
179            The new verification configuration.
180        """
181        self._uses_sigstore = False
182        self._verifier = ec_key.Verifier(pathlib.Path(public_key))
183        return self
184
185    def use_certificate_verifier(
186        self,
187        *,
188        certificate_chain: Iterable[hashing.PathLike] = frozenset(),
189        log_fingerprints: bool = False,
190    ) -> Self:
191        """Configures the verification of signatures generated by a certificate.
192
193        The verifier in this configuration is changed to one that performs
194        verification of sgistore bundles signed by a signing certificate.
195
196        Args:
197            certificate_chain: Certificate chain to establish root of trust. If
198              empty, the operating system's one is used.
199            log_fingerprints: Log certificates' SHA256 fingerprints
200
201        Return:
202            The new verification configuration.
203        """
204        self._uses_sigstore = False
205        self._verifier = certificate.Verifier(
206            [pathlib.Path(c) for c in certificate_chain],
207            log_fingerprints=log_fingerprints,
208        )
209        return self