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        if "ignore_paths" in expected_manifest.serialization_type:
101            self._hashing_config.add_ignored_paths(
102                model_path=model_path,
103                paths=expected_manifest.serialization_type["ignore_paths"],
104            )
105        actual_manifest = self._hashing_config.hash(model_path)
106
107        if actual_manifest != expected_manifest:
108            raise ValueError("Signature mismatch")
109
110    def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
111        """Sets the new configuration for hashing models.
112
113        After calling this method, the automatic guessing of the hashing
114        configuration used during signing is no longer possible from within one
115        instance of this class.
116
117        Args:
118            hashing_config: The new hashing configuration.
119
120        Returns:
121            The new signing configuration.
122        """
123        self._hashing_config = hashing_config
124        return self
125
126    def _guess_hashing_config(self, source_manifest: manifest.Manifest) -> None:
127        """Attempts to guess the hashing config from a manifest."""
128        args = source_manifest.serialization_type
129        method = args["method"]
130        # TODO: Once Python 3.9 support is deprecated revert to using `match`
131        if method == "files":
132            self._hashing_config = hashing.Config().use_file_serialization(
133                hashing_algorithm=args["hash_type"],
134                allow_symlinks=args["allow_symlinks"],
135                ignore_paths=args.get("ignore_paths", frozenset()),
136            )
137        elif method == "shards":
138            self._hashing_config = hashing.Config().use_shard_serialization(
139                hashing_algorithm=args["hash_type"],
140                shard_size=args["shard_size"],
141                allow_symlinks=args["allow_symlinks"],
142                ignore_paths=args.get("ignore_paths", frozenset()),
143            )
144        else:
145            raise ValueError("Cannot guess the hashing configuration")
146
147    def use_sigstore_verifier(
148        self, *, identity: str, oidc_issuer: str, use_staging: bool = False
149    ) -> Self:
150        """Configures the verification of signatures produced by Sigstore.
151
152        The verifier in this configuration is changed to one that performs
153        verification of Sigstore signatures (sigstore bundles signed by
154        keyless signing via Sigstore).
155
156        Args:
157            identity: The expected identity that has signed the model.
158            oidc_issuer: The expected OpenID Connect issuer that provided the
159              certificate used for the signature.
160            use_staging: Use staging configurations, instead of production. This
161              is supposed to be set to True only when testing. Default is False.
162
163        Return:
164            The new verification configuration.
165        """
166        self._uses_sigstore = True
167        self._verifier = sigstore.Verifier(
168            identity=identity, oidc_issuer=oidc_issuer, use_staging=use_staging
169        )
170        return self
171
172    def use_elliptic_key_verifier(
173        self, *, public_key: hashing.PathLike
174    ) -> Self:
175        """Configures the verification of signatures generated by a private key.
176
177        The verifier in this configuration is changed to one that performs
178        verification of sgistore bundles signed by an elliptic curve private
179        key. The public key used in the configuration must match the private key
180        used during signing.
181
182        Args:
183            public_key: The path to the public key to verify with.
184
185        Return:
186            The new verification configuration.
187        """
188        self._uses_sigstore = False
189        self._verifier = ec_key.Verifier(pathlib.Path(public_key))
190        return self
191
192    def use_certificate_verifier(
193        self,
194        *,
195        certificate_chain: Iterable[hashing.PathLike] = frozenset(),
196        log_fingerprints: bool = False,
197    ) -> Self:
198        """Configures the verification of signatures generated by a certificate.
199
200        The verifier in this configuration is changed to one that performs
201        verification of sgistore bundles signed by a signing certificate.
202
203        Args:
204            certificate_chain: Certificate chain to establish root of trust. If
205              empty, the operating system's one is used.
206            log_fingerprints: Log certificates' SHA256 fingerprints
207
208        Return:
209            The new verification configuration.
210        """
211        self._uses_sigstore = False
212        self._verifier = certificate.Verifier(
213            [pathlib.Path(c) for c in certificate_chain],
214            log_fingerprints=log_fingerprints,
215        )
216        return self