Signs files using an HSM
========================

Basic Usage
-----------

```yaml
      - name: Sign
        id: sign
        uses: https://git.lerch.org/lobo/action-hsm-sign@v1
        with:
          pin: ${{ secrets.HSM_USER_PIN }}
          files: ???
          public_key: 'https://emil.lerch.org/serverpublic.pem'
```

If a public key is specified, [rekor](https://github.com/sigstore/rekor) will
be invoked, sending the signature to the [sigstore public transparency
log](https://sigstore.dev).

The action provides the following outputs:

* Source: Source file used for the signature
* Signature: Signature
* URL: If a public key is specified, the URL output provides the sigstore log url

Because multiple files can be signed, these outputs have numerical suffixes.
In the above example, the output `${{ steps.sign.outputs.URL_1 }}` would be the
url for the first file signed with this action

Usage with Smart USB Hubs
-------------------------

Many consumer HSMs will "hang" after prolonged usage. To alleviate problems
associated with this, this action can integrate with smart USB hubs to turn
on the hub's port and wait for the OS to recognize the attached HSM before
performing the signing action.

**NOTE: The action will turn off the port on the USB hub when it is done processing**

To enable this feature, set `uhub_control` to `true`. As this is controlling
physical hardware, you will also need a runner set with a max concurrency of 1
and a unique label, used as the `runs-on` attribute of the build. For example:

```yaml
name: Sign

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest-with-hsm
```

The runner will also need to set environment variables `UHUB_PORT` and
`UHUB_LOCATION` as appropriate. To determine the proper values for these, it is
best to consult [uhubctl
documentation](https://github.com/mvp/uhubctl?tab=readme-ov-file#usage) and run
some command line tests. Updating the previous example:

```yaml
      - name: Sign
        id: sign
        uses: https://git.lerch.org/lobo/action-hsm-sign@v1
        with:
          pin: ${{ secrets.HSM_USER_PIN }}
          files: ???
          public_key: 'https://emil.lerch.org/serverpublic.pem'
          uhub_control: 'true'
```