Project Capillary: End-to-end encryption for push messaging, simplified

Posted by Giles Hogben, Privacy Engineer and Milinda Perera, Software Engineer

Developers already use HTTPS to communicate with Firebase Cloud Messaging (FCM). The channel between FCM server endpoint and the device is encrypted with SSL over TCP. However, messages are not encrypted end-to-end (E2E) between the developer server and the user device unless developers take special measures.

To this end, we advise developers to use keys generated on the user device to encrypt push messages end-to-end. But implementing such E2E encryption has historically required significant technical knowledge and effort. That is why we are excited to announce the Capillary open source library which greatly simplifies the implementation of E2E-encryption for push messages between developer servers and users' Android devices.

We also added functionality for sending messages that can only be decrypted on devices that have recently been unlocked. This is designed to support decrypting messages on devices using File-Based Encryption (FBE): encrypted messages are cached in Device Encrypted (DE) storage and message decryption keys are stored in Android Keystore, requiring user authentication. This allows developers to specify messages with sensitive content, that remain encrypted in cached form until the user has unlocked and decrypted their device.

The library handles:

• Crypto functionality and key management across all versions of Android back to KitKat (API level 19).
• Key generation and registration workflows.
• Message encryption (on the server) and decryption (on the client).
• Integrity protection to prevent message modification.
• Caching of messages received in unauthenticated contexts to be decrypted and displayed upon device unlock.
• Edge-cases, such as users adding/resetting device lock after installing the app, users resetting app storage, etc.

The library supports both RSA encryption with ECDSA authentication and Web Push encryption, allowing developers to re-use existing server-side code developed for sending E2E-encrypted Web Push messages to browser-based clients.

Along with the library, we are also publishing a demo app (at last, the Google privacy team has its own messaging app!) that uses the library to send E2E-encrypted FCM payloads from a gRPC-based server implementation.

What it's not

• The open source library and demo app are not designed to support peer-to-peer messaging and key exchange. They are designed for developers to send E2E-encrypted push messages from a server to one or more devices. You can protect messages between the developer's server and the destination device, but not directly between devices.
• It is not a comprehensive server-side solution. While core crypto functionality is provided, developers will need to adapt parts of the sample server-side code that are specific to their architecture (for example, message composition, database storage for public keys, etc.)

You can find more technical details describing how we've architected and implemented the library and demo here.