Documentation

<- Back to documentation

CopperheadOS usage guide

This is a placeholder for ongoing work on a CopperheadOS usage guide, covering how to make use of the security features, details on properly leveraging the existing user-facing Android security features and alternatives to Google Play Services.

Updates on Pixel and Pixel XL phones

The update system implements automatic background updates. It checks for updates once per hour when there’s network connectivity and then downloads and installs updates in the background. It will pick up where it left off if downloads are interrupted, so you don’t need to worry about interrupting it. Similarly, interrupting the installation isn’t a risk because updates are installed to a secondary installation of CopperheadOS which only becomes the active installation after the update is complete. Once the update is complete, you’ll be informed with a notification and simply need to reboot with the button in the notification or via a normal reboot. If the new version fails to boot, the OS will roll back to the past version and the updater will attempt to download and install the update again.

The updater will use incremental updates to download only changes rather than the whole OS unless the current version is behind the current release by more than 3 versions. As long as you have working network connectivity on a regular basis and reboot when asked, you’ll almost always be on one of the past couple versions of the OS which will minimize bandwidth usage since incrementals will always be available. If you fall more than 3 versions behind, a large full update shipping the full OS so it can update from any version will be downloaded instead.

The updater works while the device is locked / idle, including before the first unlock since it’s explicitly designed to be able to run before decryption of user data.

Settings

The settings are available in the Settings app in About device -> System updates.

The “Release channel” setting can be changed from the default Stable channel to the Beta channel if you want to help with testing. The Beta channel will usually simply follow the Stable channel, but the Beta channel may be used to experiment with new features.

The “Permitted networks” setting controls which networks will be used to perform updates. It defaults to using any network connection. It can be set to “Non-roaming” to disable it when the cellular service is marked as roaming or “Unmetered” to disable it on cellular networks and also WiFi networks marked as metered.

Enabling the opt-in “Automatic reboot” setting allows the updater to reboot the device after an update once it has been idle for a long time. When this setting is enabled, a device can take care of any number of updates completely automatically even if it’s left completely idle.

App recommendations

Messaging

Recommended messaging app preference list:

  1. Conversations + OMEMO
  2. Conversations + OTR to communicate with users on XMPP clients without OMEMO
  3. Noise to communicate with Signal users
  4. Silence encrypted SMS to communicate with Android users without data connections
  5. Other apps with end-to-end encryption if you can’t convince contacts to install one of the above (Wire, WhatsApp, etc.)
  6. Apps with transport encryption without end-to-end encryption
  7. Unencrypted SMS or apps without transport encryption

Conversations

The recommended messaging client is Conversations. It’s an XMPP client interoperable with other XMPP clients and servers. It supports end-to-end encryption via robust cryptography (OMEMO) based on the Signal protocol along with OTR and PGP for backwards compatibility with lesser clients. It’s one of very few apps with efficient push messaging without needing Google Cloud Messaging (GCM). It also supports end-to-end encrypted group chat.

Conversations has an official XMPP server with all of the necessary extensions for full functionality. It costs 8 EUR / year after the 6 month free trial. Using the official server to support the project is recommended, but there are other options without a subscription fee. We don’t currently have a recommendation about which ones to prefer, beyond sticking to those with support for every XEP other than XEP-0357 (which is for GCM, rather than the standard push mechanism).

Signal

Noise, a rebranded build of Signal available outside the Play Store is available in the Copperhead F-Droid repository. It has full support for all of the Signal features including voice and video calls but it isn’t optimized for low impact on battery life like Conversations. It used to be a fork removing the hard dependency on Google Play Services but since Signal 3.30.0 that is not a hard dependency anymore.

The Copperhead F-Droid repository is enabled by default for fresh CopperheadOS installations, but can also be manually added:

  • Repository URL: https://fdroid.copperhead.co/repo
  • Repository fingerprint: F0D4EB1193AD82FEB224BD1174B6FBD89A39D8ED988C9FFF2ADD0DCD1C4E271B

Note that the app builds in this repository are intended for CopperheadOS. You’re free to use them elsewhere, but the builds will end up leveraging CopperheadOS features in the future and will become incompatible with other operating systems. There is little reason to use Noise if you have Google Play because Noise is now simply a rebrand of the same code as Signal.

Silence

CopperheadOS replaces the AOSP Messaging app with Silence to provide support for encrypted SMS. It isn’t really recommended to prefer it over data-based encrypted messaging apps, but rather to make use of it for communicating with contacts without data connections, or for all messaging if you don’t have a data connection yourself. It makes sense to leave it as the default SMS app even if you’re using an app like Noise able to act as the default SMS client.

WhatsApp

WhatsApp works on CopperheadOS, but it isn’t currently available in a convenient way. The best way to use it is probably installing the Amazon Appstore as an apk and then installing it from there, so that you have updates for it along with the Appstore which will update itself.

We might consider trying to convince Facebook to either host an F-Droid repository or permit redistribution of it.

Maps

OsmAnd (OpenStreetMap Automated Navigation Directions) can be installed from F-Droid and provides map viewing and mobile navigation. It has the killer feature of optional support for downloading the OpenStreetMap database for chosen regions. In addition to the obvious advantage of not having a dependency on an internet connection, offline mapping offers more privacy. It’s recommended to use the offline mode if you have enough storage space to spare. Note that it’s important to configure OsmAnd to use the internal storage directory: go into the menu, then Settings, General settings, select the “Data storage folder” option, select the edit button and set it to the “Internal application memory” option.

If you really need Google Maps, you can use their web application. It’s not as nice as the mobile app but the core functionality is all there.

Advanced camera features

Install the Open Camera app from F-Droid and enable “Use Camera2 API” in the settings menu. This enables support for features like manual ISO configuration and HDR mode.

Storage

Apps have their own private storage directories and can share files with other apps using content providers. Apps can act as storage providers to provide structured requests to retrieve and store data including for the shared storage directory. Direct scoped access can also be requested for the shared storage directory (since 7.0). Unfortunately, many apps require the storage permissions for direct, full access to shared storage so it’s unwise to store sensitive data there.

In the future, CopperheadOS will offer the ability to isolate shared storage rather than toggling access. Isolated shared storage will provide an app with a dedicated shared storage directory accessible only to themselves and the built-in file manager. Ideally, apps would already use the available tools to provide this kind of functionality on their own.

File management

The built-in file manager for shared storage is accessible via Settings -> Storage -> Explore and is recommended. It will be the only app able to access isolated shared storage directories of other apps once that feature is implemented.