From b2672235f3f057272e5964ac08051b9b2c968321 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Wed, 22 Nov 2023 15:18:01 +0100 Subject: [PATCH] docs: Revamp node/run-your-node/advanced/remote-signer --- .../install-oasis-remote-signer-binary.md | 55 ---- .../run-your-node/advanced/remote-signer.mdx | 258 ++++++++++++++++++ ...cked-consensus-key-with-a-remote-signer.md | 177 ------------ redirects.js | 7 + sidebarNode.js | 3 +- 5 files changed, 266 insertions(+), 234 deletions(-) delete mode 100644 docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md create mode 100644 docs/node/run-your-node/advanced/remote-signer.mdx delete mode 100644 docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md diff --git a/docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md b/docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md deleted file mode 100644 index 372ab3e490..0000000000 --- a/docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md +++ /dev/null @@ -1,55 +0,0 @@ -# Install Oasis Remote Signer Binary - -:::info - -You only need to install the Oasis Remote Signer binary if you intend to configure your Oasis node with a remote signer setup. - -An example of such a setup is described in [Using Ledger-backed Consensus Key with a Remote Signer](using-ledger-backed-consensus-key-with-a-remote-signer.md). - -::: - -The Oasis Remote Signer is a binary that is created from the [Oasis Core](https://github.com/oasisprotocol/oasis-core) repository's [`go/oasis-remote-signer` path](https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer). - -It contains the logic for implementing various Oasis Core signers (i.e. Ledger-based signer, file-based signer or a combination of both via composite signer) and a gRPC service through which an Oasis node can connect to it and request signatures from it. - -:::caution - -The Oasis Remote Signer is currently only supported on x86_64 Linux systems. - -::: - -## Downloading a Binary Release - -:::tip - -We suggest that you build Oasis Remote Signer from source yourself for a production deployment of an Oasis node with a remote signer setup. - -::: - -For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the Network Parameters page ([Mainnet], [Testnet]). - -[Mainnet]: ../../mainnet/README.md -[Testnet]: ../../testnet/README.md - -## Building From Source - -Although highly suggested, building from source is currently beyond the scope of this documentation. - -See [Oasis Core's Build Environment Setup and Building](../../../core/development-setup/build-environment-setup-and-building) documentation for more details. - -:::danger - -The code in the [`master` branch](https://github.com/oasisprotocol/oasis-core/tree/master/) might be incompatible with the code used by other nodes in the Mainnet. - -Make sure to use the version specified in the Network Parameters page ([Mainnet], [Testnet]). - -::: - -## Adding `oasis-remote-signer` Binary to `PATH` - -To install the `oasis-node` binary next to your Oasis node data directory, copy/symlink it to e.g. `/node/bin`. - -To install the `oasis-remote-signer` binary for the current user, copy/symlink it to `~/.local/bin`. - -To install the `oasis-remote-signer` binary for all users of the system, copy it to `/usr/local/bin`. - diff --git a/docs/node/run-your-node/advanced/remote-signer.mdx b/docs/node/run-your-node/advanced/remote-signer.mdx new file mode 100644 index 0000000000..7e436afa71 --- /dev/null +++ b/docs/node/run-your-node/advanced/remote-signer.mdx @@ -0,0 +1,258 @@ +import DocCard from '@theme/DocCard'; +import {findSidebarItem} from '@site/src/sidebarUtils'; + +# Remote Signer for Oasis Node Keys + +The [Oasis remote signer][oasis-core-remote-signer] is an application that +contains logic for various Oasis Core signers. Currently, only the file-based +signer is implemented, but support for hardware signers is in the works. Access +to the remote signer is provided via a gRPC service through which the Oasis node +can connect to it and request signatures. + +This chapter will describe how to install the Oasis remote signer and then +configure your [*validator* node][validator-node] to use it. + +**These are advanced instructions intended for node operators that want to +increase the security of their validator nodes.** + +:::caution + +These instructions are still a work-in-progress draft. + +Your feedback is welcome. Please, reach out via the **#node-operators** channel +at the [Oasis Network Community server on Discord][discord] with your questions, +comments, and feedback. + +::: + +:::tip + +This chapter describes a tool to remotely access the node keys typically +generated on the first run (i.e. `beacon.pem`, `consensus.pem`, +`consensus_pub.pem`, `identity.pem`, `identity_pub.pem`, ...). There is also the +[`oasis wallet remote-signer`] Oasis CLI command which enables remote access to +your entity key. + +::: + +[validator-node]: ../validator-node.mdx +[oasis-core-remote-signer]: https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer +[discord]: ../../../get-involved/README.md +[`oasis wallet remote-signer`]: ../../../general/manage-tokens/cli/wallet.md#remote-signer + +## Prerequisites + +Before following this guide, make sure you've followed the [Prerequisites] +chapter and have the Oasis node binary installed on your system. + +[Prerequisites]: ../prerequisites.md + +## Install Oasis Remote Signer Binary + +The Oasis remote signer is part of the [Oasis Core][oasis-core-remote-signer]. +You can either download the binary or compile it from source. + +:::caution + +The Oasis remote signer is currently only supported on x86_64 Linux systems. + +::: + +### Downloading a Binary Release + +:::tip + +We suggest that you build the Oasis remote signer from source yourself for a +production deployment of an Oasis node with a remote signer setup. + +::: + +The Oasis remote signer binary is part of the **Oasis Core release bundle**. +Links to the latest releases are on the Network Parameters page ([Mainnet], +[Testnet]). The Oasis remote signer binary inside the release bundle is called +`oasis-remote-signer`. You should always use the version of the remote signer +matching the version of your Oasis node. + +[Mainnet]: ../../mainnet/README.md +[Testnet]: ../../testnet/README.md + +### Building From Source + +Follow the [Oasis Core's Build Environment Setup and Building][oasis-core-build] +chapter. After the Oasis Core is compiled, the binary should be located in +`go/oasis-remote-signer/oasis-remote-signer` + +:::danger + +The code in the [`master` branch] might be incompatible with the code used by +other nodes on the network. Make sure to use the version specified on the +Network Parameters page ([Mainnet], [Testnet]). + +::: + +[oasis-core-build]: ../../../core/development-setup/build-environment-setup-and-building.md +[`master` branch]: https://github.com/oasisprotocol/oasis-core/tree/master/ + +### Adding `oasis-remote-signer` Binary to `PATH` + +To install the `oasis-remote-signer` binary for the current user, copy/symlink +it to `~/.local/bin`. + +To install the `oasis-remote-signer` binary for all users of the system, copy +it to `/usr/local/bin`. + +## Set Up Remote Signer System + +### Initialize Remote Signer + +On your remote signer system, create a directory for the remote signer, e.g. +`remote-signer`, by running: + +``` +mkdir --mode=700 remote-signer +``` + +Then initialize the remote signer's keys (i.e. `beacon.pem`, `consensus.pem`, +`consensus_pub.pem`, `identity.pem`, `identity_pub.pem`, ...) and the server +certificate by running: + +``` +oasis-remote-signer init --datadir remote-signer/ +``` + +Also, initialize the remote signer's client certificate which will be used by +the Oasis node to connect to the remote signer: + +``` +oasis-remote-signer init_client --datadir remote-signer/ +``` + +### Run Remote Signer + +Choose the gRPC port on which the remote signer will listen for client requests +and run: + +``` +GRPC_PORT= +oasis-remote-signer \ +--datadir remote-signer \ +--client.certificate remote-signer/remote_signer_client_cert.pem \ +--grpc.port $GRPC_PORT \ +--log.level DEBUG +``` + +:::tip + +The Oasis Remote Signer is configured to run in the foreground by default. + +We recommend you configure and use it with a process manager like [systemd] or +[Supervisor]. + +::: + +[systemd]: https://github.com/systemd/systemd +[Supervisor]: http://supervisord.org + +### Copy Remote Signer Certificate and Client Key and Certificate + +For the Oasis node system to be able to connect to the Oasis Remote Signer on +the remote signer system and to be able to demonstrate its authenticity to it, +you need to copy the following files from your remote signer system to your +Oasis node system: + +* `remote-signer/remote_signer_server_cert.pem`: The remote signer's + certificate. This certificate ensures the Oasis node system is connecting to + the trusted remote signer system. +* `remote-signer/remote_signer_client_key.pem`: The remote signer's client key. + This key enables the Oasis node system to demonstrate its authenticity when it + is requesting signatures from the remote signer system. +* `remote-signer/remote_signer_client_cert.pem`: The remote signer's client + certificate. This certificate is the counterpart of the remote signer's client + key. + +## Set Up Oasis Node + +For setting up your Oasis node, follow the [Run a Validator +Node][validator-node] chapter. + +:::info + +Make sure you've copied the remote signer's certificate and remote signer's +client key and certificate to your Oasis Node system as described in +[Copy Remote Signer Certificate and Client Key and Certificate](#copy-remote-signer-certificate-and-client-key-and-certificate) section. + +::: + +### Initialize Oasis Node + +When [initializing your Oasis node](../validator-node.mdx#initializing-a-node), +you need to pass appropriate `--signer.*` flags to configure the composite and +remote signers. For example: + +``` +ENTITY_DIR= +STATIC_IP= +REMOTE_SIGNER_IP= +REMOTE_SIGNER_PORT= +oasis-node registry node init \ +--signer.backend composite \ +--signer.composite.backends 1:file,2:file,3:file,4:remote \ +--signer.dir $ENTITY_DIR \ +--node.consensus_address $STATIC_IP:26656 \ +--node.role validator \ +--signer.remote.address $REMOTE_SIGNER_IP:$REMOTE_SIGNER_PORT \ +--signer.remote.client.certificate remote-signer/remote_signer_client_cert.pem \ +--signer.remote.client.key remote-signer/remote_signer_client_key.pem \ +--signer.remote.server.certificate remote-signer/remote_signer_server_cert.pem \ +--datadir node/ +``` + +This assumes you've copied the remote signer's certificate and remote signer's +client key and certificate to the `remote-signer/` directory. + +:::tip + +The resulting directory only has `consensus_pub.pem` and no `consensus.pem` +since the consensus key is backed by the Oasis remote signer. + +::: + +### Configure Oasis Node + +When [configuring your Oasis Node](../validator-node.mdx#configuring-the-oasis-node), +you need to add the appropriate `signer` section to configure the composite and +remote signers. For example: + +```yaml +# Signer. +signer: + backend: composite + # Use file-based signer for entity, node and P2P keys and remote signer for the + # consensus key. + composite: + backends: entity:file,node:file,p2p:file,consensus:remote + # Configure how to connect to the Oasis Remote Signer. + remote: + address: : + server: + certificate: /srv/oasis/remote-signer/remote_signer_server_cert.pem + client: + key: /srv/oasis/remote-signer/remote_signer_client_key.pem + certificate: /srv/oasis/remote-signer/remote_signer_client_cert.pem +``` + +This assumes you've copied the remote signer's certificate and remote signer's +client key and certificate to the `/srv/oasis/remote-signer/` directory. + +:::info + +To ensure your Oasis Node will be able to sign consensus transactions, make sure +the Oasis Remote Signer is running on your remote signer system and accepting +remote client connections via the designated port. + +::: + +# See also + + + diff --git a/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md b/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md deleted file mode 100644 index 1f9f9e1205..0000000000 --- a/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md +++ /dev/null @@ -1,177 +0,0 @@ -# Using Ledger-backed Consensus Key with a Remote Signer - -This guide will describe how you can set up your [_validator_ node](../validator-node.mdx) with a detached consensus key stored on a [Ledger](https://www.ledger.com) wallet connected via [Oasis Core's Remote Signer](https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer). - -:::caution - -These instructions are still a work-in-progress draft. - -Your feedback is welcome. Please, reach out via the [**#node-operators** channel at the Oasis Network Community server on Discord](../../../get-involved/README.md) with your questions, comments, and feedback. - -::: - -:::danger - -These are advanced instructions intended for node operators that want to increase their validator node security by having the consensus key be detached and stored on a Ledger wallet and connected via Oasis Core's remote signer instead of having consensus key simply be a file on the file system. - -::: - -## Prerequisites - -Before following this guide, make sure you've followed the [Prerequisites](../prerequisites) section and have the Oasis Node binary installed on your Oasis node system. - -Also make sure you've followed the [Install Oasis Remote Signer Binary](install-oasis-remote-signer-binary.md) section and have the Oasis Remote Signer binary installed on your remote signer system where your Ledger wallet will be connected. - -Finally, make sure you install the _**OasisVal**_** app** on your Ledger wallet. - -## Set Up Remote Signer System - -### Initialize Remote Signer - -On your remote signer system, create a directory for the remote signer, e.g. `remote-signer`, by running: - -``` -mkdir --mode=700 remote-signer -``` - -Then initialize remote signer's keys (consensus, entity, identity, ...) and server certificate by running: - -``` -oasis-remote-signer init --datadir remote-signer/ -``` - -Also initialize remote signer's client certificate which will be used by the Oasis node system to connect to the remote signer system: - -``` -oasis-remote-signer init_client --datadir remote-signer/ -``` - -### Run Remote Signer - -:::info - -Before following the instructions below, make sure your Ledger wallet is connected to your remote signer system, unlocked and the OasisVal App is open. - -::: - -:::caution - -While the OasisVal App is available in _Developer mode_, opening the App brings up the "Pending Ledger review" screen. You need to press both buttons at once to close that screen and transition to the _ordinary_ "Oasis Ready" screen where the OasisVal App is ready to be used. - -::: - -Choose the gRPC port on which the remote signer will listen for client requests and set the path to the `ledger-signer` plugin in the appropriate environment variables and run: - -``` -GRPC_PORT= -LEDGER_SIGNER_PATH= -oasis-remote-signer \ ---datadir remote-signer \ ---signer.backend composite \ ---signer.composite.backends entity:file,node:file,p2p:file,consensus:plugin \ ---signer.plugin.name ledger \ ---signer.plugin.path $LEDGER_SIGNER_PATH \ ---client.certificate remote-signer/remote_signer_client_cert.pem \ ---grpc.port $GRPC_PORT \ ---log.level DEBUG -``` - -:::info - -If necessary, you can configure the Ledger-based signer by setting the `--signer.plugin.config` flag appropriately, e.g.: - -``` ---signer.plugin.config "wallet_id:1fc3be,index:5" -``` - -to configure the wallet with a specific ID and to use a non-zero account index. - -::: - -:::tip - -The Oasis Remote Signer is configured to run in the foreground by default. - -We recommend you configure and use it with a process manager like [systemd](https://github.com/systemd/systemd) or [Supervisor](http://supervisord.org). - -::: - -### Copy Remote Signer Certificate and Client Key and Certificate - -For the Oasis node system to be able to connect to the Oasis Remote Signer on the remote signer system and to be able to demonstrate its authenticity to it, you need to copy the following files from your remote signer system to your Oasis node system: - -* `remote-signer/remote_signer_server_cert.pem`: The remote signer's certificate. This certificate ensures the Oasis node system is connecting to the trusted remote signer system. -* `remote-signer/remote_signer_client_key.pem`: The remote signer's client key. This key enables the Oasis node system to demonstrate its authenticity when it is requesting signatures from the remote signer system. -* `remote-signer/remote_signer_client_cert.pem`: The remote signer's client certificate. This certificate is the counterpart of the remote signer's client key. - -## Set Up Oasis Node System - -For setting up your Oasis Node system, follow the [Run a Validator Node](../validator-node.mdx) docs. - -:::info - -Make sure you've copied the remote signer's certificate and remote signer's client key and certificate to your Oasis Node system as described in [Copy Remote Signer Certificate and Client Key and Certificate](using-ledger-backed-consensus-key-with-a-remote-signer.md#copy-remote-signer-certificate-and-client-key-and-certificate) section. - -::: - -### Initialize Oasis Node - -When [initializing your Oasis node](../validator-node.mdx#initializing-a-node), you need to pass appropriate `--signer.*` flags to configure the composite and remote signers. For example: - -``` -ENTITY_DIR= -STATIC_IP= -REMOTE_SIGNER_IP= -REMOTE_SIGNER_PORT= -oasis-node registry node init \ ---signer.backend composite \ ---signer.composite.backends 1:file,2:file,3:file,4:remote \ ---signer.dir $ENTITY_DIR \ ---node.consensus_address $STATIC_IP:26656 \ ---node.role validator \ ---signer.remote.address $REMOTE_SIGNER_IP:$REMOTE_SIGNER_PORT \ ---signer.remote.client.certificate remote-signer/remote_signer_client_cert.pem \ ---signer.remote.client.key remote-signer/remote_signer_client_key.pem \ ---signer.remote.server.certificate remote-signer/remote_signer_server_cert.pem \ ---datadir node/ -``` - -This assumes you've copied the remote signer's certificate and remote signer's client key and certificate to the `remote-signer/` directory. - -:::tip - -The resulting directory only has `consensus_pub.pem` and no `consensus.pem` since the consensus key is Ledger-backed. - -::: - -### Configure Oasis Node - -When [configuring your Oasis Node](../validator-node.mdx#configuring-the-oasis-node), you need to add the appropriate `signer` section to configure the composite and remote signers. For example: - -```yaml -# Signer. -signer: - backend: composite - # Use file-based signer for entity, node and P2P keys and remote signer for the - # consensus key. - composite: - backends: entity:file,node:file,p2p:file,consensus:remote - # Configure how to connect to the Oasis Remote Signer. - remote: - address: : - server: - certificate: /srv/oasis/remote-signer/remote_signer_server_cert.pem - client: - key: /srv/oasis/remote-signer/remote_signer_client_key.pem - certificate: /srv/oasis/remote-signer/remote_signer_client_cert.pem -``` - -This assumes you've copied the remote signer's certificate and remote signer's client key and certificate to the `/srv/oasis/remote-signer/` directory. - -:::info - -To ensure your Oasis Node will be able to sign consensus transactions, make sure your Ledger wallet is connected to your remote signer system, unlocked and the OasisVal App is open. - -Also make sure the Oasis Remote Signer is running on your remote signer system and accepting remote client connections via the designated port. - -::: diff --git a/redirects.js b/redirects.js index b6823af73c..9607f5f8a4 100644 --- a/redirects.js +++ b/redirects.js @@ -174,6 +174,13 @@ const redirectsOptions = { to: '/node/genesis-doc', from: '/general/oasis-network/genesis-doc', // #200 Restructure docs }, + { + to: '/node/run-your-node/advanced/remote-signer', + from: [ + '/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer', // #626 Deprecate oasis-core-ledger + '/node/run-your-node/advanced/install-oasis-remote-signer-binary', // #626 Deprecate oasis-core-ledger + ], + }, { to: '/node/run-your-node/ias-proxy', from: '/general/run-a-node/set-up-your-node/run-an-ias-proxy', // #200 Restructure docs diff --git a/sidebarNode.js b/sidebarNode.js index bae7db0d6d..05a3961f31 100644 --- a/sidebarNode.js +++ b/sidebarNode.js @@ -121,8 +121,7 @@ const sidebars = { items: [ 'node/run-your-node/advanced/sync-node-using-state-sync', 'node/run-your-node/advanced/copy-state-from-one-node-to-the-other', - 'node/run-your-node/advanced/install-oasis-remote-signer-binary', - 'node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer', + 'node/run-your-node/advanced/remote-signer', ] }, 'node/run-your-node/troubleshooting',