diff --git a/docs/decisions/0000-use-markdown-architectural-decision-records.md b/docs/decisions/0000-use-markdown-architectural-decision-records.md deleted file mode 100644 index 428218e..0000000 --- a/docs/decisions/0000-use-markdown-architectural-decision-records.md +++ /dev/null @@ -1,22 +0,0 @@ -# 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 deleted file mode 100644 index 4fb9c57..0000000 --- a/docs/decisions/0001-require-strong-transport-encryption.md +++ /dev/null @@ -1,92 +0,0 @@ -# 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 deleted file mode 100644 index 2ab5d0c..0000000 --- a/docs/decisions/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# 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 deleted file mode 100644 index 25696bb..0000000 --- a/docs/decisions/template.md +++ /dev/null @@ -1,72 +0,0 @@ -# [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] -* …