Reordering and content updates

This commit is contained in:
Sarah Jamie Lewis 2021-09-15 13:23:44 -07:00
parent 14951e5305
commit ccd8a61836
6 changed files with 161 additions and 82 deletions

View File

@ -2,23 +2,24 @@
- [Overview and History](./overview.md)
- [Risk Model](./risk.md)
- [Cwtch Technical Basics](./cwtch-overview.md)
- [Open Questions](./open-questions.md)
- [Cwtch Library](./cwtch.md)
- [Cwtch Overview](./cwtch-overview.md)
- [Component Ecosystem Breakdown](./components.md)
- [Message Formats](./message_formats.md)
- [Groups](./groups.md)
- [Tapir](./tapir.md)
- [Packet Format](./packet_format.md)
- [Authentication Protocol](./authentication_protocol.md)
- [Connectivity](./connectivity.md)
- [Cwtch UI](./ui.md)
- [Profile Encryption & Storage](./profile_encryption_and_storage.md)
- [Android Service](./android.md)
- [Message Overlays](./overlays.md)
- [Input](./input.md)
- [Cwtch Servers](./server.md)
- [Key Bundles](./key_bundles.md)
- [Risks](./cwtch-risks.md)
- [Cwtch UI](./ui.md)
- [Profile Encryption & Storage](./profile_encryption_and_storage.md)
- [Android Service](./android.md)
- [Message Overlays](./overlays.md)
- [Input](./input.md)
- [Cwtch Servers](./server.md)
- [Key Bundles](./key_bundles.md)
- [Development](./development.md)
- [Deployment](./deployment.md)
- [Open Questions](./open-questions.md)
- [References](./references.md)

75
src/components.md Normal file
View File

