diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index c13e301d..00000000 --- a/docs/README.md +++ /dev/null @@ -1,215 +0,0 @@ -# Signatory - -## Configuration - -Signatory configuration is specified in a YAML file. Use the `signatory.yaml` file as a template to get started. - -You can configure multiple `vault`s. Each `vault` should be configured to use a backend. Same backend can be used in more than one `vault`. - -The configuration file is shared between `signatory` and `signatory-cli`. - -### Configuration example - -```yaml -server: - # Address for the main HTTP server to listen on - address: :6732 - # Address for the utility HTTP server (for Prometheus metrics) to listen on - utility_address: :9583 - # List of authorized public keys. Sign operation must be authenticated if present - # Nested lists are allowed - authorized_keys: - - &authorized_key edpktpQKJF4vRodmSfT3h6LrYisshQuJeoybUxB9c8s3b1QymvisHC - - &authorized_keys_list - - edpkubVAm7SttSV2WigeSoB7fAnr612PJo9DnhCgQyXakjaMeweN1D - - &picked_key edpkuNVUYqMD61DyQ7N378nGCjCnQ3h2BiEsfeeY64kwKVJAJ4C9sY - -vaults: - # Name is used to identify backend during import process - kms: - driver: cloudkms - config: - # See backend specific documentation - project: signatory - location: europe-north1 - key_ring: hsm-ring - azure: - driver: azure - config: - # See backend specific documentation - vault: https://signatory.vault.azure.net/ - tenant_id: cf5dd0ba-d3a3-4f3f-a688-06d12672f8ed - client_id: 5d29a974-edd0-4659-b933-7d9c56726649 - client_pkcs12_certificate: principal.pfx - yubi: - driver: yubihsm - config: - # See backend specific documentation - address: localhost:12345 - password: password - auth_key_id: 1 - -# List enabled public keys hashes here -tezos: - # Default policy allows "block" and "endorsement" operations - tz1Wz4ZabKRsz842Xuzy4a7CcWADfPVsPKus: - # Explicit policy - tz3MhmeqpudUqEX8PYTbNDF3CVcnnjNQoo8N: - # Setting `log_payloads` to `true` will cause Signatory to log operation - # payloads to `stdout`. This may be desirable for audit and investigative - # purposes. - log_payloads: true - allowed_operations: - # List of [generic, block, endorsement, preendorsement] - - generic - - block - - endorsement - allowed_kinds: - # List of [endorsement, ballot, reveal, transaction, origination, delegation, seed_nonce_revelation, activate_account] - - transaction - - endorsement - authorized_keys: - # Allow sign operation only for clients specified below. Same syntax as `server/authorized_key` - - *authorized_key -``` - -## Backends -* [AWS](aws_kms.md) -* [Google Cloud KMS](gcp_kms.md) -* [Azure](azure_kms.md) -* [YubiHSM2](yubihsm.md) - ---- - -## Signatory service - -Signatory service is used for signing operations and implements Tezos specific HTTP external signer API - -``` -A Tezos Remote Signer for signing block-chain operations with private keys - -Usage: - signatory [flags] - signatory [command] - -Available Commands: - help Help about any command - serve Run a server - -Flags: - -c, --config string Config file path (default "signatory.yaml") - -h, --help help for signatory - --log string Log level: [error, warn, info, debug, trace] (default "info") -``` - -### Prometheus metrics and health service - -Signatory exposes Prometheus metrics and health status on the address specified in `utility_address` configuration parameter. The default value is `:9583`. - -#### Prometheus metrics - -Metrics include counters and histograms that track signing operations and errors. - -The metrics are intended to be scraped using the Prometheus time series database. We also publish a ready-made Grafana dashboard that users can use to visualize the operation of their signing operations. (TODO: publish Grafana dashboard) - -`localhost:9583/metrics` - -#### Health service - -The health service endpoint can be used to test if the service is running correctly and is ready to sign requests. - -This endpoint is useful for monitoring, or declarative tests as part of deployment playbooks or Kubernetes manifests. - -`localhost:9583/healthz` - -### Testing - -To test the signing operation, you can send a post to Signatory. In this example, we are sending a dummy operation of type `02`, which is an `endorsement` operation type. - -```sh -curl -XPOST \ - -d '"027a06a770e6cebe5b3e39483a13ac35f998d650e8b864696e31520922c7242b88c8d2ac55000003eb6d"' \ - localhost:8003/keys/tz3Tm6UTWmPAZJaNSPAQNiMiyFSHnRXrkcHj -``` - -If you receive an error from curl and on the signatory console, you will have to investigate. If it was successful, you should see output similar to: - -```json -{"signature":"p2sigR4JTRTMkT4XC4NgVuGdhZDbgaaSZpNPUserkyMCTY1GQJTFpCuihFRVk9n7YaNjA5U3cNcvJPRm7C9G5A1hsLsesVPcMu"} -``` - ---- - -## Signatory command line tool - -Signatory service is used for importing of private keys and obtaining information about available key pairs and their policies. - -``` -A Tezos Remote Signer for signing block-chain operations with private keys - -Usage: - signatory-cli import [flags] - -Flags: - -h, --help help for import - -o, --opt string Options to be passed to the backend. Syntax: key:val[,...] - --password string Password for private key(s) - --vault string Vault name for importing - -Global Flags: - -c, --config string Config file path (default "signatory.yaml") - --log string Log level: [error, warn, info, debug, trace] (default "info") -``` - -### Import a private key - -```sh -signatory-cli -c CONFIG import --vault VAULT PRIVATE_KEY -``` - -Example: - -```sh -signatory-cli -c signatory.yaml import --vault yubi edsk3rsARzj7f8PEHXXUbLigMDCww75nPnzbFmSz19TLwzrYzF8uCB -``` - -### List keys - -```sh -signatory-cli -c CONFIG list -``` - -Example: - -```sh -signatory-cli -c signatory.yaml list -``` - -Example output: - -``` -INFO[0000] Initializing vault vault=cloudkms vault_name=kms -INFO[0000] Initializing vault vault=azure vault_name=azure -Public Key Hash: tz3VfoCwiQyMNYnaseFLFAjN9AQJQnhvddjG -Vault: CloudKMS -ID: projects/signatory-testing/locations/europe-north1/keyRings/hsm-ring/cryptoKeys/hsm-key/cryptoKeyVersions/1 -Allowed Operations: [block endorsement] -Allowed Kinds: [] - -Public Key Hash: tz3ZqyLdKy2doLbw7yghLPz2TWWZdxeLGKVx -Vault: CloudKMS -ID: projects/signatory-testing/locations/europe-north1/keyRings/hsm-ring/cryptoKeys/hsm-key/cryptoKeyVersions/2 -*DISABLED* - -Public Key Hash: tz3aTwpna6m9qsw4YZVFad1nsm5cGgWHVQ8R -Vault: CloudKMS -ID: projects/signatory-testing/locations/europe-north1/keyRings/hsm-ring/cryptoKeys/signatory-imported-1RG8mJUH8P5ncMEMypfkno98Gpq/cryptoKeyVersions/1 -Allowed Operations: [block endorsement generic] -Allowed Kinds: [endorsement transaction] - -Public Key Hash: tz3VkMSRVjLwEoUgZNJwjoD6YHeBDXyWiBaY -Vault: Azure -ID: https://signatory.vault.azure.net/keys/key0/fa9607734e58485181d19da901e725b9 -*DISABLED* - -``` diff --git a/docs/aws_kms.md b/docs/aws_kms.md index 48870bf7..0ed88b84 100644 --- a/docs/aws_kms.md +++ b/docs/aws_kms.md @@ -14,14 +14,15 @@ Search for IAM and create a user with "Programmatic access" for Signatory to acc Below are the minimum configuration required. -```sh -awskms: +```yaml +vaults: + aws: driver: awskms config: - user_name: sigy-tsty - access_key_id: AKIATXBC6RIH4YZT5U6B - secret_access_key: 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 - region: us-west-2 + user_name: + access_key_id: + secret_access_key: + region: ``` ### Configuration parameters diff --git a/docs/azure_kms.md b/docs/azure_kms.md index c62aa889..b160612d 100644 --- a/docs/azure_kms.md +++ b/docs/azure_kms.md @@ -289,6 +289,10 @@ Allowed Kinds: [endorsement transaction] **Update signatory.yaml config with PKH:** ```yaml +server: + address: :6732 + utility_address: :9583 + vaults: azure: driver: azure @@ -304,12 +308,11 @@ vaults: tezos: tz3d6nYmR1LmSDsgJ463Kgd8EbH53pYnuv8S: log_payloads: true - allowed_operations: - # List of [generic, block, endorsement] - - generic - - block - - endorsement - allowed_kinds: - # List of [endorsement, ballot, reveal, transaction, origination, delegation, seed_nonce_revelation, activate_account] - - transaction - - endorsement + allow: + block: + endorsement: + preendorsement: + generic: + - transaction + - reveal + - delegation diff --git a/docs/cli.md b/docs/cli.md index 140ff55b..cd394fff 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -94,19 +94,15 @@ vaults: tezos: tz2***: log_payloads: true - allowed_operations: - # List of [generic, block, endorsement] - - generic - - block - - endorsement - allowed_kinds: - # List of [endorsement, ballot, reveal, transaction, origination, delegation, seed_nonce_revelation, activate_account] - - transaction - - endorsement + allow: + block: + endorsement: + preendorsement: + generic: + - transaction tz3***: log_payloads: true - allowed_operations: - - generic - allowed_kinds: - - transaction + allow: + generic: + - transaction ``` diff --git a/docs/gcp_kms.md b/docs/gcp_kms.md index a6425ff1..65028aed 100644 --- a/docs/gcp_kms.md +++ b/docs/gcp_kms.md @@ -77,37 +77,28 @@ Status: FOUND_NOT_CONFIGURED **Update signatory.yaml config with PKH:** -```sh -signatory % cat /etc/s.yaml +```yaml server: - # Address/Port that Signatory listens on address: :6732 - # Address/Port that Signatory serves prometheus metrics on utility_address: :9583 vaults: - kms: + gcp: driver: cloudkms config: - project: signatory-testing - location: europe-south1 - key_ring: sigy-key + project: + location: + key_ring: + application_credentials: tezos: - # Default policy allows "block" and "endorsement" operations tz3fK7rVYSg2HTEAmUYdfjJWSDGfsKrxH3xQ: - # Setting `log_payloads` to `true` will cause Signatory to log operation - # payloads to `stdout`. This may be desirable for audit and investigative - # purposes. log_payloads: true - allowed_operations: - # List of [generic, block, endorsement] - - generic - - block - - endorsement - allowed_kinds: - # List of [endorsement, ballot, reveal, transaction, origination, delegation, seed_nonce_revelation, activate_account] - - transaction - - endorsement + allow: + block: + endorsement: + preendorsement: + generic: + - transaction ``` ## **Key Import:** diff --git a/docs/ledger.md b/docs/ledger.md index bb722d3e..b7ba6387 100644 --- a/docs/ledger.md +++ b/docs/ledger.md @@ -38,7 +38,6 @@ Examples (equivalent): `bip32-ed25519/m/44'/1729'/0'/0'`, ```yaml vaults: -# Name of vault ledger: driver: ledger config: diff --git a/docs/localsecret.md b/docs/localsecret.md index e766caaf..5a782919 100644 --- a/docs/localsecret.md +++ b/docs/localsecret.md @@ -14,28 +14,24 @@ Place the following YAML in a file named `signatory.yaml` ```yaml server: - # Address/Port that Signatory listens on address: :6732 - # Address/Port that Signatory serves prometheus metrics on utility_address: :9583 vaults: -# Name of vault - local_file_keys: + local_secret: driver: file config: file: /etc/secret.json -# List enabled public keys hashes here tezos: - # Default policy allows "block" and "endorsement" operations tz1Wk1Wdczh5BzyZ1uz2DW9xdFg9B5cFuGFm: log_payloads: true - allowed_operations: - # List of [generic, block, endorsement] - - generic - - block - - endorsement + allow: + block: + endorsement: + preendorsement: + generic: + - transaction ``` The `tz1Wk1Wdczh5BzyZ1uz2DW9xdFg9B5cFuGFm` key corresponds to the secret key that you will put in `/etc/secret.json` @@ -43,9 +39,12 @@ The `tz1Wk1Wdczh5BzyZ1uz2DW9xdFg9B5cFuGFm` key corresponds to the secret key tha Contents of `secret.json` is: ```json -[ { "name": "your_secret_key", - "value": - "unencrypted:edsk3DYwZpPmbNTRSdJW2wBeHoneNqjPt9Xj49Fnhcir6q47JpD5Vz" } ] +[ + { + "name": "", + "value": "unencrypted:" + } +] ``` ### Running Signatory diff --git a/docs/start.md b/docs/start.md index cce2d2f7..93ca70d2 100644 --- a/docs/start.md +++ b/docs/start.md @@ -4,12 +4,17 @@ title: Getting Started sidebar_label: Getting Started --- +[aws]: https://aws.amazon.com/kms/ +[azure]: https://docs.microsoft.com/en-us/azure/key-vault/ +[gcp]: https://cloud.google.com/security-key-management +[yubi]: https://www.yubico.com/products/hardware-security-module/ + ## What is Signatory Signatory is a remote signing daemon that allows Tezos bakers to sign endorsement and baking operations with various key-management systems. -Signatory currently supports [YubiHSM][yubi], [Azure Key Vault][azure], and for development/prototyping purposes, Signatory can sign with a local private key. +Signatory currently supports [AWS KMS][aws], [Azure Key Vault][azure], [GCP Key Management][gcp], [YubiHSM][yubi], and for development/prototyping purposes, Signatory can sign with a [local private key](localsecret.md). The goal of the Signatory service is to make key management as secure as possible in a Cloud and on-premise HSM context. @@ -20,7 +25,245 @@ By supporting multiple Cloud KMS/HSM systems, we hope to help the network from c Observability is a first-class concern. Signatory allows for rich reporting and alerting capabilities. It exposes metrics about its operation via Prometheus metrics, enabling teams to set up robust monitoring of their critical infrastructure and allowing operators to see historical trends, signing volumes, errors and latencies. Users can report feature requests, security issues, or bug reports can via the Github project page: github.com/ecadlabs/signatory or via email to security@ecadlabs.com -Security issues can be encrypted using the keys available at keybase/jevonearth +Security issues can be encrypted using the keys available at https://keybase.io/jevonearth -[yubi]: https://www.yubico.com/products/hardware-security-module/ -[azure]: https://docs.microsoft.com/en-us/azure/key-vault/ \ No newline at end of file +## Configuration + +Signatory configuration is specified in a YAML file. Use the `signatory.yaml` file as a template to get started. + +You can configure multiple `vault`s. Each `vault` should be configured to use a backend. Same backend can be used in more than one `vault`. + +The configuration file is shared between `signatory` and `signatory-cli`. + +### Configuration Example - File-based Vault + +> :warning: **We don't recommend using the `file` Vault driver in Production.** + +The file-based vault relies on a file containing your wallet's private keys. The `file` vault driver is the least secure of them all compared to the YubiHSM and Cloud KMS drivers; However, it's the easiest Vault to set up when trying Signatory for the first time as it doesn't require you to have a YubiHSM nor a Cloud provider account. + +`/etc/signatory/signatory.yaml` +```yaml +server: + # Address for the main HTTP server to listen on + address: :6732 + # Address for the utility HTTP server (for Prometheus metrics) to listen on + utility_address: :9583 + +vaults: + # Name is used to identify backend during import process + local_file: + driver: file + config: + file: /etc/signatory/secret.json + +# List enabled public keys hashes here +tezos: + # Default policy allows "block" and "endorsement" operations + tz1Wz4ZabKRsz842Xuzy4a7CcWADfPVsPKus: + + # Explicit policy + tz3MhmeqpudUqEX8PYTbNDF3CVcnnjNQoo8N: + # Setting `log_payloads` to `true` will cause Signatory to log operation + # payloads to `stdout`. This may be desirable for audit and investigative + # purposes. + log_payloads: true + allow: + block: + endorsement: + preendorsement: + failing_noop: + generic: + - transaction + - reveal + - delegation + - origination +``` + +`/etc/signatory/secret.json` +```json +[ + { + "name": "tz1Wz4ZabKRsz842Xuzy4a7CcWADfPVsPKus", + "value": "unencrypted:" + }, + { + "name": "tz3MhmeqpudUqEX8PYTbNDF3CVcnnjNQoo8N", + "value": "unencrypted:" + } +] +``` + +## Configuration Example - AWS KMS Vault +This configuration example uses AWS KMS as + +```yaml +server: + # Address for the main HTTP server to listen on + address: :6732 + # Address for the utility HTTP server (for Prometheus metrics) to listen on + utility_address: :9583 + +vaults: + # Name is used to identify backend during import process + + # AWS KMS backend + aws: + driver: awskms + config: + user_name: signatory_testnets # IAM User or Role + access_key_id: # Optional + secret_access_key: # Optional + region: us-west-2 + +tezos: + tz3MhmeqpudUqEX8PYTbNDF3CVcnnjNQoo8N: + allow: + block: + endorsement: + preendorsement: + failing_noop: + generic: + - delegation + - transaction +``` + +## Backends +* [AWS KMS](aws_kms.md) +* [Azure Key Vault](azure_kms.md) +* [GCP Key Management](gcp_kms.md) +* [YubiHSM2](yubihsm.md) + +--- + +## Signatory service + +Signatory service is used for signing operations and implements Tezos specific HTTP external signer API + +``` +A Tezos Remote Signer for signing block-chain operations with private keys + +Usage: + signatory [flags] + signatory [command] + +Available Commands: + help Help about any command + serve Run a server + +Flags: + -c, --config string Config file path (default "signatory.yaml") + -h, --help help for signatory + --log string Log level: [error, warn, info, debug, trace] (default "info") +``` + +### Prometheus metrics and health service + +Signatory exposes Prometheus metrics and health status on the address specified in `utility_address` configuration parameter. The default value is `:9583`. + +#### Prometheus metrics + +Metrics include counters and histograms that track signing operations and errors. + +The metrics are intended to be scraped using the Prometheus time series database. We also publish a ready-made Grafana dashboard that users can use to visualize the operation of their signing operations. (TODO: publish Grafana dashboard) + +`localhost:9583/metrics` + +#### Health service + +The health service endpoint can be used to test if the service is running correctly and is ready to sign requests. + +This endpoint is useful for monitoring, or declarative tests as part of deployment playbooks or Kubernetes manifests. + +`localhost:9583/healthz` + +### Testing + +To test the signing operation, you can send a post to Signatory. In this example, we are sending a dummy operation of type `02`, which is an `endorsement` operation type. + +```sh +curl -XPOST \ + -d '"027a06a770e6cebe5b3e39483a13ac35f998d650e8b864696e31520922c7242b88c8d2ac55000003eb6d"' \ + localhost:8003/keys/tz3Tm6UTWmPAZJaNSPAQNiMiyFSHnRXrkcHj +``` + +If you receive an error from curl and on the signatory console, you will have to investigate. If it was successful, you should see output similar to: + +```json +{"signature":"p2sigR4JTRTMkT4XC4NgVuGdhZDbgaaSZpNPUserkyMCTY1GQJTFpCuihFRVk9n7YaNjA5U3cNcvJPRm7C9G5A1hsLsesVPcMu"} +``` + +--- + +## Signatory command line tool + +Signatory service is used for importing of private keys and obtaining information about available key pairs and their policies. + +``` +A Tezos Remote Signer for signing block-chain operations with private keys + +Usage: + signatory-cli import [flags] + +Flags: + -h, --help help for import + -o, --opt string Options to be passed to the backend. Syntax: key:val[,...] + --password string Password for private key(s) + --vault string Vault name for importing + +Global Flags: + -c, --config string Config file path (default "signatory.yaml") + --log string Log level: [error, warn, info, debug, trace] (default "info") +``` + +### Import a private key + +```sh +signatory-cli -c CONFIG import --vault VAULT PRIVATE_KEY +``` + +Example: + +```sh +signatory-cli -c signatory.yaml import --vault yubi edsk3rsARzj7f8PEHXXUbLigMDCww75nPnzbFmSz19TLwzrYzF8uCB +``` + +### List keys + +```sh +signatory-cli -c CONFIG list +``` + +Example: + +```sh +signatory-cli -c signatory.yaml list +``` + +Example output: + +``` +INFO[0000] Initializing vault vault=cloudkms vault_name=kms +INFO[0000] Initializing vault vault=azure vault_name=azure +Public Key Hash: tz3VfoCwiQyMNYnaseFLFAjN9AQJQnhvddjG +Vault: CloudKMS +ID: projects/signatory-testing/locations/europe-north1/keyRings/hsm-ring/cryptoKeys/hsm-key/cryptoKeyVersions/1 +Allowed Operations: [block endorsement] +Allowed Kinds: [] + +Public Key Hash: tz3ZqyLdKy2doLbw7yghLPz2TWWZdxeLGKVx +Vault: CloudKMS +ID: projects/signatory-testing/locations/europe-north1/keyRings/hsm-ring/cryptoKeys/hsm-key/cryptoKeyVersions/2 +*DISABLED* + +Public Key Hash: tz3aTwpna6m9qsw4YZVFad1nsm5cGgWHVQ8R +Vault: CloudKMS +ID: projects/signatory-testing/locations/europe-north1/keyRings/hsm-ring/cryptoKeys/signatory-imported-1RG8mJUH8P5ncMEMypfkno98Gpq/cryptoKeyVersions/1 +Allowed Operations: [block endorsement generic] +Allowed Kinds: [endorsement transaction] + +Public Key Hash: tz3VkMSRVjLwEoUgZNJwjoD6YHeBDXyWiBaY +Vault: Azure +ID: https://signatory.vault.azure.net/keys/key0/fa9607734e58485181d19da901e725b9 +*DISABLED* + +``` diff --git a/docs/yubihsm.md b/docs/yubihsm.md index b45c7524..983f6327 100644 --- a/docs/yubihsm.md +++ b/docs/yubihsm.md @@ -118,7 +118,6 @@ server: utility_address: localhost:9583 vaults: - # Name is used to identify backend during import process yubi: driver: yubihsm config: @@ -167,20 +166,18 @@ server: utility_address: localhost:9583 vaults: - # Name is used to identify backend during import process yubi: driver: yubihsm config: - address: localhost:12345 # Address for the yubihsm-connector + address: localhost:12345 password: password auth_key_id: 1 tezos: tz1SBhzLDp9Jvg98ztMZMstaKbAENmzRd4Y7: log_payloads: true - allowed_operations: - - generic - allowed_kinds: - - origination + allow: + generic: + - origination ``` Rerun the `signatory-cli list` command to verify that your new address is getting picked up, and is configured as you expect. @@ -192,7 +189,7 @@ Vault: YubiHSM ID: 0cf8 Status: Active Allowed Operations: [generic] -Allowed Kinds: [ballot] +Allowed Kinds: [origination] ``` [yubihsm]: https://www.yubico.com/products/hardware-security-module/