Docs: Update Guardian Key/Signer Documentation

docs/guardian_signer.md

@@ -0,0 +1,43 @@
+# Guardian Signer
+
+The guardian signer is responsible for signing various operations within the Wormhole ecosystem, such as observations (which results in the creation of VAAs) and gossip messages on the peer-to-peer network (see the [whitepaper](../whitepapers/0009_guardian_key.md)). Historically, the guardian only supported signing using a private key on disk. However, the guardian now allows developers to easily add alternative signing mechanisms through the `GuardianSigner` interface introduced in [PR #4120](https://github.com/wormhole-foundation/wormhole/pull/4120).
+
+The guardian node supports the following signing mechanisms:
+* File-based signer - Load a private key from disk, and use it for signing operations.
+* Amazon Web Services KMS - Use AWS' KMS for signing operations.
+
+## Usage
+
+### Traditional Usage
+
+For backwards-capability the traditional `guardianKey` command line argument is still supported. The argument accepts a path to a private key file on disk, that is loaded and used for signing operations:
+
+```sh
+--guardianKey PATH_TO_GUARDIAN_KEY
+```
+
+### Guardian Signer URI Scheme
+
+To make use of alternative signing mechanisms, the `guardianSignerUri` argument can be used. The generic format of the argument is shown below, where `signer` is the name of the mechanism to use and the `signer-config` denotes the configuration of the specified signer. 
+
+```
+--guardianSignerUri <signer>://<signer-config>
+```
+
+The supported signing mechanisms are tabled below.
+
+| Signer | URI Scheme | Description |
+|--------|------------|-------------|
+| File Signer | `file://<path-to-file>` | `path-to-file` denotes the path to the private key on disk |
+| Amazon Web Services KMS | `amazonkms://<arn>` | `<arn>` denotes the Amazon Resource Name of the Key Management Service (KMS) key to use |
+
+## Setup
+
+### AWS KMS Key Setup
+
+_NOTE_ For the best possible performance, it is recommended that the guardian be run from an EC2 instance that is in the same region as the KMS key.
+
+The KMS key's spec should be `ECC_SECQ_P256K1`, and should be enabled for signing. In order for the guardian to authenticate against the KMS service, one of two options are available:
+
+* Create new API keys in the AWS console that are permissioned to use the KMS key for signing, and add the keys to the EC2 instance's `~/.aws/credentials` file. ([example here](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)).
+* Create a role that is permissioned to use the KMS key and attach that role to the Guardian EC2 instance.

whitepapers/0009_guardian_signer.md

@@ -0,0 +1,53 @@
+# Guardian Signer
+
+## Objective
+
+Sign different kinds of messages within the Wormhole ecosystem for the purpose of attestation and guardian identification.
+
+## Background
+
+In order for guardians to attest to on-chain events or prove their identities when communicating among each other, digital signatures are required. On-chain smart contracts and guardians hold registries of public keys of trusted guardian nodes that are permitted to perform certain actions within the guardian ecosystem. Without this system, it would not be possible to distinguish legitimate behavior from malicious.
+
+The guardian signer is responsible for providing signatures, and supports different mechanisms for [producing signatures](../docs/guardian_signer.md).
+
+## Overview
+
+The guardian signer is used to sign numerous messages within the Wormhole ecosystem:
+
+* Gossip Messages - Messages that are sent between guardians, such as heartbeats, governor configs, governor status updates and observation requests.
+* On-Chain Observations - Events that occur on-chain that need to be attested to and delivered to different chains, bundled in VAAs (Version 1).
+* Guardian Identification - Wormchain account registration.
+* Accountant Observations - Sign observations relevant to token bridge and NTT. 
+* Cross-Chain Query Responses - Attest to states on other chains.
+
+## Detailed Design
+
+The process for signing gossip messages are as follows:
+
+1. Prepend the message type prefix to the payload.
+    - This is to ensure uniqueness of the message, and prevent two gossip messages from being used interchangeably for different operations.
+2. Compute the `keccak256` hash of the payload.
+3. Compute a signature of the hash using `ethcrypto.Sign()`.
+
+On-chain observations are signed by performing a double-`keccak256` hashing operation on the observation and signing the result. The resulting data structure, which primarily contains information about the observation and the signature, is called a VAA (Verifiable Action Approval). 
+
+## Prefixes Used
+
+<!-- cspell:disable -->
+
+```go
+acct_sub_obsfig_000000000000000000| // token bridge accountant observation
+ntt_acct_sub_obsfig_00000000000000| // ntt accountant observation
+governor_config_000000000000000000| // gossip governor config
+governor_status_000000000000000000| // gossip governor status
+heartbeat|                          // gossip heartbeat
+signed_observation_request|         // gossip signed observation request
+mainnet_query_request_000000000000| // query request (mainnet, not signed by guardian)
+testnet_query_request_000000000000| // query request (testnet, not signed by guardian)
+devnet_query_request_0000000000000| // query request (devnet, not signed by guardian)
+query_response_0000000000000000000| // query response
+query_response_0000000000000000000| // query response
+signed_wormchain_address_00000000|  // wormchain register account as guardian
+```
+
+<!-- cspell:enable -->