Documentation

<- Back to documentation

CopperheadOS usage guide

CopperheadOS makes many privacy and security enhancements to Android and whenever possible those changes are unobtrusive and ideally invisible to end users. This usage guide aims to document the tiny minority of the changes where the changes have an impact on a user of the operating system along with best practices for using CopperheadOS. It’s currently in a very early form and will grow more broader and more in-depth over time.

Permission model

CopperheadOS and stock Android use the same runtime permission model for apps targeting the modern Android platform. Dangerous permission groups (camera, contacts, microphone, etc.) are disabled by default and apps need to request them from the user as needed with the expectation that they attempt to handle not getting the permissions. The dangerous permission groups can also be toggled via Settings -> Apps -> App name -> Permissions and modern apps can be expected to handle this and request the permissions again as needed.

For apps targeting old versions of the Android platform, stock Android grants all requested dangerous permissions at install time. The dangerous permission groups can still be toggled off via Settings -> Apps -> App name -> Permissions and provide empty data where possible rather than failing for compatibility. By contrast, CopperheadOS presents the user with a menu where they can review and disable dangerous permission groups before the app is able to run. The substantial difference is that stock Android doesn’t give the user a chance to toggle off permissions before the app is able to run. Installing it and toggling them off before manually launching the app is not adequate as it’s possible for it to be started before that.

Note that Android makes it possible for apps to get by without permissions in most cases. An app can have the user pick a contact, take a picture, store / open a file in a storage provider, etc. without any permissions required. Be skeptical about the justification given by app developers for their permission usage. For example, many claim to need to read the phone state (Phone permission group) to detect an active phone call but it’s almost always a false justification as they could be using the standard audio focus mechanism.

Network permission

Unlike stock Android, CopperheadOS treats full network access as a user-facing permission with a toggle. For compatibility, it’s enabled by default for apps targeting the modern Android platform unlike other runtime permissions.

There are many known cases of apps exporting interfaces to other apps for making limited network requests, so this toggle will become more useful when further isolation options are available. For example, web browsers almost all expose an interface allowing other apps to open URLs and choose not to require either the INTERNET permission or explicit user consent before making the request.

Background clipboard access

CopperheadOS disables access to the clipboard by apps in the background by default. This can be toggled back on via Settings -> Security -> Allow background clipboard access to use apps like clipboard managers. In the future, there will be a fine-grained toggle.

USB peripherals

CopperheadOS defaults to ignoring connected USB peripherals if the screen is locked. This can be controlled in Settings -> Security -> Device security -> USB accessories. The options are:

  1. Disallow new USB peripherals
  2. Allow new USB peripherals when unlocked (default)
  3. Allow new USB peripherals (like stock Android)

This option has no impact on the device acting as a USB peripheral itself when connected to a computer. However, Android already defaults to charge only mode and requires explicit opt-in to the device exposing itself as an MTP, PTP or MIDI device.

Experimental LTE only mode

If you have a reliable LTE connection from your carrier, you can reduce attack surface by disabling 2G / 3G connectivity in Settings -> Wireless & networks -> More -> Cellular networks -> Preferred network type. Note that traditional voice calls won’t work unless you have working VoLTE support on CopperheadOS with your carrier.

Network connection information / statistics

CopperheadOS prevents third party apps from obtaining detailed network information without any permissions as they can on stock Android. The Net Monitor app is built into CopperheadOS and has a special exception from this rule. Network information can also be accessed via the Android Debug Bridge shell. Third party apps can only access information that’s made explicitly available via documented interfaces with permission controls and there’s essentially no access to it right now as valid use cases for it by third party apps not covered by Net Monitor haven’t been presented. The only known examples of using the information in good faith haven’t been correct, such as the attempts to implement a user-facing firewall via a VPN service rather than properly integrated via the existing OS firewall infrastructure so that it actually works properly.

App spawning time

You may notice that cold start app spawning time takes a bit longer (i.e. in the ballpark of 200ms) than stock Android due to security centric exec spawning feature. This is most noticeable on the Nexus 5X due to it being the slowest supported device and is far less significant on current generation hardware. It doesn’t cause any performance cost after launching an app, and similarly doesn’t cause any extra latency if the app was already running / cached in the background.

