瀏覽代碼

add whitepaper explaining guardian key usage (#1960)

Co-authored-by: tbjump <unknown>
tbjump 3 年之前
父節點
當前提交
31dfbef6e7
共有 1 個文件被更改,包括 37 次插入0 次删除
  1. 37 0
      whitepapers/0009_guardian_key.md

+ 37 - 0
whitepapers/0009_guardian_key.md

@@ -0,0 +1,37 @@
+# Guardian Key Usage
+
+## Objective
+* Describe how guardian keys are used and how message confusion is avoided.
+
+
+## Background
+Message confusion could occur when a Guardian signs a message and an attacker replays that message elsewhere where it is interpreted as a different message type, which could lead to unintended behavior.
+
+
+## Overview
+The Guardian Key is used to:
+1. Sign gossip messages
+    1. heartbeat
+    2. governor config and governor status
+    3. observation request
+2. Sign Observations
+    1. Version 1 VAAs
+    2. Version 2 VAAs, i.e. Batch VAAs.
+
+## Detailed Design
+
+Signing of gossip messages:
+1. Prepend the message type prefix to the payload
+2. Compute Keccak256Hash of the payload.
+3. Compute ethcrypto.Sign()
+
+Signing of Observations:
+* v1 VAA: `double-Keccak256(observation)`.
+* v2 (batchVAA): `double-Keccak256(version | Keccak256(hash1 | hash2 | ... | hash_n))`, where `|` stands for concatenation.
+
+Rationale
+* Gossip messages cannot be confused with other gossip messages because the message type prefix is prepended.
+* Gossip messages cannot be confused with observations because observations utilize a double-Keccak256 and the payload is enforced to be `>=34` bytes.
+* v2 VAAs cannot be confused as v1 VAAs because their payload when parsed as a v1 VAA is only 33 bytes, which does not constitute a valid observation.
+* v1 VAAs cannot be confused as v2 VAAs because observations are longer than 33 bytes and hence do not constitute a valid v2 VAA body.
+