Tapir, Cwtch, Cwtch UI Risk Sketches

book.toml

@@ -4,3 +4,6 @@ language = "en"
 multilingual = false
 src = "./src"
 title = "Cwtch Secure Development Handbook"
+
+[output.html]
+mathjax-support = true

src/cwtch.md

@@ -1 +1,73 @@
 # Cwtch Library
+
+# Known Risks
+
+## Dependency on Outdated Protobuf Implementation
+
+**Status: Partially Mitigated (Work in Progress)**
+
+The group features of Cwtch are enabled by an untrusted infrastructure
+protcol that is implemented using the older ricochet-based channels. The go
+code that was generated from these channels no longer works given the newest
+version of the protobufs framework.
+
+The goal is to remove protobufs entirely from the project by porting this
+functionality over the Tapir, once a suitable replacement protocol has been
+defined.
+
+## Thread Safety 
+
+**Status: Partially Mitigated (Work in Progress)**
+
+The Cwtch library evolved from a prototype that had weak checks around
+concurrency and the addition of singleton behavior around saving profiles to
+files and protocol engines resulted in race conditions.
+
+The inclusion of the `Event Bus` made handling such cases easier, and the
+majority of the code is now tested via unit tests and integration test
+running the `-race` flag. The last portion of the code that requires work in
+this regard are around the AppBridge and Server which are used by the UI to
+maintain separation.  
+
+## Private information transiting the IPC boundary
+
+**Status: Unmitigated (Requires privileged user to exploit)** 
+
+Information used to derive the encryption key used to save all sensitive data to
+the file system cross the boundary between the UI front-end and the App backend.
+
+Intercepting this information requires a privileged position on the local
+machine. There are currently no plans to mitigate this issue.
+
+## PoW Spam Prevention as a Metadata Vector
+
+**Status: Speculative** 
+
+Processing capabilities are not constant, and so a malicious server could perform
+ some correlations/fiddle with difficulty per connection in an attempt to identify
+  connections over time.
+
+Needs some statistical experimentation to quantify, but given the existing 
+research detecting timeskews over Tor I wouldn't be surprised if this could be derived.
+
+As for mitigation: Adding a random time skew might be an option,some defense 
+against the server adjusting difficulty too often would also mitigate some of 
+the more extreme vectors.
+
+Additionally, Token Based Services and Peer-based Groups are both potential
+ options for eliminating this attack vector entirely.
+ 
+ 
+## Testing Status
+
+Cwtch features one well-defined integration test which exercise the ideal case of
+three well-formed peers authenticating and messaging each other through an
+untrusted server.
+
+In addition, unit tests are defined for a number of Cwtch modules, however
+ many of them have become outdated with the introduction of Tapir.
+
+Most tests are run with the `-race` flag which will cause them to fail if
+race conditions are detected. 
+
+Both integration tests and unit tests are run automatically for every pull request and main branch merge.

src/tapir.md

@@ -1 +1,86 @@
 # Tapir
