From 2bdc1f37ca435ba1878eba3dd6b8a7dbf071c1ed Mon Sep 17 00:00:00 2001 From: Peter Neuroth Date: Wed, 8 Nov 2023 09:40:16 +0100 Subject: [PATCH] doc: Introduce runes to the security docs Signed-off-by: Peter Neuroth --- docs/src/reference/security.md | 54 ++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 18 deletions(-) diff --git a/docs/src/reference/security.md b/docs/src/reference/security.md index 04b1501f8..7c1294eaf 100644 --- a/docs/src/reference/security.md +++ b/docs/src/reference/security.md @@ -53,24 +53,24 @@ section. ## Client ⇄ Signer authentication The signer cannot rely on the mTLS CA structure, since that is under -control of the Greenlight team. As such it uses an attestation scheme -in which the signer-identity attests to itself (and other signers) -that a given client is permitted to perform some operations. - -Upon registering a new client, the signer will provide an attestation -signature. This attestation signature is what tells other signers that -commands originating from that client are to be accepted. This is -important because it allows multiple signers to recognize which -clients are authorized, even if the attesting signer is not the signer -that is currently verifying the authorization. +control of the Greenlight team. Instead, Greenlight employs an +attestation scheme in which the signer identity attests to itself and +other signers that a particular client is authorized to perform +certain operations. + +When registering a new client, the signer will submit a [`rune`][rune] +as an access token. The rune serves as both an authentication and +authorization token, and is tied to the client's identity; it is +presented to the signer on each request. This will allow multiple +signers to recognize which clients are authorized, even if the signer +who carved the rune is not the signer verifying the authorization. Before signing a request the signer independently verifies that: 1. The operations that it is asked to sign off on match pending RPC commands, and are safe to perform. 2. The pending RPC commands are all signed by a valid client-identity - 3. The client-identities all have a matching attestation signature - from the signer + 3. The client-identities all have a valid rune from a signer. 4. None of the pending RPC commands is a replay of a previously completed RPC command. @@ -82,10 +82,28 @@ preventing read-access that doesn't involve the signer, while the latter ensures funds are not moved without a client authorizing it. The client-identity pubkey, its signature of the command payload, and -the signer-attestation are all passed to the node via grpc -headers. The node extracts them, alongside the call itself, and adds -it to a request context which will itself be attached to requests that -are sent to the signer, so it can verify the validity and authenticity -of the operations. An attacker that gains access to the node is unable -to provide either these signatures and will therefore fail to convince +the rune are all passed to the node via grpc headers. The node +extracts them, alongside the call itself, and adds it to a request +context which will itself be attached to requests that are sent to the +signer, so it can verify the validity and authenticity of the +operations. An attacker that gains access to the node is unable to +provide either these signatures and will therefore fail to convince the signer of its injected commands. + +## Client ⇄ Signer Authorization + +The [`rune`][rune]-based signer authentication verifies a client's +identity and their authorization to execute commands. To achieve more +granular control over command authorization for individual clients, a +rune can be created with specific restrictions. When verifying client +identity, the signer additionally ensures that specific conditions, +such as the requested command, align with the limitations of the given +rune. + +This enables a user to share access to the signer across multiple +clients that are restricted to a subset of commands, for example +read-only clients, or invoice-only clients, or clients that can only +create on-chain addresses and so on. + + +[rune]: https://github.com/rustyrussell/runes