Initial GCP Signer implementation

A bare bones Signer for Google Cloud KMS: Private keys live in KMS,
signing happens in KMS (although payload hashing happens in Signer).

Key creation or import is not supported at this point.

A test is added with a few caveats:
* dependencies are not added to requirements.txt: this would
  more than triple the size of requirements-pinned.txt...
  There is a separate requirements file: this is not ideal but best I
  could come up with.
* Test only works on GitHub (because of the GCP authentication),
  and only on branches within the upstream repo: not on PRs from forks
* Test is run only once: it's a smoke test, not an exhaustive matrix
  test.

Author: jku

.github/workflows/test-kms.yml

@@ -0,0 +1,38 @@
+name: Run KMS tests
+
+on:
+  push:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  test-kms:
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: 'write' # for OIDC auth for GCP authentication
+
+    steps:
+      - name: Checkout securesystemslib
+        uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          cache: 'pip'
+          cache-dependency-path: 'requirements*.txt'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade tox
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@c4799db9111fba4461e9f9da8732e5057b394f72
+        with:
+          token_format: access_token
+          workload_identity_provider: projects/843741030650/locations/global/workloadIdentityPools/securesystemslib-tests/providers/securesystemslib-tests
+          service_account: [email protected]
+
+      - run: tox -e kms

mypy.ini

@@ -9,3 +9,7 @@ files =
 # Supress error messages until enough modules
 # are type annotated
 follow_imports = silent
+
+# let's not install typeshed annotations for GCPSigner
+[mypy-google.*]
+ignore_missing_imports = True

pyproject.toml

@@ -44,6 +44,7 @@ Issues = "https://github.com/secure-systems-lab/securesystemslib/issues"
 
 [project.optional-dependencies]
 crypto = ["cryptography>=37.0.0"]
+gcpkms = ["google-cloud-kms"]
 pynacl = ["pynacl>1.2.0"]
 PySPX = ["PySPX==0.5.0"]
 

requirements-kms.txt

@@ -0,0 +1 @@
+google-cloud-kms

securesystemslib/signer/__init__.py

