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/connection.capnp b/connection.capnp index 6ec6ad9..95349f2 100644 --- a/connection.capnp +++ b/connection.capnp @@ -11,13 +11,31 @@ using MachineSystem = import "machinesystem.capnp".MachineSystem; using UserSystem = import "usersystem.capnp".UserSystem; using PermissionSystem = import "permissionsystem.capnp".PermissionSystem; +const apiVersionMajor :Int32 = 0; +const apiVersionMinor :Int32 = 3; +const apiVersionPatch :Int32 = 0; + +struct Version +{ + major @0 :Int32; + minor @1 :Int32; + patch @2 :Int32; +} + interface Bootstrap { - authenticationSystem @0 () -> ( authenticationSystem : AuthenticationSystem ); + getAPIVersion @0 () -> ( version : Version ); - machineSystem @1 () -> ( machineSystem : MachineSystem ); + 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 ); + + machineSystem @3 () -> ( machineSystem : MachineSystem ); - userSystem @2 () -> ( userSystem : UserSystem ); + userSystem @4 () -> ( userSystem : UserSystem ); - permissionSystem @3 () -> ( permissionSystem : PermissionSystem ); + permissionSystem @5 () -> ( permissionSystem : PermissionSystem ); } 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/0001-require-strong-transport-encryption.md b/docs/decisions/0001-require-strong-transport-encryption.md new file mode 100644 index 0000000..4fb9c57 --- /dev/null +++ b/docs/decisions/0001-require-strong-transport-encryption.md @@ -0,0 +1,92 @@ +# Require the use of transport encryption + +* Status: accepted +* Deciders: @dequbed, @TheJoKlLa, @kjkriegel + +## 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 + +* [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 +[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 new file mode 100644 index 0000000..2ab5d0c --- /dev/null +++ b/docs/decisions/index.md @@ -0,0 +1,14 @@ +# 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) +* [ADR-0001](0001-require-strong-transport-encryption.md) - Require the use of transport encryption + + + +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] +* … 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") {