Updates on Pixel 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, it will download 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.

Update security

The update server isn’t a trusted party since updates are signed and verified along with downgrade attacks being prevented. The update protocol doesn’t send identifiable information to the update server and works well over a VPN / Tor. Copperhead isn’t able to comply with a government order to build, sign and ship a malicious update to a specific user’s device based on information like the IMEI, serial number, etc. The update server only ends up knowing the IP address used to connect to it and the version being upgraded from based on the requested incremental.

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.

Authentication / encryption

Using a strong passphrase is recommended. CopperheadOS extends the arbitrary default maximum passphrase length from 16 characters to 64 characters.

Pattern unlock is strongly discouraged and may be turned into a hidden option in the future.

Fingerprint unlock acts as an extremely convenient secondary unlock mechanism. However, it opens up weaknesses compared to knowledge-based authentication. It’s not usable after a reboot for the first unlock or after 48 hours and it doesn’t reduce authentication or encryption security in those cases. It has the important redeeming quality of making a strong passphrase as the main unlock mechanism very convenient and the placement of the scanner can make it even more convenient than swipe to unlock or even the no unlock mechanism option (i.e. power button only).

The long-term plan for CopperheadOS is to build upon fingerprint unlock by adding support for setting an optional knowledge-based 2nd factor. Once that’s implemented, the only recommended authentication setups will be the following, from strongest to weakest:

  1. Strong passphrase
  2. Strong passphrase with fingerprint + PIN (or weaker passphrase) as a secondary unlock mechanism
  3. Strong passphrase with fingerprint as a secondary unlock mechanism

Until it’s implemented, using a PIN or a weak passphrase instead of the second option can make sense. It’s much weaker in the case where fingerprint unlock isn’t available, i.e. after a reboot or the 48 hour timeout.

CopperheadOS supports randomizing the PIN entry layout via a toggle in Settings -> Security -> Passwords -> Scramble PIN layout, which is disabled by default. This will apply to the planned 2nd factor fingerprint unlock mechanism in addition to using a PIN as the main unlock method, which will be discouraged once there’s a better option available.

F-Droid repository

The CopperheadOS F-Droid repository is included in the default set. For reference:

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

It’s only intended to be useful to CopperheadOS users. Nothing from there is guaranteed to work elsewhere and issues on other operating systems should not be reported.

App recommendations

Browsing

CopperheadOS ships hardened builds of Chromium and the robust rendering sandbox makes it the most secure option available. Since the Android WebView is provided by Chromium, most apps render web content using the CopperheadOS Chromium builds. For example, DuckDuckGo uses the WebView in their search app and the CopperheadOS PDF Viewer uses it to render PDF documents. CopperheadOS enables the rendering sandbox for the WebView since Android Nougat and Google will be enabling it with Android O, but the standalone browser sandbox is currently more restrictive. The WebView is also at the mercy of the security of the app using it, since apps can add their own interfaces and can grant access to the same files and other content they can access outside of the WebView.

Brave is based on Chromium with additional features like built-in ad-blocking, HTTPS Everywhere and fingerprinting protection. However, it’s not currently available in the main F-Droid repository and would be missing the extra hardening. In the near future, we’ll likely provide hardened builds of Brave for CopperheadOS via our F-Droid repository.

Avoid Gecko-based browsers like Firefox. Firefox Focus currently uses the system WebView rather than Gecko but Mozilla plans to change that. They’re significantly less secure and are among the few apps not able to benefit from the full set of CopperheadOS hardening features due to shipping their own linker and custom JIT compiler within the app process. The WebView is inherently Chromium-based so using Gecko also means exposing the attack surface of two browser engines rather than one.

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.

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.

Note that OsmAnd sends the semi-persistent ANDROID_ID to their server on connections. ANDROID_ID will become less identifying in future CopperheadOS releases by default and further user control will be offered, but it reflects poorly on OsmAnd.

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.