Docs: Clarify vault backend key type support (especially tz4/BLS) and add octez-client integration example

[michaelkernaghan]

Summary

Two documentation improvements that could help users setting up Signatory with BLS (tz4) keys and remote signing.

1. Vault backend key type compatibility

The Nitro Enclave docs (/docs/nitro) list tz4/BLS as a supported algorithm in the signatory-cli generate command. However, not all vault backends can perform BLS12-381 signing. In particular, AWS KMS does not natively support BLS12-381 signing operations, so Signatory's AWS KMS backend cannot sign tz4 keys (as currently implemented).

I couldn't find documentation clarifying which vault backends support which key types. A user seeing tz4 listed under generate might reasonably assume it works with any backend.

Suggestion: Add a compatibility note (or matrix) clarifying backend-specific key type support. For example:

Backend	tz1 (Ed25519)	tz2 (secp256k1)	tz3 (P-256)	tz4 (BLS)
AWS KMS	Supported	Supported	Supported	Not supported
File-based	Supported	Supported	Supported	Supported (verified)
HashiCorp Vault	Needs confirmation	Needs confirmation	Needs confirmation	Needs confirmation
Azure KMS	Needs confirmation	Needs confirmation	Needs confirmation	Needs confirmation
GCP KMS	Needs confirmation	Needs confirmation	Needs confirmation	Needs confirmation
YubiHSM	Needs confirmation	Needs confirmation	Needs confirmation	Needs confirmation
PKCS#11	Needs confirmation	Needs confirmation	Needs confirmation	Needs confirmation

This could live on a vault backends overview page, with a brief note on each individual backend page as well.

Note: Nitro Enclave is a deployment environment, not a vault backend -- key type support inside an enclave depends on the chosen vault backend (file-based, KMS, etc.).

What we observed

When tz4 keys were configured to sign through a Signatory instance using the AWS KMS backend, signing operations failed. Unfortunately we have since removed the broken key entries from our wallet and cannot reproduce the exact error output. The configuration that failed used the http:// remote signer protocol in octez-client pointing to a KMS-backed Signatory.

The working solution was to deploy a separate Signatory instance using a file-based vault for the tz4 key, while continuing to use the AWS KMS backend for our tz2 delegate key.

• Signatory version: v1.3.1
• Baker: octez-baker on TallinnNet

Working configuration (file-based vault for tz4)

Signatory config.yml:

server:
  address: :6733
  utility_address: :9584

vaults:
  local_file:
    driver: file
    config:
      file: /etc/signatory/secret.json

tezos:
  tz4Gu6wNaVJhnHB5GiNPTyfb44CmJkpWJYD3:
    allowed_operations:
      - block
      - endorsement
      - preendorsement
    allowed_kinds:
      - transaction
      - reveal
      - delegation
      - stake

2. octez-client integration example for remote Signatory

The docs cover Signatory server configuration but don't show the baker-side setup. An end-to-end example would help users complete the connection.

On our working deployment, the octez-client key import uses:

octez-client import secret key <alias> http://<signatory-host>:<port>/<tz_address>

For example, with a BLS companion key served by Signatory on localhost:6733:

octez-client import secret key my_bls_key http://localhost:6733/tz4Gu6wNaVJhnHB5GiNPTyfb44CmJkpWJYD3

A brief section in the docs showing both a minimal Signatory config stanza and the corresponding octez-client import secret key command would reduce guesswork for new users.

Context

Discovered during deployment of a BLS companion key (tz4) for TallinnNet baking with Signatory v1.3.1. Initial attempt routed the tz4 key through an AWS KMS-backed Signatory, which could not perform BLS signing. Successful deployment used a file-based vault on a Nitro-capable VM.

[lthms]

Hello. FYI, tz1 on a software kms is not supported by signatory as far as i can tell

AsymmetricSign: rpc error: code = InvalidArgument desc = For algorithm EC_SIGN_ED25519 and protection level SOFTWARE, digest must not be set."