Capillary is a Java library designed to simplify the implementation of end-to-end encrypted push messages from Java application servers to Android clients. It targets developers building secure messaging features, providing robust crypto and key management for Android versions KitKat (API 19) and later, with a focus on handling edge cases and device lock states.

How It Works

Capillary facilitates E2E encryption by managing asymmetric key pairs generated on the Android client. These public keys are registered with the application server, which then encrypts outgoing messages. The Android client decrypts these messages using the corresponding private key. It supports two primary cryptographic approaches: Web Push (ECDH-based, efficient but with Android Keystore limitations) and RSA-ECDSA (hybrid encryption with RSA for confidentiality and ECDSA for integrity, leveraging Android Keystore for private key security). It also offers an "Auth" mode, requiring device unlock for decryption, which is beneficial for sensitive content.

Quick Start & Requirements

• Installation: Add com.google.capillary:lib (server) and com.google.capillary:lib-android (Android) as Maven or Gradle dependencies.
• Prerequisites: Java-based application server, Android client. For RSA-ECDSA, an ECDSA public/private key pair is required, which can be generated using a provided utility script (./gradlew tools:installDist then ./tools/build/install/tools/tools/bin/ecdsa-key-pair-generator). Android Keystore support is required for secure key operations.
• Initialization: Call Config.initialize() in the Android app.
• Documentation: API docs for Java and Android are available for version 1.0.0. A demo application is also provided.

Highlighted Details

• Supports E2E encryption for push messages, including handling device lock states and File-Based Encryption (FBE).
• Offers two cryptographic protocols: Web Push (ECDH) and RSA-ECDSA, with distinct security and efficiency trade-offs.
• Provides client-side key generation, management, and decryption, along with server-side encryption capabilities.
• Enables "Auth" mode to protect sensitive messages when the device is locked.

Maintenance & Community

Maintained by Milinda Perera and Giles Hogben from Google. No community links (Discord/Slack) or roadmap are provided in the README.

Licensing & Compatibility

The library is licensed under the Apache License 2.0, permitting commercial use and integration with closed-source applications.

Limitations & Caveats

The Web Push protocol option has limitations regarding Android Keystore support for ECDH operations, requiring hybrid encryption with an RSA key. The RSA-ECDSA option is less efficient than ECDH. The library provides core crypto functionality; developers must implement server-side key registration, retrieval, and message transmission logic, though a demo application illustrates an FCM-based implementation.