Make the API fully configurable (#416)

* Make the library API fully configurable

Signed-off-by: Mihai Maruseac <[email protected]>

* Remove `verify`, document exception.

Signed-off-by: Mihai Maruseac <[email protected]>

---------

Signed-off-by: Mihai Maruseac <[email protected]>

Author: mihaimaruseac

src/model_signing/hashing.py

@@ -90,9 +90,7 @@ def __init__(self):
         symbolic link in the model directory results in an error.
         """
         self._ignored_paths = frozenset()
-        self._serializer = file.Serializer(
-            self._build_file_hasher_factory(), allow_symlinks=False
-        )
+        self.use_file_serialization()
 
     def hash(self, model_path: os.PathLike) -> manifest.Manifest:
         """Hashes a model using the current configuration."""
@@ -137,11 +135,11 @@ def _build_file_hasher_factory(
             method.
         """
 
-        def factory(path: pathlib.Path) -> io.SimpleFileHasher:
+        def _factory(path: pathlib.Path) -> io.SimpleFileHasher:
             hasher = self._build_stream_hasher(hashing_algorithm)
             return io.SimpleFileHasher(path, hasher, chunk_size=chunk_size)
 
-        return factory
+        return _factory
 
     def _build_sharded_file_hasher_factory(
         self,
@@ -162,23 +160,23 @@ def _build_sharded_file_hasher_factory(
             The hasher factory that should be used by the active serialization
             method.
         """
-        algorithm = self._build_stream_hasher(hashing_algorithm)
 
-        def factory(
+        def _factory(
             path: pathlib.Path, start: int, end: int
         ) -> io.ShardedFileHasher:
+            hasher = self._build_stream_hasher(hashing_algorithm)
             return io.ShardedFileHasher(
                 path,
-                algorithm,
+                hasher,
                 start=start,
                 end=end,
                 chunk_size=chunk_size,
                 shard_size=shard_size,
             )
 
-        return factory
+        return _factory
 
-    def set_serialize_by_file_to_manifest(
+    def use_file_serialization(
         self,
         *,
         hashing_algorithm: Literal["sha256", "blake2"] = "sha256",
@@ -213,7 +211,7 @@ def set_serialize_by_file_to_manifest(
         )
         return self
 
-    def set_serialize_by_file_shard_to_manifest(
+    def use_shard_serialization(
         self,
         *,
         hashing_algorithm: Literal["sha256", "blake2"] = "sha256",

src/model_signing/signing.py

@@ -19,14 +19,15 @@
 `hashing.py`, `signing.py` and `verifying.py` at the root level of the library.
 """
 
-from collections.abc import Callable
+from collections.abc import Iterable
 import os
 import pathlib
 import sys
 from typing import Optional
 
 from model_signing import hashing
-from model_signing import manifest
+from model_signing._signing import sign_certificate as certificate
+from model_signing._signing import sign_ec_key as ec_key
 from model_signing._signing import sign_sigstore as sigstore
 from model_signing._signing import signing
 
@@ -60,10 +61,7 @@ class Config:
     def __init__(self):
         """Initializes the default configuration for signing."""
         self._hashing_config = hashing.Config()
-        self._payload_generator = signing.Payload
-        self._signer = sigstore.Signer(
-            use_ambient_credentials=False, use_staging=False
-        )
+        self.use_sigstore_signer()
 
     def sign(self, model_path: os.PathLike, signature_path: os.PathLike):
         """Signs a model using the current configuration.
@@ -73,7 +71,7 @@ def sign(self, model_path: os.PathLike, signature_path: os.PathLike):
             signature_path: the path of the resulting signature.
         """
         manifest = self._hashing_config.hash(model_path)
-        payload = self._payload_generator(manifest)
+        payload = signing.Payload(manifest)
         signature = self._signer.sign(payload)
         signature.write(pathlib.Path(signature_path))
 
@@ -89,25 +87,7 @@ def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
         self._hashing_config = hashing_config
         return self
 
-    def set_payload_generator(
-        self, generator: Callable[[manifest.Manifest], signing.Payload]
-    ) -> Self:
-        """Sets the conversion from manifest to signing payload.
-
-        Since we want to support multiple serialization formats and multiple
-        signing solutions, we use a payload generator to relax the coupling
-        between the two.
-
-        Args:
-            generator: the conversion from a manifest to a signing payload.
-
-        Return:
-            The new signing configuration.
-        """
-        self._payload_generator = generator
-        return self
-
-    def set_sigstore_signer(
+    def use_sigstore_signer(
         self,
         *,
         oidc_issuer: Optional[str] = None,
@@ -117,9 +97,8 @@ def set_sigstore_signer(
     ) -> Self:
         """Configures the signing to be performed with Sigstore.
 
-        Only one signer can be configured. Currently, we only support Sigstore
-        in the API, but the CLI supports signing with PKI, BYOK and no signing.
-        We will merge the configurations in a subsequent change.
+        The signer in this configuration is changed to one that performs signing
+        with Sigstore, as configured.
 
         Args:
             oidc_issuer: An optional OpenID Connect issuer to use instead of the
@@ -144,3 +123,47 @@ def set_sigstore_signer(
             identity_token=identity_token,
         )
         return self
+
+    def use_elliptic_key_signer(
+        self, *, private_key: pathlib.Path, password: Optional[str] = None
+    ) -> 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.
+
+        Args:
+            private_key: The path to the private key to use for signing.
+            password: An optional password for the key, if encrypted.
+
+        Return:
+            The new signing configuration.
+        """
+        self._signer = ec_key.Signer(private_key, password)
+        return self
+
+    def use_certificate_signer(
+        self,
+        *,
+        private_key: pathlib.Path,
+        signing_certificate: pathlib.Path,
+        certificate_chain: Iterable[pathlib.Path],
+    ) -> 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.
+
+        Args:
+            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.
+
+        Return:
+            The new signing configuration.
+        """
+        self._signer = certificate.Signer(
+            private_key, signing_certificate, certificate_chain
+        )
+        return self

src/model_signing/verifying.py

@@ -20,12 +20,14 @@
 of the library.
 """
 
+from collections.abc import Iterable
 import os
 import pathlib
 import sys
-from typing import Optional
 
 from model_signing import hashing
+from model_signing._signing import sign_certificate as certificate
+from model_signing._signing import sign_ec_key as ec_key
 from model_signing._signing import sign_sigstore as sigstore
 
 
@@ -35,33 +37,6 @@
     from typing_extensions import Self
 
 
-def verify(
-    model_path: os.PathLike,
-    signature_path: os.PathLike,
-    *,
-    identity: str,
-    oidc_issuer: Optional[str] = None,
-    use_staging: bool = False,
-):
-    """Verifies that a model conforms to a signature.
-
-    Currently, this assumes signatures over DSSE, using Sigstore. We will add
-    support for more cases in a future change.
-
-    Args:
-        model_path: the path to the model to verify.
-        signature_path: the path to the signature to check.
-        identity: The expected identity that has signed the model.
-        oidc_issuer: The expected OpenID Connect issuer that provided the
-          certificate used for the signature.
-        use_staging: Use staging configurations, instead of production. This
-          is supposed to be set to True only when testing. Default is False.
-    """
-    Config().set_sigstore_dsse_verifier(
-        identity=identity, oidc_issuer=oidc_issuer, use_staging=use_staging
-    ).verify(model_path, signature_path)
-
-
 class Config:
     """Configuration to use when verifying models against signatures.
 
@@ -81,8 +56,13 @@ def verify(self, model_path: os.PathLike, signature_path: os.PathLike):
 
         Args:
             model_path: the path to the model to verify.
-            signature_path: the path to the signature to check.
+
+        Raises:
+            ValueError: No verifier has been configured.
         """
+        if self._verifier is None:
+            raise ValueError("Attempting to verify with no configured verifier")
+
         signature = sigstore.Signature.read(pathlib.Path(signature_path))
         expected_manifest = self._verifier.verify(signature)
         actual_manifest = self._hashing_config.hash(model_path)
@@ -102,19 +82,14 @@ def set_hashing_config(self, hashing_config: hashing.Config) -> Self:
         self._hashing_config = hashing_config
         return self
 
-    def set_sigstore_dsse_verifier(
-        self,
-        *,
-        identity: str,
-        oidc_issuer: Optional[str] = None,
-        use_staging: bool = False,
+    def use_sigstore_verifier(
+        self, *, identity: str, oidc_issuer: str, use_staging: bool = False
     ) -> Self:
-        """Configures the verification of a Sigstore signature over DSSE.
+        """Configures the verification of signatures produced by Sigstore.
 
-        Only one verifier can be configured. Currently, we only support Sigstore
-        in the API, but the CLI supports signing with PKI, BYOK and no
-        signing/verification.  We will merge the configurations in a subsequent
-        change.
+        The verifier in this configuration is changed to one that performs
+        verification of Sigstore signatures (sigstore bundles signed by
+        keyless signing via Sigstore).
 
         Args:
             identity: The expected identity that has signed the model.
@@ -130,3 +105,38 @@ def set_sigstore_dsse_verifier(
             identity=identity, oidc_issuer=oidc_issuer, use_staging=use_staging
         )
         return self
+
+    def use_elliptic_key_verifier(self, *, public_key: pathlib.Path) -> Self:
+        """Configures the verification of signatures generated by a private key.
+
+        The verifier in this configuration is changed to one that performs
+        verification of sgistore bundles signed by an elliptic curve private
+        key. The public key used in the configuration must match the private key
+        used during signing.
+
+        Args:
+            public_key: The path to the public key to verify with.
+
+        Return:
+            The new verification configuration.
+        """
+        self._verifier = ec_key.Verifier(public_key)
+        return self
+
+    def use_certificate_verifier(
+        self, *, certificate_chain: Iterable[pathlib.Path] = frozenset()
+    ) -> Self:
+        """Configures the verification of signatures generated by a certificate.
+
+        The verifier in this configuration is changed to one that performs
+        verification of sgistore bundles signed by a signing certificate.
+
+        Args:
+            certificate_chain: Certificate chain to establish root of trust. If
+              empty, the operating system's one is used.
+
+        Return:
+            The new verification configuration.
+        """
+        self._verifier = certificate.Verifier(certificate_chain)
+        return self

tests/api_test.py

@@ -88,16 +88,16 @@ def test_sign_and_verify(
         self, sigstore_oidc_beacon_token, sample_model_folder, tmp_path
     ):
         sc = signing.Config()
-        sc.set_sigstore_signer(
+        sc.use_sigstore_signer(
             use_staging=True, identity_token=sigstore_oidc_beacon_token
         )
         signature_path = tmp_path / "model.sig"
         sc.sign(sample_model_folder, signature_path)
 
         expected_identity = "https://github.com/sigstore-conformance/extremely-dangerous-public-oidc-beacon/.github/workflows/extremely-dangerous-oidc-beacon.yml@refs/heads/main"
-        verifying.verify(
-            sample_model_folder,
-            signature_path,
+        expected_oidc_issuer = "https://token.actions.githubusercontent.com"
+        verifying.Config().use_sigstore_verifier(
             identity=expected_identity,
+            oidc_issuer=expected_oidc_issuer,
             use_staging=True,
-        )
+        ).verify(sample_model_folder, signature_path)