Annotated Signal Documentation

Context

The purpose of this resource is to bridge the gap between the Signal documentation available on the company’s website (see) and the code base libsignal implementing the Signal protocol. These documents focus on SPQR (ML-KEM Braid) and the PQXDH protocols and are pinned to specific commits in libsignal’s commit history. As such, a lot of the documentation here are forks of the original Signal documents with annotations pointing to the relevant code lines in libsignal. We additionally added helpful text that fleshes out some of the implementation and security details (e.g., key storage lifetime, specific versions of KEM used, where state transitions happen in the code, etc.) to help the reader understand how Signal implements its protocol. Finally, thanks to our experience answering questions about the Signal protocol and its implementation, and thanks to the help of the Signal folks themselves, we created an original resource that explains what the Triple Ratchet is and how PQXDH, SPQR and the Double Ratchet interact with each other.

We hope that this resource will both be a good pedagogic source as well as a useful tool to the research cryptography and security community at large. We love Signal and want to make sure that they get all the help and support that they can and need! We hope to get more funding in the future to keep these docs up to date.

If you have any questions and feedback feel free to send us an email at [e-mail]. We have reviewed this document to the best of our ability, but may have missed some things that we are happy to rectify or add!

This resource was created by Rawane Issa and edited by Andrew Shaughnessy. No AI was used in writing this document!