From 47aa73a86ee66793d718942fefaa27bdb617848e Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Mon, 24 Jan 2022 11:31:05 +0100 Subject: [PATCH 1/6] wip: authentication --- src/engine/authentication.md | 49 ++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 src/engine/authentication.md diff --git a/src/engine/authentication.md b/src/engine/authentication.md new file mode 100644 index 000000000..0c1767c45 --- /dev/null +++ b/src/engine/authentication.md @@ -0,0 +1,49 @@ +# Authentication + +The `engine` JSON-RPC interface, exposed by EL and consumed by CL, needs to be authenticated. The authentication scheme chosen for thus purpose is [JWT](https://jwt.io/). + +The type of attacks that this authentication scheme attempts to protect against are the following: + +- RPC port exposed towards the internet, allowing attackers to exchange messages with EL engine api. +- RPC port exposed towards the browser, allowing malicious webpages to submit messages to the EL engine api. + +The authentication scheme is _not_ designed to + +- Prevent attackers with capability to read ('sniff') network traffic from reading the traffic, +- Prevent attackers with capability to read ('sniff') network traffic from performing replay-attacks of earlier messages. + +Authentication is performed as follows: + +- For `HTTP` dialogue, each `jsonrpc` request is individually authenticated by supplying `JWT` token in the HTTP header. +- For a WebSocket dialogue, only the initial handshake is authenticated, after which the message dialogue proceeds without further use of JWT. + - Clarification: The websocket handshake starts with the client performing a websocket upgrade request. This is a regular http GET request, and the actual +parameters for the WS-handshake is carried in the http headers. +- For `inproc`, a.k.a raw ipc communication, no authentication is required, under the assumption that a process able to access `ipc` channels for the process, which usually means local file access, is already sufficiently permissioned that further authentication requirements do not add security. + + +## JWT specifications + +- The authenticated `engine` api **MUST** use a different port from the legacy API. The EL **SHOULD** default to using port `8546`. +- On the authenticated endpoint, the legacy API **MUST** also be available. +- The EL **MUST** support the at least the following `alg` `HMAC + SHA256` (`HS256`) +- The EL **MUST** reject the `alg` `none`. + + +The HMAC algorithm means that symmetric encryption is used, thus several CL's will be able to use the same key, and, from an authentication perspective be able to impersonate each other. From a deployment perspective, it means that an EL does not need to be provisioned with individual keys for each caller. + +## Key distribution + +The `EL` and `CL` clients **MUST** accept a cli/config parameter: `jwt-secret`, a `256` bit key, to be used for verifying/generating jwt tokens. +If such a parameter is not given, the client **SHOULD** generate such a token, valid for the duration of the execution, and show the token in the output, which the user can then use to provision the counterpart client with. + +## JWT Claims + +The JWT payload/claims should include: + +- Required: `iat` (issued-at) claim. The EL **SHOULD** only accept `iat` timestamps which are within +-5 seconds from the current time. +- Optional: `id` claim. The CL **MAY** use this to communicate a unique identifier for the individual CL node. +- Optional: `clver` claim. The CL **MAY** use this to communicate the CL node type/version. + +## Examples + +Todo, add some examples of JWT authentication here. \ No newline at end of file From 493b67810b8ad3e18079ab646b8b0bdee32a7198 Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Mon, 24 Jan 2022 11:34:35 +0100 Subject: [PATCH 2/6] squashme --- src/engine/authentication.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/engine/authentication.md b/src/engine/authentication.md index 0c1767c45..204b41fe4 100644 --- a/src/engine/authentication.md +++ b/src/engine/authentication.md @@ -42,7 +42,9 @@ The JWT payload/claims should include: - Required: `iat` (issued-at) claim. The EL **SHOULD** only accept `iat` timestamps which are within +-5 seconds from the current time. - Optional: `id` claim. The CL **MAY** use this to communicate a unique identifier for the individual CL node. -- Optional: `clver` claim. The CL **MAY** use this to communicate the CL node type/version. +- Optional: `clv` claim. The CL **MAY** use this to communicate the CL node type/version. + +Other claims included in the JWT payload, which the EL does not handle, **MUST** be ignored. ## Examples From 3aa4c1991fae2e306eff9fb46d5cf1851d92c525 Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Tue, 25 Jan 2022 14:14:32 +0100 Subject: [PATCH 3/6] authentication: updates --- src/engine/authentication.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/engine/authentication.md b/src/engine/authentication.md index 204b41fe4..e9faa0fa1 100644 --- a/src/engine/authentication.md +++ b/src/engine/authentication.md @@ -17,15 +17,16 @@ Authentication is performed as follows: - For `HTTP` dialogue, each `jsonrpc` request is individually authenticated by supplying `JWT` token in the HTTP header. - For a WebSocket dialogue, only the initial handshake is authenticated, after which the message dialogue proceeds without further use of JWT. - Clarification: The websocket handshake starts with the client performing a websocket upgrade request. This is a regular http GET request, and the actual -parameters for the WS-handshake is carried in the http headers. +parameters for the WS-handshake are carried in the http headers. - For `inproc`, a.k.a raw ipc communication, no authentication is required, under the assumption that a process able to access `ipc` channels for the process, which usually means local file access, is already sufficiently permissioned that further authentication requirements do not add security. ## JWT specifications -- The authenticated `engine` api **MUST** use a different port from the legacy API. The EL **SHOULD** default to using port `8546`. +- Client software MUST expose the authenticated Engine API at a port independent from legacy JSON-RPC API. + - The default port for the authenticated Engine API is `8551`. The Engine API is exposed under the `engine` namespace. - On the authenticated endpoint, the legacy API **MUST** also be available. -- The EL **MUST** support the at least the following `alg` `HMAC + SHA256` (`HS256`) +- The EL **MUST** support at least the following `alg` `HMAC + SHA256` (`HS256`) - The EL **MUST** reject the `alg` `none`. @@ -48,4 +49,4 @@ Other claims included in the JWT payload, which the EL does not handle, **MUST** ## Examples -Todo, add some examples of JWT authentication here. \ No newline at end of file +Todo, add some examples of JWT authentication here. From 5e674fc7dcd125887fb0bc69e153bd9d2f15c5ca Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Fri, 4 Feb 2022 08:43:52 +0100 Subject: [PATCH 4/6] change output form for generated secret + clarifications --- src/engine/authentication.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/engine/authentication.md b/src/engine/authentication.md index e9faa0fa1..f9ca3114b 100644 --- a/src/engine/authentication.md +++ b/src/engine/authentication.md @@ -23,7 +23,7 @@ parameters for the WS-handshake are carried in the http headers. ## JWT specifications -- Client software MUST expose the authenticated Engine API at a port independent from legacy JSON-RPC API. +- Client software MUST expose the authenticated Engine API at a port independent from existing JSON-RPC API. - The default port for the authenticated Engine API is `8551`. The Engine API is exposed under the `engine` namespace. - On the authenticated endpoint, the legacy API **MUST** also be available. - The EL **MUST** support at least the following `alg` `HMAC + SHA256` (`HS256`) @@ -34,8 +34,11 @@ The HMAC algorithm means that symmetric encryption is used, thus several CL's wi ## Key distribution -The `EL` and `CL` clients **MUST** accept a cli/config parameter: `jwt-secret`, a `256` bit key, to be used for verifying/generating jwt tokens. -If such a parameter is not given, the client **SHOULD** generate such a token, valid for the duration of the execution, and show the token in the output, which the user can then use to provision the counterpart client with. +The `EL` and `CL` clients **MUST** accept a cli/config parameter: `jwt-secret`, which designates a file containing the hex-encoded 256 bit secret key to be used for verifying/generating jwt tokens. + +If such a parameter is not given, the client **SHOULD** generate such a token, valid for the duration of the execution, and store it the hex-encoded secret as a `jwt.hex` file on the filesystem. This file can then be used to provision the counterpart client. + +If such a parameter _is_ given, but the file cannot be read, or does not contain a hex-encoded key of at least `256` bits, the client should treat this as an error: either abort the startup, or show error and continue without exposing the authenticated port. ## JWT Claims @@ -45,7 +48,7 @@ The JWT payload/claims should include: - Optional: `id` claim. The CL **MAY** use this to communicate a unique identifier for the individual CL node. - Optional: `clv` claim. The CL **MAY** use this to communicate the CL node type/version. -Other claims included in the JWT payload, which the EL does not handle, **MUST** be ignored. +Other claims **MAY** be included in the JWT payload. If the EL sees claims it does not recognize, these **MUST** be ignored. ## Examples From b32028f5cc2f302469eac8fd52606c066d368c0a Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Fri, 4 Feb 2022 08:55:05 +0100 Subject: [PATCH 5/6] add acronyms to wordlist --- wordlist.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/wordlist.txt b/wordlist.txt index d372d3132..5ed93ded6 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -29,3 +29,9 @@ validator wei yaml yParity +EL +CL +JWT +WS +ipc +cli From 3162ac563bfc0729fa1a24b2510830b20e8be9fa Mon Sep 17 00:00:00 2001 From: Danny Ryan Date: Mon, 7 Feb 2022 06:51:10 -0700 Subject: [PATCH 6/6] Update src/engine/authentication.md --- src/engine/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/authentication.md b/src/engine/authentication.md index f9ca3114b..f7fee2d0c 100644 --- a/src/engine/authentication.md +++ b/src/engine/authentication.md @@ -42,7 +42,7 @@ If such a parameter _is_ given, but the file cannot be read, or does not contain ## JWT Claims -The JWT payload/claims should include: +This specification utilizes the following list of JWT claims: - Required: `iat` (issued-at) claim. The EL **SHOULD** only accept `iat` timestamps which are within +-5 seconds from the current time. - Optional: `id` claim. The CL **MAY** use this to communicate a unique identifier for the individual CL node.