# Contributions

Please use the [GitHub issue tracker](https://github.com/ecadlabs/signatory/issues) to report bugs or request features.

To contribute, please check the issue tracker to see if an existing issue exists for your planned contribution. If there's no issue, please create one first, and then submit a pull request with your contribution.

For a contribution to be merged, it is required to have complete documentation, come with unit tests, and integration tests where appropriate. Submitting a "work in progress" pull request for review/feedback is always welcome!

## Adding support for a new Vault

### Vault documentation

For a new Vault provider to be supported and included in Signatory, documentation must cover the following outline.

- Introduction
- Describe the vault provider and it's trade-offs.
- Vault provider setup hints (goal is to not write a tutorial for someone elses product)
- Key managment
- Generating key in Vault (is supported)
- Key import ceremony, or explicit warning if key import is not supported!
- Signatory setup process specific to new vault
- signatory-cli features specific to new vault
- tezos-client setup (should be generic!)
- Verify functioning signatory with test curl command

---

## Alex Trial version for YubiHSM:

Note on convention: Anything surrounded by curly brackets is a piece of info that will be specific to you. For example {tezos_public_key_hash} will be something on your system resembling `tz1P572ijpP...`

### Introduction to YubiHSM2:

They will likely describe their own products far better than we ever could. Some resources on the HSM are available here:

- [HSM website](https://www.yubico.com/products/hardware-security-module/) (make sure to check out the product brief on this page)
- [Developers Overview](https://developers.yubico.com/YubiHSM2/Product_Overview/)
- [HSM Series Support Page](https://www.yubico.com/ca/setup/yubikey-5-series/)

#### Trade-offs of using YubiHSM:
To be completed later

### Vault Setup Hints
This is the guide that was used to set up the HSM initially and gather the required tool to interface with different hosts:
(This should get the HSM connected to your host and able to receive commands)
- [Quick Start](https://developers.yubico.com/YubiHSM2/Usage_Guides/YubiHSM_quick_start_tutorial.html)
- You will need to complete up to and including the section titled "Adding a New Authentication Key". This will make sure your environment is set up to allow asymmetric key generation
- One part of this is possibly defining a udev rule for allowing your user to access the yubiHSM since running things as root isn't generally advised. This [link](https://developers.yubico.com/YubiHSM2/Component_Reference/yubihsm-connector/) is helpful for setting up udev rules so your user can run the connector

### Key Management
- You will need to complete the section titled "Generate a Key for Signing". This will create the keys that the HSM will use for signing. A single key is generally enough to get what you need done and if you need more, they can be added in the future.

### Signatory Setup for most cases (no different setup needed for Yubi at this time)
I don't believe there is anything additional needed for signatory when using a YubiHSM. The standard should work:
- Clone [repo](https://github.com/ecadlabs/signatory)
- Make sure Go is installed (version must be greater than 1.12(I think))
- Navigate to the cloned signatory repo
- `make signatory`
- `make signatory-cli`

#### What you need for YubiHSM in a signatory configuration YAML file
The following is needed in a config file for signatory to know what it is looking for on a yubiHSM

# The vaults section is what defines the connection to the yubiHSM
vaults:
# Name is used to identify backend
  yubi:
    driver: yubihsm
    config:
      address: localhost:12345 # Address for the yubihsm-connector
      password: {password_you_set_when_creating_authentication_key}
      auth_key_id: 1 # This is the ID of the authentication key you created for the YubiHSM

# This section is for public key hashes to define what is activated IRL
tezos:
  # Default policy allows "block" and "endorsement" operations
  {tezos_public_key_hash}:
  #tz1RKhyJmze24D3EerrGpCZG6P572ijpPUc3(for example):
    log_payloads: true
    allowed_operations:
    # List of [generic, block, endorsement]
    - generic
    - block
    - endorsement

### Signatory-cli features for YubiHSM
Once you have signatory binaries and the YubiHSM set up it is time to test the connection between the hardware and signatory. After completing the setup for the HSM and signatory we can test it by using the signatory-cli command `list`. Here is an example:

alexander@debian:~/signatory$ ./signatory-cli list --help
List public keys

Usage:
  signatory-cli list [flags]

Flags:
  -h, --help   help for list

Global Flags:
  -c, --config string   Config file path (default "/etc/signatory.yaml")
      --log string      Log level: [error, warn, info, debug, trace] (default "info")
      
alexander@debian:~/signatory$ ./signatory-cli list -c signatory.yaml 
INFO[0000] Initializing vault                            vault=yubihsm vault_name=yubi
Public Key Hash:    tz1RKhyJmze24D3EerrGpCZG6P572ijpPUc3
Vault:              YubiHSM
ID:                 bf5d
Active:             true
Allowed Operations: [block endorsement generic]
Allowed Kinds:      []

### Tezos Client Setup
Adding the information generated in any vault to the tezos-client is done in a single command, it is as follows:

`tezos-client import secret key {name_you_choose} http://localhost:6732/{your_public_key_hash}`

Using the same pkh as above the command would look like:

`tezos-client import secret key yubi_guide http://localhost:6732/tz1RKhyJmze24D3EerrGpCZG6P572ijpPUc3`

This should produce the output: `Tezos address added: tz1RKhyJmze24D3EerrGpCZG6P572ijpPUc3`

### Final Signatory Verification Test
We can finally see that all the pieces are working together by curling the signatory service and asking for the public key associated with our active public key hash:
`curl http://localhost:6732/keys/tz1RKhyJmze24D3EerrGpCZG6P572ijpPUc3`

The output can be verified by checking the public_keys file in the .tezos-client directory