docs: Revamp node/run-your-node/advanced/remote-signer

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=<REMOTE-SIGNER-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=<YOUR-ENTITY-DIR>
+STATIC_IP=<YOUR-STATIC-IP>
+REMOTE_SIGNER_IP=<YOUR-REMOTE-SIGNER-IP>
+REMOTE_SIGNER_PORT=<YOUR-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: <YOUR-REMOTE-SIGNER-IP>:<YOUR-REMOTE-SIGNER-PORT>
+    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
+
+<DocCard item={findSidebarItem('/node/run-your-node/validator-node')} />
+<DocCard item={findSidebarItem('/general/manage-tokens/cli/wallet')} />