From d34c06c48e83e51314b2ff40d828e8b5f00784fa Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Wed, 22 Dec 2021 19:08:23 +0000 Subject: [PATCH 01/13] Add API and Server Version --- connection.capnp | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/connection.capnp b/connection.capnp index 6ec6ad9..98337df 100644 --- a/connection.capnp +++ b/connection.capnp @@ -11,6 +11,17 @@ using MachineSystem = import "machinesystem.capnp".MachineSystem; using UserSystem = import "usersystem.capnp".UserSystem; using PermissionSystem = import "permissionsystem.capnp".PermissionSystem; +const api_version_major :Int32 = 0; +const api_version_minor :Int32 = 3; +const api_version_patch :Int32 = 0; + +struct Version +{ + major @0 :Int32; + minor @1 :Int32; + patch @2 :Int32; +} + interface Bootstrap { authenticationSystem @0 () -> ( authenticationSystem : AuthenticationSystem ); @@ -19,5 +30,9 @@ interface Bootstrap userSystem @2 () -> ( userSystem : UserSystem ); - permissionSystem @3 () -> ( permissionSystem : PermissionSystem ); + permissionSystem @3 () -> ( permissionSystem : PermissionSystem ); + + getAPIVersion @4 () -> ( version : Version ); + + getServerVersion @5 () -> ( version : Version ); } From f1bd45141e0c1f46a05f1f90753b6a6f20218173 Mon Sep 17 00:00:00 2001 From: TheJoKlLa Date: Wed, 22 Dec 2021 19:13:42 +0000 Subject: [PATCH 02/13] Changed API Version ID to get backward compatibility in Bootstrap Interface --- connection.capnp | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/connection.capnp b/connection.capnp index 98337df..ef6725b 100644 --- a/connection.capnp +++ b/connection.capnp @@ -24,15 +24,15 @@ struct Version interface Bootstrap { - authenticationSystem @0 () -> ( authenticationSystem : AuthenticationSystem ); + getAPIVersion @0 () -> ( version : Version ); - machineSystem @1 () -> ( machineSystem : MachineSystem ); + getServerVersion @1 () -> ( version : Version ); + + authenticationSystem @2 () -> ( authenticationSystem : AuthenticationSystem ); + + machineSystem @3 () -> ( machineSystem : MachineSystem ); - userSystem @2 () -> ( userSystem : UserSystem ); + userSystem @4 () -> ( userSystem : UserSystem ); - permissionSystem @3 () -> ( permissionSystem : PermissionSystem ); - - getAPIVersion @4 () -> ( version : Version ); - - getServerVersion @5 () -> ( version : Version ); + permissionSystem @5 () -> ( permissionSystem : PermissionSystem ); } From b12a5601c3ffa40de7502b2680ba584bc284dc31 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 16:06:39 +0100 Subject: [PATCH 03/13] make getServerVersion able to return more informational output --- connection.capnp | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/connection.capnp b/connection.capnp index ef6725b..1bb125c 100644 --- a/connection.capnp +++ b/connection.capnp @@ -26,7 +26,10 @@ interface Bootstrap { getAPIVersion @0 () -> ( version : Version ); - getServerVersion @1 () -> ( version : Version ); + getServerRelease @1 () -> ( name :Text, release :Text ); + # Returns the server implementation name and version/build number + # Designed only for human-facing debugging output so should be informative over machine-readable + # Example: ( name = "bffhd", release = "0.3.1-f397e1e [rustc 1.57.0 (f1edd0429 2021-11-29)]") authenticationSystem @2 () -> ( authenticationSystem : AuthenticationSystem ); From 89edea3ead46a024a0a8b640d05b0a0b5714b1f9 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 16:24:39 +0100 Subject: [PATCH 04/13] Make `const` defs UPPERCASE This, f1bd4514 and b12a5601 implement proper versioning, so: Fixes: #17 --- connection.capnp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/connection.capnp b/connection.capnp index 1bb125c..cf7758b 100644 --- a/connection.capnp +++ b/connection.capnp @@ -11,9 +11,9 @@ using MachineSystem = import "machinesystem.capnp".MachineSystem; using UserSystem = import "usersystem.capnp".UserSystem; using PermissionSystem = import "permissionsystem.capnp".PermissionSystem; -const api_version_major :Int32 = 0; -const api_version_minor :Int32 = 3; -const api_version_patch :Int32 = 0; +const API_VERSION_MAJOR :Int32 = 0; +const API_VERSION_MINOR :Int32 = 3; +const API_VERSION_PATCH :Int32 = 0; struct Version { From f1a7e3882d60d3425d397a099d25dac9b241cda3 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 16:43:58 +0100 Subject: [PATCH 05/13] use MADR --- .gitignore | 5 ++ ...markdown-architectural-decision-records.md | 22 ++++++ docs/decisions/index.md | 13 ++++ docs/decisions/template.md | 72 +++++++++++++++++++ 4 files changed, 112 insertions(+) create mode 100644 docs/decisions/0000-use-markdown-architectural-decision-records.md create mode 100644 docs/decisions/index.md create mode 100644 docs/decisions/template.md diff --git a/.gitignore b/.gitignore index 5588931..7124615 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,7 @@ tags *.cs + +# MADR +/node_modules/ +/package-lock.json +/package.json diff --git a/docs/decisions/0000-use-markdown-architectural-decision-records.md b/docs/decisions/0000-use-markdown-architectural-decision-records.md new file mode 100644 index 0000000..428218e --- /dev/null +++ b/docs/decisions/0000-use-markdown-architectural-decision-records.md @@ -0,0 +1,22 @@ +# Use Markdown Architectural Decision Records (MADR) + +## Context and Problem Statement + +We want to record architectural decisions made in this project. +Which format and structure should these records follow? + +## Considered Options + +* [Markdown Architectural Decisions Record (MADR)](https://adr.github.io/madr/) +* Gitlab issues +* Formless – No conventions for file format and structure + +## Decision Outcome + +Chosen option: "Markdown Architectural Decisions Record (MADR)", because + +* Markdown is an easy to write textual format requiring no tooling to be easily human readable +* Markdown is widely supported and is auto-rendered by all git hosting platforms considered +* Can be easily stored alongside the actual code and documentation since plain-text files play well with git +* Is not bound to a single hosting platform like Gitlab issues would be +* Gives a very sensible default template and format for us to use diff --git a/docs/decisions/index.md b/docs/decisions/index.md new file mode 100644 index 0000000..37ef8b8 --- /dev/null +++ b/docs/decisions/index.md @@ -0,0 +1,13 @@ +# Architectural Decision Log + +This log lists the architectural decisions for [project name]. + + + +* [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records (MADR) + + + +For new ADRs, please use [template.md](template.md) as basis. +More information on MADR is available at . +General information about architectural decision records is available at . diff --git a/docs/decisions/template.md b/docs/decisions/template.md new file mode 100644 index 0000000..25696bb --- /dev/null +++ b/docs/decisions/template.md @@ -0,0 +1,72 @@ +# [short title of solved problem and solution] + +* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] +* Deciders: [list everyone involved in the decision] +* Date: [YYYY-MM-DD when the decision was last updated] + +Technical Story: [description | ticket/issue URL] + +## Context and Problem Statement + +[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] + +## Decision Drivers + +* [driver 1, e.g., a force, facing concern, …] +* [driver 2, e.g., a force, facing concern, …] +* … + +## Considered Options + +* [option 1] +* [option 2] +* [option 3] +* … + +## Decision Outcome + +Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. + +### Positive Consequences + +* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] +* … + +### Negative Consequences + +* [e.g., compromising quality attribute, follow-up decisions required, …] +* … + +## Pros and Cons of the Options + +### [option 1] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +### [option 2] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +### [option 3] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +## Links + +* [Link type] [Link to ADR] +* … From 5de7dc2ef36b71a56b8c22836dce88cc2cf789de Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 17:31:29 +0100 Subject: [PATCH 06/13] Transport encryption ADR --- ...001-require-strong-transport-encryption.md | 86 +++++++++++++++++++ docs/decisions/index.md | 1 + 2 files changed, 87 insertions(+) create mode 100644 docs/decisions/0001-require-strong-transport-encryption.md diff --git a/docs/decisions/0001-require-strong-transport-encryption.md b/docs/decisions/0001-require-strong-transport-encryption.md new file mode 100644 index 0000000..d558d82 --- /dev/null +++ b/docs/decisions/0001-require-strong-transport-encryption.md @@ -0,0 +1,86 @@ +# Require the use of transport encryption + +* Status: accepted +* Deciders: @dequbed, @TheJoKlLa, @kjk + +## Context and Problem Statement + +Implementers of the API should use some level of transport encryption for any +non-local communication because it's not the 2000's anymore and our crypto is +actually good, cheap and secure. + +## Decision Drivers + +* The software stack in question has a decent amount of security relevance, even when only used in a LAN context. +* Since most users of the API connect via WLAN and most of those are using PSK, eavesdropping is trivial + +## Considered Options + +* [TLS] +* [DTLS] +* [Noise protocol][noise] + +## Decision Outcome + +Chosen option: "TLS", because TLS overall is the easiest to implement for the +remaining stack as it currently stands and most sysadmins have a good +understanding of the PKI of TLS. + +### Positive Consequences + +* Reliable transport encryption is ensured +* PKI structure of TLS can easily solve the inherent trust establishment problem in a federated setting + +### Negative Consequences + +* Generating a trusted X.509 certificate is required for federated application incurring either monetary cost or additional setup work +* Encryption overhead is a relevant factor in ultra-low-powered devices in cases with a for that use-case badly configured server (i.e. not offering ChaCha20 and other computationally cheap algorithms) + +## Pros and Cons of the Options + +### TLS + +Use the known and proven TLS protocol + +* Good, because TLS support is ubiquitous on all platforms +* Good, because TLS allows to negotiate cipher algorithms allowing different devices to chose the cipher best suited for them +* Good, because TLS offers extensions, e.g. [ALPN] that make protocol versioning easier +* Bad, because TLS is not well suited for [SCTP] which the protocol in future wants to switch to +* Bad, because TLS is inherently very complex and has suffered from many attack vectors, best known e.g. [Heartbleed] and [Logjam] that require extra caution when configuring TLS +* Bad, because TLS' cipher negotiation (especially below version 1.3) is susceptible to downgrade attacks, especially in the case of a `STARTTLS`-style usage. + +### DTLS + +Use the [Datagram Transport Layer Security][DTLS] which is an IETF protocol similar to TLS but specifically designed for message-orientated protocols where message losses and reoderings have to be tolerated. + +* Good, because it shares most of the advantages of TLS but also [more ergonomically works with SCTP][sctp-dtls] +* Bad, because DTLS is significantly less well supported than TLS +* Bad, because DTLS has no equivalent for TLSv1.3 which adds significant improvents over TLSv1.2 in terms of security + +### Noise protocol framework + +Use encryption based on Noise, a framework with support for mutual and optional authentication, identity hiding, forward secrecy, zero round-trip encryption, and other advanced features. + +* Good, because it has no design for cipher negotiation making downgrade attacks impossible +* Good, because the lightweight nature of noise and the ciphers chosen means it has very limited impact compared to TLS or DTLS +* Good, because noise lends itself very well to a system where encryption keys are shared via side-channel, e.g. by scanning a QR code also containing the address to connect to. +* Bad, because platform support is very limited compared to TLS/DTLS, although the most important ones i.e. [Rust][noise-rust] (bffhd), [C#](noise-csharp) (Borepin), Python([1][noise-python1], [2][noise-python2]) (pyfabaccess) are covered. +* Bad, because noise requires more implementation work than TLS in terms of numbers of lines of code and in decisions to make. + +## Links + +* [Link type] [Link to ADR] +* … + +[TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security +[DTLS]: https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security +[noise]: http://www.noiseprotocol.org/ +[ALPN]: https://datatracker.ietf.org/doc/html/rfc7301 +[SCTP]: https://en.wikipedia.org/wiki/Stream_Control_Transmission_Protocol +[Heartbleed]: https://heartbleed.com/ +[LogJam]: https://weakdh.org/logjam.html +[sctp-dtls]: https://datatracker.ietf.org/doc/html/rfc6083 +[noise-rust]: https://github.com/mcginty/snow +[noise-csharp]: https://github.com/Metalnem/noise +[noise-python1]: https://github.com/plizonczyk/noiseprotocol +[noise-python2]: https://github.com/tgalal/dissononce diff --git a/docs/decisions/index.md b/docs/decisions/index.md index 37ef8b8..2ab5d0c 100644 --- a/docs/decisions/index.md +++ b/docs/decisions/index.md @@ -5,6 +5,7 @@ This log lists the architectural decisions for [project name]. * [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records (MADR) +* [ADR-0001](0001-require-strong-transport-encryption.md) - Require the use of transport encryption From 8033653d2cf1a4554c70961c32b52b4c0e2276d3 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 17:34:24 +0100 Subject: [PATCH 07/13] fix links in ADR-0001 --- .../0001-require-strong-transport-encryption.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/decisions/0001-require-strong-transport-encryption.md b/docs/decisions/0001-require-strong-transport-encryption.md index d558d82..9e679fe 100644 --- a/docs/decisions/0001-require-strong-transport-encryption.md +++ b/docs/decisions/0001-require-strong-transport-encryption.md @@ -69,8 +69,14 @@ Use encryption based on Noise, a framework with support for mutual and optional ## Links -* [Link type] [Link to ADR] -* … +* [Transport Layer Security (TLS)][TLS] +* [Datagram Transport Layer Security (DTLS)][DTLS] +* [Noise Protocol Framework][noise] +* [TLS Application-Layer Protocol Negotiation Extension (ALPN)][ALPN] +* [Stream Control Transmission Protocol (SCTP)][SCTP] +* [Heartbleed] +* [LogJam] +* [Datagram Transport Layer Security for Stream Control Transmission Protocol][sctp-dtls] [TLS]: https://en.wikipedia.org/wiki/Transport_Layer_Security [DTLS]: https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security From bb88fb1832d204591aee80d7df6036470bc5a1de Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 17:39:00 +0100 Subject: [PATCH 08/13] Add `category` field to Machines Fixes: #20 --- machine.capnp | 1 + 1 file changed, 1 insertion(+) diff --git a/machine.capnp b/machine.capnp index 2b31750..38254fe 100644 --- a/machine.capnp +++ b/machine.capnp @@ -38,6 +38,7 @@ struct Machine { manager @5:User; wiki @13 :Text; urn @14 :Text; + category @15 :Text; info @6 :Info; interface Info $CSharp.name("InfoInterface") { From a9ea6120733afd9d75ba8872faa0c5bb41ff3174 Mon Sep 17 00:00:00 2001 From: Kai Kriegel Date: Wed, 5 Jan 2022 18:07:02 +0000 Subject: [PATCH 09/13] render ADRs via gitlab pages --- .gitlab-ci.yml | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .gitlab-ci.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..63562d2 --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,39 @@ +# This file is a template, and might need editing before it works on your project. +# To contribute improvements to CI/CD templates, please follow the Development guide at: +# https://docs.gitlab.com/ee/development/cicd/templates.html +# This specific template is located at: +# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Pages/Jekyll.gitlab-ci.yml + +# Template project: https://gitlab.com/pages/jekyll +# Docs: https://docs.gitlab.com/ee/pages/ +image: ruby:2.6 + +variables: + JEKYLL_ENV: production + LC_ALL: C.UTF-8 + +before_script: + - gem install bundler + - bundle install + +test: + stage: test + script: + - bundle exec jekyll build -d test -s docs/decisions + artifacts: + paths: + - test + except: + variables: + - $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +pages: + stage: deploy + script: + - bundle exec jekyll build -d public -s docs/decisions + artifacts: + paths: + - public + only: + variables: + - $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH From 64863ec96cd00abe8bdbe1f9fd8d8d4a07fea3ad Mon Sep 17 00:00:00 2001 From: Kai Kriegel Date: Wed, 5 Jan 2022 18:22:54 +0000 Subject: [PATCH 10/13] try gitbook --- .gitlab-ci.yml | 44 ++++++++++++++++++-------------------------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 63562d2..16d89d3 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,39 +1,31 @@ -# This file is a template, and might need editing before it works on your project. -# To contribute improvements to CI/CD templates, please follow the Development guide at: -# https://docs.gitlab.com/ee/development/cicd/templates.html -# This specific template is located at: -# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Pages/Jekyll.gitlab-ci.yml +# requiring the environment of NodeJS 10 +image: node:10 -# Template project: https://gitlab.com/pages/jekyll -# Docs: https://docs.gitlab.com/ee/pages/ -image: ruby:2.6 - -variables: - JEKYLL_ENV: production - LC_ALL: C.UTF-8 +# add 'node_modules' to cache for speeding up builds +cache: + paths: + - node_modules/ # Node modules and dependencies before_script: - - gem install bundler - - bundle install + - npm install gitbook-cli -g # install gitbook + - gitbook fetch 3.2.3 # fetch final stable version + - gitbook install # add any requested plugins in book.json test: stage: test script: - - bundle exec jekyll build -d test -s docs/decisions - artifacts: - paths: - - test - except: - variables: - - $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH - + - gitbook build ./docs/decisions public # build to public path + rules: + - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH + +# the 'pages' job will deploy and build your site to the 'public' path pages: stage: deploy script: - - bundle exec jekyll build -d public -s docs/decisions + - gitbook build ./docs/decisions public # build to public path artifacts: paths: - public - only: - variables: - - $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + expire_in: 1 week + rules: + - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH From 4925081753926be28fbd287da7e54b15c4db5926 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 19:56:54 +0100 Subject: [PATCH 11/13] correct @kjkriegel's nick --- docs/decisions/0001-require-strong-transport-encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0001-require-strong-transport-encryption.md b/docs/decisions/0001-require-strong-transport-encryption.md index 9e679fe..4fb9c57 100644 --- a/docs/decisions/0001-require-strong-transport-encryption.md +++ b/docs/decisions/0001-require-strong-transport-encryption.md @@ -1,7 +1,7 @@ # Require the use of transport encryption * Status: accepted -* Deciders: @dequbed, @TheJoKlLa, @kjk +* Deciders: @dequbed, @TheJoKlLa, @kjkriegel ## Context and Problem Statement From ae1c762f3ee45b28c6a17d8b12a0a175e75f4b66 Mon Sep 17 00:00:00 2001 From: Kai Jan Kriegel Date: Wed, 5 Jan 2022 20:18:58 +0100 Subject: [PATCH 12/13] Revert "render ADRs via gitlab pages" This reverts commit a9ea6120733afd9d75ba8872faa0c5bb41ff3174. --- .gitlab-ci.yml | 31 ------------------------------- 1 file changed, 31 deletions(-) delete mode 100644 .gitlab-ci.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 16d89d3..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,31 +0,0 @@ -# requiring the environment of NodeJS 10 -image: node:10 - -# add 'node_modules' to cache for speeding up builds -cache: - paths: - - node_modules/ # Node modules and dependencies - -before_script: - - npm install gitbook-cli -g # install gitbook - - gitbook fetch 3.2.3 # fetch final stable version - - gitbook install # add any requested plugins in book.json - -test: - stage: test - script: - - gitbook build ./docs/decisions public # build to public path - rules: - - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH - -# the 'pages' job will deploy and build your site to the 'public' path -pages: - stage: deploy - script: - - gitbook build ./docs/decisions public # build to public path - artifacts: - paths: - - public - expire_in: 1 week - rules: - - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH From 3ccfcc2b35b9fc26fd3b7b9621306889bca9a860 Mon Sep 17 00:00:00 2001 From: Nadja Reitzenstein Date: Wed, 5 Jan 2022 20:20:30 +0100 Subject: [PATCH 13/13] make compile --- connection.capnp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/connection.capnp b/connection.capnp index cf7758b..95349f2 100644 --- a/connection.capnp +++ b/connection.capnp @@ -11,9 +11,9 @@ using MachineSystem = import "machinesystem.capnp".MachineSystem; using UserSystem = import "usersystem.capnp".UserSystem; using PermissionSystem = import "permissionsystem.capnp".PermissionSystem; -const API_VERSION_MAJOR :Int32 = 0; -const API_VERSION_MINOR :Int32 = 3; -const API_VERSION_PATCH :Int32 = 0; +const apiVersionMajor :Int32 = 0; +const apiVersionMinor :Int32 = 3; +const apiVersionPatch :Int32 = 0; struct Version {