signer: add HSMSigner and HSMKey

Adds basic Signer and Key implementations to generate signatures on
a hardware security module (HSMSigner) and to export the corresponding
public key (HSMKey).

Supported keys are ecdsa on SECG curves secp256r1 (NIST P-256) or
secp384r1 (NIST P-384), which correspond to securesystemslib
signing schemes "ecdsa-sha2-nistp256" and "ecdsa-sha2-nistp384".

Tests are performed on SoftHSM (virtual hsm).

**Caveat**
HSMSigner and HSMKey use the token from a passed PyKCS11 session.
This means that users must identify the correct slot, token and key,
open a session, optionally log in (for signing), and also log out
and close the session afterwards.

This is not user-friendly. Ideally, the user only identifies the
correct slot, token and key out-of-band (e.g. with pkcs11-tool,
yubico-piv-tool or ykman) and then passes a stable identifier to
HSMSigner. Maybe labels? Slot id is not stable.

**Other ideas**
- HSMKey is an SSlibKey with an *import key from HSM* method.
  The method could be moved to different import API (see secure-systems-lab#466),
  and HSMKey could be removed.
- HSMSigner could live in a dedicated _hsm_signer.py, this would
  better hide the conditional imports.

Signed-off-by: Lukas Puehringer <[email protected]>

.github/workflows/hsm.yml

@@ -0,0 +1,59 @@
+name: Run Securesystemslib HSM tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout securesystemslib
+        uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: "requirements*.txt"
+
+      - name:  Install system dependencies
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" == "Linux" ]; then
+            sudo apt-get install -y softhsm2
+            echo "PYKCS11LIB=/usr/lib/softhsm/libsofthsm2.so" >> $GITHUB_ENV
+
+          elif [ "$RUNNER_OS" == "macOS" ]; then
+            brew install softhsm
+            echo "PYKCS11LIB=$(brew --prefix softhsm)/lib/softhsm/libsofthsm2.so" >> $GITHUB_ENV
+
+          elif [ "$RUNNER_OS" == "Windows" ]; then
+            choco install softhsm.install
+            echo "PYKCS11LIB=C:\SoftHSM2\lib\softhsm2-x64.dll" >> $GITHUB_ENV
+
+          else
+              echo "$RUNNER_OS not supported"
+              exit 1
+          fi
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade tox
+
+      - name: Run tox
+        run: tox -e hsm

mypy.ini

@@ -12,4 +12,11 @@ follow_imports = silent
 
 # let's not install typeshed annotations for GCPSigner
 [mypy-google.*]
-ignore_missing_imports = True
+ignore_missing_imports = True
+
+# Suppress error messages for non-annotating dependencies
+[mypy-PyKCS11.*]
+ignore_missing_imports = True
+
+[mypy-asn1crypto.*]
+ignore_missing_imports = True

pylintrc

@@ -51,3 +51,4 @@ check-quote-consistency=yes
 
 [TYPECHECK]
 generated-members=shake_128s.*
+ignored-modules=PyKCS11

pyproject.toml

@@ -47,6 +47,7 @@ crypto = ["cryptography>=37.0.0"]
 gcpkms = ["google-cloud-kms"]
 pynacl = ["pynacl>1.2.0"]
 PySPX = ["PySPX==0.5.0"]
+hsm = ["asn1crypto", "cryptography", "PyKCS11"]
 
 [tool.setuptools]
 include-package-data = true

requirements-hsm-pinned.txt

@@ -0,0 +1,16 @@
+#
+# This file is autogenerated by pip-compile with python 3.8
+# To update, run:
+#
+#    pip-compile --output-file=requirements-hsm-pinned.txt requirements-hsm.txt
+#
+asn1crypto==1.5.1
+    # via -r requirements-hsm.txt
+cffi==1.15.1
+    # via cryptography
+cryptography==38.0.4
+    # via -r requirements-hsm.txt
+pycparser==2.21
+    # via cffi
+pykcs11==1.5.11
+    # via -r requirements-hsm.txt

requirements-hsm.txt

@@ -0,0 +1,3 @@
+asn1crypto
+cryptography
+PyKCS11

securesystemslib/signer/__init__.py

@@ -5,11 +5,17 @@
 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._key import (
+    KEY_FOR_TYPE_AND_SCHEME,
+    HSMKey,
+    Key,
+    SSlibKey,
+)
 from securesystemslib.signer._signature import GPGSignature, Signature
 from securesystemslib.signer._signer import (
     SIGNER_FOR_URI_SCHEME,
     GPGSigner,
+    HSMSigner,
     SecretsHandler,
     Signer,
     SSlibSigner,

securesystemslib/signer/_key.py

@@ -4,9 +4,39 @@
 from typing import Any, Dict, Optional, Tuple, Type
 
 import securesystemslib.keys as sslib_keys
-from securesystemslib import exceptions
+from securesystemslib import KEY_TYPE_ECDSA, exceptions
 from securesystemslib.signer._signature import Signature
 
+# pylint: disable=wrong-import-position
+CRYPTO_IMPORT_ERROR = None
+try:
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.ec import (
+        SECP256R1,
+        SECP384R1,
+        EllipticCurvePublicKey,
+        ObjectIdentifier,
+        get_curve_for_oid,
+    )
+
+except ImportError:  # pragma: no cover
+    CRYPTO_IMPORT_ERROR = "'cryptography' required"
+
+PYKCS11_IMPORT_ERROR = None
+try:
+    from PyKCS11 import PyKCS11
+
+except ImportError:  # pragma: no cover
+    PYKCS11_IMPORT_ERROR = "'PyKCS11' required"
+
+ASN1CRYPTO_IMPORT_ERROR = None
+try:
+    from asn1crypto.keys import ECDomainParameters, ECPoint
+
+except ImportError:  # pragma: no cover
+    ASN1CRYPTO_IMPORT_ERROR = "'asn1crypto' required"
+# pylint: enable=wrong-import-position
+
 logger = logging.getLogger(__name__)
 
 # NOTE Key dispatch table is defined here so it's usable by Key,
@@ -180,3 +210,91 @@ def verify_signature(self, signature: Signature, data: bytes) -> None:
             raise exceptions.VerificationError(
                 f"Unknown failure to verify signature by {self.keyid}"
             ) from e
+
+
+class HSMKey(SSlibKey):
+    """Hardware Security Module (HSM) Key
+
+    HSMKey is a regular SSlibKey with an additional `from_hsm` method to
+    export public keys from hardware security modules.
+    """
+
+    @classmethod
+    def from_hsm(
+        cls,
+        hsm_session: "PyKCS11.Session",
+        hsm_keyid: Tuple[int, ...],
+        keyid: str,
+    ):
+        """Export public key from HSM
+
+        Supports ecdsa on SECG curves secp256r1 (NIST P-256) or secp384r1 (NIST P-384).
+
+        Arguments:
+            hsm_session: An open ``PyKCS11.Session`` to the token with the public key.
+            hsm_keyid: Key identifier on the token.
+            keyid: Key identifier that is unique within the metadata it is used in.
+
+        Raises:
+            ValueError: No compatible key for ``hsm_keyid`` found on HSM.
+            PyKCS11.PyKCS11Error: Various HSM communication errors.
+
+        """
+        if CRYPTO_IMPORT_ERROR:
+            raise exceptions.UnsupportedLibraryError(CRYPTO_IMPORT_ERROR)
+
+        if PYKCS11_IMPORT_ERROR:
+            raise exceptions.UnsupportedLibraryError(PYKCS11_IMPORT_ERROR)
+
+        # Search for ecdsa public keys with passed keyid on HSM
+        keys = hsm_session.findObjects(
+            [
+                (PyKCS11.CKA_CLASS, PyKCS11.CKO_PUBLIC_KEY),
+                (PyKCS11.CKA_KEY_TYPE, PyKCS11.CKK_ECDSA),
+                (PyKCS11.CKA_ID, hsm_keyid),
+            ]
+        )
+
+        if len(keys) != 1:
+            raise ValueError(
+                f"hsm_keyid must identify one {KEY_TYPE_ECDSA} key, found {len(keys)}"
+            )
+
+        # Extract public key domain parameters and point from HSM
+        hsm_params, hsm_point = hsm_session.getAttributeValue(
+            keys[0], [PyKCS11.CKA_EC_PARAMS, PyKCS11.CKA_EC_POINT]
+        )
+
+        params = ECDomainParameters.load(bytes(hsm_params))
+
+        # TODO: Define as module level constant and don't hardcode scheme strings
+        scheme_for_curve = {
+            SECP256R1: "ecdsa-sha2-nistp256",
+            SECP384R1: "ecdsa-sha2-nistp384",
+        }
+        curve_names = [curve.name for curve in scheme_for_curve]
+
+        if params.chosen.native not in curve_names:
+            raise ValueError(
+                f"found key on {params.chosen.native}, should be on one of {curve_names}"
+            )
+
+        # Create PEM from key
+        curve = get_curve_for_oid(ObjectIdentifier(params.chosen.dotted))
+        public_pem = (
+            EllipticCurvePublicKey.from_encoded_point(
+                curve(), ECPoint().load(bytes(hsm_point)).native
+            )
+            .public_bytes(
+                serialization.Encoding.PEM,
+                serialization.PublicFormat.SubjectPublicKeyInfo,
+            )
+            .decode()
+        )
+
+        return HSMKey(
+            keyid,
+            KEY_TYPE_ECDSA,
+            scheme_for_curve[curve],
+            {"public": public_pem},
+        )

securesystemslib/signer/_signer.py

@@ -1,13 +1,33 @@
 """Signer interface and the default implementations"""
 
+import binascii
 import logging
 import os
 from abc import ABCMeta, abstractmethod
-from typing import Callable, Dict, Optional, Type
+from typing import Callable, Dict, Optional, Tuple, Type
 from urllib import parse
 
+# pylint: disable=wrong-import-position
+CRYPTO_IMPORT_ERROR = None
+try:
+    from cryptography.hazmat.primitives.asymmetric.utils import (
+        encode_dss_signature,
+    )
+except ImportError:  # pragma: no cover
+    CRYPTO_IMPORT_ERROR = "'cryptography' required"
+
+PYKCS11_IMPORT_ERROR = None
+try:
+    from PyKCS11 import PyKCS11
+
+except ImportError:  # pragma: no cover
+    PYKCS11_IMPORT_ERROR = "'PyKCS11' required"
+# pylint: enable=wrong-import-position
+
 import securesystemslib.gpg.functions as gpg
 import securesystemslib.keys as sslib_keys
+from securesystemslib import KEY_TYPE_ECDSA
+from securesystemslib.exceptions import UnsupportedLibraryError
 from securesystemslib.signer._key import Key, SSlibKey
 from securesystemslib.signer._signature import GPGSignature, Signature
 
@@ -271,3 +291,100 @@ def sign(self, payload: bytes) -> GPGSignature:
 
         sig_dict = gpg.create_signature(payload, self.keyid, self.homedir)
         return GPGSignature(**sig_dict)
+
+
+class HSMSigner(Signer):
+    """Hardware Security Module (HSM) Signer.
+
+    HSMSigner uses the PKCS#11/Cryptoki API to sign on an HSM (e.g. YubiKey). It
+    supports ecdsa on SECG curves secp256r1 (NIST P-256) or secp384r1 (NIST P-384).
+
+    Arguments:
+        hsm_session: An open and logged-in ``PyKCS11.Session`` to the token with the
+                private key.
+        hsm_keyid: Key identifier on the token.
+        public_key: The related public key instance.
+
+    Raises:
+        UnsupportedLibraryError: ``PyKCS11`` and ``cryptography`` libraries not found.
+        ValueError: ``public_key.scheme`` not supported.
+    """
+
+    def __init__(
+        self,
+        hsm_session: "PyKCS11.Session",
+        hsm_keyid: Tuple[int, ...],
+        public_key: Key,
+    ):
+        if CRYPTO_IMPORT_ERROR:
+            raise UnsupportedLibraryError(CRYPTO_IMPORT_ERROR)
+
+        if PYKCS11_IMPORT_ERROR:
+            raise UnsupportedLibraryError(PYKCS11_IMPORT_ERROR)
+
+        # TODO: Define as module level constant and don't hardcode scheme strings
+        supported_schemes = {
+            "ecdsa-sha2-nistp256": PyKCS11.Mechanism(PyKCS11.CKM_ECDSA_SHA256),
+            "ecdsa-sha2-nistp384": PyKCS11.Mechanism(PyKCS11.CKM_ECDSA_SHA384),
+        }
+
+        if public_key.scheme not in supported_schemes:
+            raise ValueError(f"unsupported scheme {public_key.scheme}")
+
+        self._mechanism = supported_schemes[public_key.scheme]
+        self.hsm_session = hsm_session
+        self.hsm_keyid = hsm_keyid
+        self.public_key = public_key
+
+    @classmethod
+    def from_priv_key_uri(
+        cls,
+        priv_key_uri: str,
+        public_key: Key,
+        secrets_handler: Optional[SecretsHandler] = None,
+    ) -> "HSMSigner":
+        raise NotImplementedError("Incompatible with private key URIs")
+
+    def sign(self, payload: bytes) -> Signature:
+        """Signs payload with Hardware Security Module (HSM).
+
+        Arguments:
+            payload: bytes to be signed.
+
+        Raises:
+            ValueError: No compatible key for ``hsm_keyid`` found on HSM.
+            PyKCS11.PyKCS11Error: Various HSM communication errors.
+
+        Returns:
+            Signature.
+        """
+
+        # Search for ecdsa public keys with passed keyid on HSM
+        keys = self.hsm_session.findObjects(
+            [
+                (PyKCS11.CKA_CLASS, PyKCS11.CKO_PRIVATE_KEY),
+                (PyKCS11.CKA_KEY_TYPE, PyKCS11.CKK_ECDSA),
+                (PyKCS11.CKA_ID, self.hsm_keyid),
+            ]
+        )
+        if len(keys) != 1:
+            raise ValueError(
+                f"hsm_keyid must identify one {KEY_TYPE_ECDSA} key, found {len(keys)}"
+            )
+
+        signature = self.hsm_session.sign(keys[0], payload, self._mechanism)
+
+        # The PKCS11 signature octets correspond to the concatenation of the ECDSA
+        # values r and s, both represented as an octet string of equal length of at
+        # most nLen with the most significant byte first (i.e. big endian)
+        # https://docs.oasis-open.org/pkcs11/pkcs11-curr/v3.0/cs01/pkcs11-curr-v3.0-cs01.html#_Toc30061178
+        r_s_len = int(len(signature) / 2)
+        r = int.from_bytes(signature[:r_s_len], byteorder="big")
+        s = int.from_bytes(signature[r_s_len:], byteorder="big")
+
+        # Create an ASN.1 encoded Dss-Sig-Value to be used with pyca/cryptography
+        dss_sig_value = binascii.hexlify(encode_dss_signature(r, s)).decode(
+            "ascii"
+        )
+
+        return Signature(self.public_key.keyid, dss_sig_value)