@@ -4,6 +4,7 @@
 This module provides extensible interfaces for public keys and signers:
 Some implementations are provided by default but more can be added by users.
 """
+from securesystemslib.signer._gcp_signer import GCPSigner
 from securesystemslib.signer._key import KEY_FOR_TYPE_AND_SCHEME, Key, SSlibKey
 from securesystemslib.signer._signature import GPGSignature, Signature
 from securesystemslib.signer._signer import (
@@ -19,6 +20,7 @@
     {
         SSlibSigner.ENVVAR_URI_SCHEME: SSlibSigner,
         SSlibSigner.FILE_URI_SCHEME: SSlibSigner,
+        GCPSigner.SCHEME: GCPSigner,
     }
 )
 

securesystemslib/signer/_gcp_signer.py

@@ -0,0 +1,126 @@
+"""Signer interface and example interface implementations.
+
+The goal of this module is to provide a signing interface supporting multiple
+signing implementations and a couple of example implementations.
+
+"""
+
+import logging
+from typing import Optional
+from urllib import parse
+
+import securesystemslib.hash as sslib_hash
+from securesystemslib import exceptions
+from securesystemslib.signer._key import Key
+from securesystemslib.signer._signer import SecretsHandler, Signature, Signer
+
+logger = logging.getLogger(__name__)
+
+GCP_IMPORT_ERROR = None
+try:
+    from google.cloud import kms
+except ImportError:
+    GCP_IMPORT_ERROR = (
+        "google-cloud-kms library required to sign with Google Cloud keys."
+    )
+
+
+class GCPSigner(Signer):
+    """Google Cloud KMS Signer
+
+    This Signer uses Google Cloud KMS to sign: the payload is hashed locally,
+    but the signature is created on the KMS.
+
+    The signer uses "ambient" credentials: typically environment var
+    GOOGLE_APPLICATION_CREDENTIALS that points to a file with valid
+    credentials. These will be found by google.cloud.kms, see
+    https://cloud.google.com/docs/authentication/getting-started
+    (and https://github.com/google-github-actions/auth for the relevant
+    GitHub action).
+
+    Arguments:
+        gcp_keyid: Fully qualified GCP KMS key name, like
+            projects/python-tuf-kms/locations/global/keyRings/securesystemslib-tests/cryptoKeys/ecdsa-sha2-nistp256/cryptoKeyVersions/1
+        public_key: The related public key instance
+
+    Raises:
+        UnsupportedAlgorithmError: The payload hash algorithm is unsupported.
+        UnsupportedLibraryError: google.cloud.kms was not found
+        Various errors from google.cloud modules: e.g.
+            google.auth.exceptions.DefaultCredentialsError if ambient
+            credentials are not found
+    """
+
+    SCHEME = "gcpkms"
+
+    def __init__(self, gcp_keyid: str, public_key: Key):
+        if GCP_IMPORT_ERROR:
+            raise exceptions.UnsupportedLibraryError(GCP_IMPORT_ERROR)
+
+        self.hash_algorithm = self._get_hash_algorithm(public_key)
+        self.gcp_keyid = gcp_keyid
+        self.public_key = public_key
+        self.client = kms.KeyManagementServiceClient()
+
+    @classmethod
+    def from_priv_key_uri(
+        cls,
+        priv_key_uri: str,
+        public_key: Key,
+        secrets_handler: Optional[SecretsHandler] = None,
+    ) -> "GCPSigner":
+        uri = parse.urlparse(priv_key_uri)
+
+        if uri.scheme != cls.SCHEME:
+            raise ValueError(f"GCPSigner does not support {priv_key_uri}")
+
+        return cls(uri.path, public_key)
+
+    @staticmethod
+    def _get_hash_algorithm(public_key: Key) -> str:
+        """Helper function to return payload hash algorithm used for this key"""
+
+        # TODO: This could be a public abstract method on Key so that GCPSigner
+        # would not be tied to a specific Key implementation -- not all keys
+        # have a pre hash algorithm though.
+        if public_key.keytype == "rsa":
+            # hash algorithm is encoded as last scheme portion
+            algo = public_key.scheme.split("-")[-1]
+        if public_key.keytype in [
+            "ecdsa",
+            "ecdsa-sha2-nistp256",
+            "ecdsa-sha2-nistp384",
+        ]:
+            # nistp256 uses sha-256, nistp384 uses sha-384
+            bits = public_key.scheme.split("-nistp")[-1]
+            algo = f"sha{bits}"
+
+        # trigger UnsupportedAlgorithm if appropriate
+        _ = sslib_hash.digest(algo)
+        return algo
+
+    def sign(self, payload: bytes) -> Signature:
+        """Signs payload with Google Cloud KMS.
+
+        Arguments:
+            payload: bytes to be signed.
+
+        Raises:
+            Various errors from google.cloud modules.
+
+        Returns:
+            Signature.
+        """
+        # NOTE: request and response can contain CRC32C of the digest/sig:
+        # Verifying could be useful but would require another dependency...
+
+        hasher = sslib_hash.digest(self.hash_algorithm)
+        hasher.update(payload)
+        digest = {self.hash_algorithm: hasher.digest()}
+        request = {"name": self.gcp_keyid, "digest": digest}
+
+        logger.debug("signing request %s", request)
+        response = self.client.asymmetric_sign(request)
+        logger.debug("signing response %s", response)
+
+        return Signature(self.public_key.keyid, response.signature.hex())

tests/check_kms_signers.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+
+"""
+This module confirms that signing using KMS keys works.
+
+The purpose is to do a smoke test, not to exhaustively test every possible
+key and environment combination.
+
+For Google Cloud (GCP), the requirements to successfully test are:
+* Google Cloud authentication details have to be available in the environment
+* The key defined in the test has to be available to the authenticated user
+
+NOTE: the filename is purposefully check_ rather than test_ so that tests are
+only run when explicitly invoked: The tests can only pass on Securesystemslib
+GitHub Action environment because of the above requirements.
+"""
+
+import unittest
+
+from securesystemslib.exceptions import UnverifiedSignatureError
+from securesystemslib.signer import Key, Signer
+
+
+class TestKMSKeys(unittest.TestCase):
+    """Test that KMS keys can be used to sign."""
+
+    def test_gcp(self):
+        """Test that GCP KMS key works for signing
+
+        NOTE: The KMS account is setup to only accept requests from the
+        Securesystemslib GitHub Action environment: test cannot pass elsewhere.
+
+        In case of problems with KMS account, please file an issue and
+        assign @jku.
+        """
+
+        data = "data".encode("utf-8")
+        pubkey = Key.from_dict(
+            "abcd",
+            {
+                "keyid": "abcd",
+                "keytype": "ecdsa",
+                "scheme": "ecdsa-sha2-nistp256",
+                "keyval": {
+                    "public": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/ptvrXYuUc2ZaKssHhtg/IKNbO1X\ncDWlbKqLNpaK62MKdOwDz1qlp5AGHZkTY9tO09iq1F16SvVot1BQ9FJ2dw==\n-----END PUBLIC KEY-----\n"
+                },
+            },
+        )
+        gcp_id = "projects/python-tuf-kms/locations/global/keyRings/securesystemslib-tests/cryptoKeys/ecdsa-sha2-nistp256/cryptoKeyVersions/1"
+
+        signer = Signer.from_priv_key_uri(f"gcpkms:{gcp_id}", pubkey)
+        sig = signer.sign(data)
+
+        pubkey.verify_signature(sig, data)
+        with self.assertRaises(UnverifiedSignatureError):
+            pubkey.verify_signature(sig, b"NOT DATA")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=1, buffer=True)

tox.ini

@@ -33,6 +33,15 @@ setenv =
 commands =
     python -m tests.check_public_interfaces_gpg
 
+[testenv:kms]
+deps =
+    -r{toxinidir}/requirements-pinned.txt
+    -r{toxinidir}/requirements-kms.txt
+passenv =
+    GOOGLE_APPLICATION_CREDENTIALS
+commands =
+    python -m tests.check_kms_signers
+
 # This checks that importing securesystemslib.gpg.constants doesn't shell out on
 # import.
 [testenv:py311-test-gpg-fails]