action-hsm-sign/README.md

Signs files using an HSM

Basic Usage

      - 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 will be invoked, sending the signature to the sigstore public transparency log.

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:

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 and run some command line tests. Updating the previous example:

      - 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'