Discreet Log #16: Cwtch Secure Development Handbook

17 Sep 2021


Welcome to Discreet Log! A fortnightly technical development blog to provide an in-depth look into the research, projects and tools that we work on at Open Privacy. For our 16th edition Sarah Jamie Lewis talks about recent updates to the Cwtch Secure Development Handbook.


Over the years Cwtch has evolved from a single codebase proof-of-concept to an ecosystem that spans several subcomponents, historical and current UI front-ends, platform-specific code and multiple language bindings (more on that in a few weeks).

Keeping track of the privacy and security risks, mitigations and concerns in addition to all the other complexity is a job that is too big for any one codebase, issue tracker or wiki. That is why, a few years ago, I started maintaining the Cwtch Secure Development Handbook.

Recently the handbook has undergone a few updates, and that is what I want to talk about this week.

History of the Handbook

The handbook started as an external reference for known and mitigated risks in the Cwtch ecosystem. Known risks are accepted limitations of the system e.g. the reliance on an external Tor process having access to Cwtch private keys to host onion v3 services. Mitigated risks were previously documented risks that we had either resolved or put additional steps in place to prevent exploitation e.g. the removal of outdated library dependencies as Cwtch moved from a prototype to a complete system.

As people have started trying out Cwtch and volunteering the scope of the handbook increased. Sections were added to document cryptographic protocols used in Cwtch, and a break down of libraries and packages, in addition to a history of Cwtch and prior work in the field of metadata resistant messaging.

New Updates

One big problem with the technical handbook was that it made many assumptions regarding the knowledge that a reader possessed about Cwtch. This worked fine when the handbook was a reference for core developers, but works less well now that we are onboarding volunteer developers, community translators and casual testers.

I want to extend a big thank you to @kngako for spending time to read through the handbook and provide fixes and suggestions for sections to add to lower the barrier to entry to understanding Cwtch.

Thanks to those suggestions the handbook now has several new sections including:

As ever, if you’d like to support Open Privacy’s efforts to develop Cwtch and bring open source metadata-resistant and privacy-first infrastructure to marginalized communities, please consider donating.

What is Discreet Log?

Discreet Log is a fortnightly technical development blog to give a more in-depth look at the research, projects and tools that we work on at Open Privacy.

More Discreet Log

Donate to Open Privacy



Open Privacy is an incorporated non-profit society in British Columbia, Canada. Donations are not tax deductible. You can Donate Once via Bitcoin, Monero, Zcash, and Paypal, or you can Donate Monthly via Patreon or Paypal. Please contact us to arrange a donation by other methods.