@ -0,0 +1,75 @@
# Component Ecosystem Breakdown
Cwtch is made up of several smaller component libraries. This chapter will provide a brief overview of
each component and how it relates to the wider Cwtch ecosystem.
## [openprivacy/connectivity](https://git.openprivacy.ca/openprivacy/connectivity)
Summary: A library providing an ACN (Anonymous Communication Network ) networking abstraction.
The goal of connectivity is to abstract away the underlying libraries/software needed to communicate with a
specific ACN. Right now we only support Tor and so the job of connectivity is to:
* Start and Stop the Tor Process
* Provide configuration to the Tor process
* Allow raw connections to endpoints via the Tor process (e.g. connect to onion services)
* Host endpoints via the Tor process (e.g. host onion services)
* Provide status updates about the underlying Tor process
For more information see [connectivity](./connectivity.md)
## [cwtch.im/tapir](https://git.openprivacy.ca/cwtch.im/tapir)
Summary: Tapir is a small library for building p2p applications over anonymous communication systems.
The goal of tapir is to abstract away **applications** over a particular ACN. Tapir supports:
* Creating a cryptographic identity (including ephemeral identities)
* Maintaining a connection pool of inbound and outbound connections to services
* Handling various application-layers including cryptographic transcripts, [authentication and authorization protocols](https://docs.openprivacy.ca/cwtch-security-handbook/authentication_protocol.html#authentication-protocol), and
[token-based services via PrivacyPass](https://docs.openprivacy.ca/cwtch-security-handbook/tapir.html#token-app),
For more information see [tapir](./tapir.md)
## [cwtch.im/cwtch](https://git.openprivacy.ca/cwtch.im/cwtch)
Summary: Cwtch is the main library for implementing the cwtch protocol / system.
The goal of cwtch is to provide implementations for cwtch-specific applications e.g.
message sending, groups, and file sharing(implemented as Tapir applications), provide interfaces for managing and storing Cwtch profiles, provide an event bus for subsystem splutting and building plugins with new functionality, in addition to managing other core functionality.
The cwtch library is also responsible for maintaining canonical model representations for wire formats and overlays.
## [cwtch.im/libcwtch-go](https://git.openprivacy.ca/cwtch.im/libcwtch-go)
Summary: libcwtch-go provides C (including Android) bindings for Cwtch for use in UI implementations.
The goal of libcwtch-go is to bridge the gap between the backend cwtch library and any front end systems which
may be written in a different language.
The API provided by libcwtch is much more restricted than the one provided by Cwtch directly, each libcwtch API typically
packages up several calls to Cwtch.
libcwtch-go is also responsible for managing UI settings and experimental gating. It is also often used as a staging ground
for experimental features and code that may eventually end up in Cwtch.
## [cwtch-ui](https://git.openprivacy.ca/cwtch.im/cwtch-ui)
Summary: A flutter based UI for Cwtch.
Cwtch UI uses libcwtch-go to provide a complete UI for Cwtch, allowing people to create and manage profiles,
add contacts and groups, message people, share files (coming soon) and more.
The UI is also responsible for managing localization and translations.
For more information see [Cwtch UI](./ui.md)
## Auxiliary Components
Occasionally, Open Privacy will factor out parts of Cwtch into standalone libraries that are not Cwtch specific.
These are briefly summarized here:
### [openprivacy/log](https://git.openprivacy.ca/openprivacy/log)
An Open Privacy specific logging framework that is used throughout Cwtch packages.

70
src/cwtch-risks.md Normal file
View File

@ -0,0 +1,70 @@
# Risks
## Private information transiting the IPC boundary
**Status: 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.
## Testing Status
Cwtch features one [well-defined integration test](https://openprivacy.ca/discreet-log/06-cwtch-integ-tests/) which exercise the ideal case of
three well-formed peers authenticating and messaging each other through an
untrusted server.
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.
## Resolved or Outdated Risks
### Dependency on Outdated Protobuf Implementation
**Status: Mitigated**
The group features of Cwtch are enabled by an untrusted infrastructure
protcol that was originally 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.
We have removed protobufs entirely from the project by porting this
functionality over the Tapir.
### Proof of Work (PoW) Spam Prevention as a Metadata Vector
**Status: Outdated**: Cwtch now uses Token Based Services to separate challenges like PoW from
resolving the tokens.
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.
## Thread Safety
**Status: Mitigated**
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
code is now tested via unit tests and integration test
running the `-race` flag.

View File

@ -1,70 +1,3 @@
# Cwtch Library
## Private information transiting the IPC boundary
**Status: 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.
## Testing Status
Cwtch features one [well-defined integration test](https://openprivacy.ca/discreet-log/06-cwtch-integ-tests/) which exercise the ideal case of
three well-formed peers authenticating and messaging each other through an
untrusted server.
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.
## Resolved or Outdated Risks
# Cwtch
### Dependency on Outdated Protobuf Implementation
**Status: Mitigated**
The group features of Cwtch are enabled by an untrusted infrastructure
protcol that was originally 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.
We have removed protobufs entirely from the project by porting this
functionality over the Tapir.
### Proof of Work (PoW) Spam Prevention as a Metadata Vector
**Status: Outdated**: Cwtch now uses Token Based Services to separate challenges like PoW from
resolving the tokens.
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.
## Thread Safety
**Status: Mitigated**
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
code is now tested via unit tests and integration test
running the `-race` flag.

View File

@ -10,7 +10,7 @@ compromised then there is nothing in our current process that would detect this.
We need:
* Reproducible Builds - we currently use puplic docker containers for all builds
* Reproducible Builds - we currently use public docker containers for all builds
which should allow anyone to compare distributed builds with ones built from source.
* Signed Releases - Open Privacy does not yet maintain a public record of staff
public keys. This is likely a necessity for signing released builds and

View File

@ -18,8 +18,8 @@ committed to make it as easy as possible to contribute to Cwtch while also
**Status: Mitigated**
Master is currently locked and 3 Open Privacy staff members have permission
to override it, and the responsibility of monitoring changes.
`trunk` is currently locked and only 3 Open Privacy staff members have permission
to override it, in addition the responsibility of monitoring changes.
Further every new pull request and merge triggered automated builds & tests
which trigger emails and audit logs.
@ -28,7 +28,7 @@ The code is also open source and inspectable by anyone.
### Risk: Code Regressions
**Status: Partially Mitgated** (See individual project entries in this
**Status: Partially Mitigated** (See individual project entries in this
handbook for more information)
Our automated pipelines have the ability to catch regressions when that