+
+Designed to replace the old protobuf-based ricochet channels, Tapir provides a 
+framework for building anonymous applications.
+
+It is divided into a number of layers:
+
+* Identity - An ed25519 keypair, required for established a Tor v3 onion service
+and used to maintain a consistent cryptographic identity for a peer.
+* Connections - The raw networking protocol that connects two peers. Connections
+are so far only defined over Tor v3 Onion Services (see: [connectivity](./connectivity.md))
+* Applications - The various logic that enables a particular information flow
+over a connection. Examples include shared cryptographic transcripts
+, authentication, spam guards and token based services. Applications provide
+**Capabilities** which can be referenced by other applications to determine if
+a given peer has the ability to use a given hosted application.
+* Application Stacks - A mechanism for connecting more than one application
+together, e.g. authentication depends on a shared cryptographic transcript
+, and the main [cwtch](./cwtch.md) peer app is based on the authentication
+application.
+
+## Known Risks  
+
+### Impersonation of Peers
+
+**Status: Mitigated** 
+
+By default, tor v3 onion services only provide one-way authentication, that
+is the client can verify a metadata resistant connection to the server by the
+server obtained no information about the client.
+
+Tapir provides a peer-to-peer interface over this client-server structure
+through the [Authentication application](https://git.openprivacy.ca/cwtch.im/tapir/src/branch/master/applications/auth.go).
+
+The Authentication application implements a 3-way, ephemeral diffie-hellman
+handshake to generate a shared session key. Once generated this session key is
+used to encrypt *all* traffic between the two peers for the duration of the
+session.
+
+The session key is used to encrypt a challenge derived from the shared
+cryptographic transcript (based on [merlin](https://merlin.cool))
+
+Only if all the above checks pass is the connection maintained open - otherwise
+the peer that detects a failure closes the connection.
+
+### Double Connections
+
+**Status: Mitigated** 
+
+Because of the one-way authentication provided by Tor onion services there is a 
+window between connection instantiation and the finalization of authentication
+when two valid connections can occur between the same two peers.
+
+While these vestigial connections are not harmful, they do have the potential to
+confuse users and interfaces. To avoid ambiguity Tapir attempt to detect and
+close duplicate connections through a number of rules:
+
+1. If a connection open is attempted to a hostname that
+already has an open connection the connection attempt is aborted.
+2. After authentication the lookup happens again, and if another connection is
+found the newest connection is closed.
+
+There is a small chance both peers will close their initiated connections
+if they also happen to start the connection attempt at exactly the sametime
+. This should be exceedingly rare in practice, and is further mitigated by
+an exponential backoff of connection retries by the [ui](./ui.md)
+
+Finally, the Tapir interfaces `WaitForCapabilityOrClose` and `GetConnection` are
+aware of the potential for duplicate connections and have logic that allows the
+handling of such instances (such as returning an error when they are found
+allowing a handling application to retry the request if a connection with a
+given capability isn't returned)
+
+## Testing Status
+
+Tapir features a number of well-defined integration tests which exercise not
+only the ideal case of two well-formed peers authenticating and messaging each
+other, but also a malicious peer attempting to bypass authentication.
+
+In addition, unit tests are defined for a number of the specified
+applications (including Authentication) and many of the
+cryptographic primitives.
+
+All tests are also run with the `-race` flag which will cause them to fail if
+race conditions are detected. Both integration tests and unit tests are run
+ automatically for every pull request and main branch merge.

src/ui.md

@@ -1 +1,47 @@
 # Cwtch UI
+
+The UI is built on [therecipe/qt](https://github.com/therecipe/qt) which
+ links in Qt libraries.
+
+# Known Risks
+
+## Deanonymization through Content Injection
+
+**Status: Mitigated in several places** 
+
+Like most UI frameworks, QML provides a HTML rendering engine with the potential
+to make requests through remote resource loading. Any kind of malicious content
+injection is therefore elevated to a critical deanonymization risk.
+
+To mitigate such a risk we do the following:
+
+* Maintain our own UI library that explicitly relies on PlainText fields to
+ handle all content (and thus styled safely)
+* Mediate all Cwtch api networking calls through Tor
+* Force QML to use a deliberately broken network resolver that is incapable of
+resolving remote content
+* Frequently test the UI for potential content injection vulnerabilities.
+
+While none of these mitigations should be assumed robust by themselves, the
+combination of them should be sufficient to prevent such attacks.
+
+## Denial of Service through Spamming
+
+**Status: Partially Mitigated** 
+
+There is currently no limitation on the number of messages that can be sent
+to a Cwtch server or by a Cwtch peer. Each message requires process and is
+added to the UI if valid. 
+
+We have put in work to ensure that an influx of messages does not degrade the
+app experience, however it will result in an increase in network badwidth which
+may be intolerable or undesired for many people - especially those on metered
+ connections (e.g. cellphone data plans)
+ 
+In order to be suitable to deploy groups at a wide scale, the app require a way
+to prevent Cwtch from fetching information over such connections, and this
+should likely be turned on by default.
+
+## Testing Status 
+
+The UI is currently only subject to manual testing.