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.

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 & notifications -> App info -> App name -> Permissions and modern apps can be expected to handle this and request the permissions again as needed. Dangerous permission groups can also be audited / toggled by group instead of by app using Settings -> Apps & notifications -> App permissions.

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 & notifications -> App info -> 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.

Serial number

CopperheadOS requires that apps have the Phone permission group (read phone state) to access the serial number just like the IMEI on stock Android. Android is moving towards this but doesn’t yet enforce it even for apps targeting Android Oreo.

Display over other apps

Unlike stock Android, CopperheadOS doesn’t permit any automatic grants of the special “Display over other apps” permission. It needs to be very explicitly granted by users.

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 recommended. It’s available as the Files app on the home screen and is also accessible via Settings -> Storage -> Files. Shared storage can be shown by enabling by “Show internal storage” in the app menu. It has proper integration with storage providers (apps providing storage to other apps, with explicit user control) and external storage. It will also be the only app able to access isolated shared storage directories of other apps once that feature is implemented.

Force always on Tor / VPN

In Settings -> Network & Internet -> VPN, the gear icon next to installed VPN apps like Orbot (Tor) can be used to set one as an “Always-on VPN” to make it start automatically. However, it’s also necessary to toggle on “Block connections without VPN” to disallow connections being made if the VPN dies. This will be enabled by default for an “Always-on VPN” on CopperheadOS in the near future.

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 & Location -> Allow background clipboard access to use apps like clipboard managers. In the future, there will be a fine-grained toggle.

Native debugging

Support for native debugging features can be disabled by toggling off Settings -> Security & Location -> Enable native code debugging. It’s left enabled by default like stock in order to generate useful logs and crash dump information from crashes tied to bugs in native code. Disabling it will make the information generated by the ‘Take bug report’ feature nearly useless for crashes caused by native code but it will still produce useful information for uncaught Java exceptions. There are currently no known app compatibility issues caused by disabling this, but it isn’t compatible with some nasty tricks used by obfuscated apps to make themselves harder to inspect.

USB peripherals

CopperheadOS defaults to ignoring connected USB peripherals if the screen is locked. This can be controlled in Settings -> Security & Location -> 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.

Camera on lockscreen

CopperheadOS adds a toggle at Settings -> Security & Location -> Camera on lockscreen for reducing lockscreen attack surface by disallowing camera usage. It disables both the camera launch icon in the lower right corner of the lockscreen and camera launch gestures while locked.

Quick Settings restrictions

CopperheadOS restricts usage of sensitive Quick Settings tiles while the screen is securely locked.

The following Quick Settings tiles have an unlocking requirement in stock Android:

  • Cast
  • Location

CopperheadOS extends this requirement to more tiles:

  • Bluetooth
  • NFC (not present as a tile in stock)
  • Airplane mode
  • WiFi
  • Auto-rotate
  • Data Saver
  • Hotspot
  • Cellular data
  • Battery

Some tiles still have no unlocking requirement:

  • Flashlight
  • Night Light
  • Invert colors
  • Do not disturb
  • Work

The ‘Flashlight’ tile is quite useful from the lockscreen and adds minimal attack surface.

‘Night Light’ and ‘Invert colors’ are comparable to the brightness slider. They add minimal attack surface and are easy to notice and toggle off. Similarly, ‘Do not disturb’ (DND) is comparable to the volume rocker which works while locked and both are quite useful functionality to have there. The volume rocker already allows setting the ‘Alarms only’ DND mode too.

Android for Work isn’t currently in scope for CopperheadOS hardening and the Work tile isn’t available when it’s not in use, so it has been left as is. Android for Work isn’t aimed at businesses deploying dedicated work devices but rather Bring Your Own Device (BYOD).

WiFi scanning

MAC randomization is always enabled for WiFi scanning. The Nexus 5X, Pixel and Pixel XL have fairly unique firmware support for scanning MAC randomization going above and beyond the usual implementation. On most other devices, there are identifiers exposed by WiFi scanning beyond the MAC address such as the packet sequence number and assorted identifying information in the probe requests.

WiFi scanning is never performed when WiFi is disabled without explicitly enabling it in Settings -> Security & Location -> Location -> Scanning, unlike stock Android. The same thing applies to Bluetooth.

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 -> Network & Internet -> Mobile network -> Preferred network type. Traditional voice calls will only work in the LTE only mode if you have either an LTE connection and VoLTE (Voice over LTE) support or a WiFi connection and VoWiFi (Voice over WiFi) support. VoLTE / VoWiFi on Pixel phones is expected to work on all carriers where it’s supported on stock (T-Mobile, Rogers, Fido, etc.) other than Verizon. VoLTE / VoWiFI compatibility is substantially worse on Nexus devices for now.

This feature is not intended to improve the confidentiality of traditional calls and texts, but may somewhat raise the bar for some forms of interception. It’s not a substitute for end-to-end encrypted calls / texts or even transport layer encryption. LTE does provide basic network authentication / encryption but it’s for the network itself. The intention of the LTE only feature is only hardening against remote exploitation by disabling an enormous amount of legacy code.

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 100ms) 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.

Settings

The settings are available in the Settings app in System -> About phone -> Update settings.

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.

The “Require battery above warning level” setting controls whether updates will only be performed when the battery is above the level where the warning message is shown. The standard value is at 15% capacity.

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.

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.

Android updates support serialno constraints to make them validate only on a certain device but CopperheadOS rejects any update with a serialno constraint for both the Stable and Beta channels.

Disabling updates

It’s highly recommended to leave automatic updates enabled and to configure the permitted networks if the bandwidth usage is a problem on your mobile data connection. However, it’s possible to turn off the update client by going to Settings -> Apps, enabling Show system via the menu, selecting CopperheadOS Updater and disabling the app. If you do this, you’ll need to remember to enable it again to start receiving updates.

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 & Location -> 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.

Fingerprint unlock attempts

CopperheadOS disables fingerprint unlock after 5 failed attempts, unlike stock Android which allows 20 attempts with 30 second delays after each 5 failed attempts.

You can use this to disable the fingerprint scanner by intentionally making invalid unlocking attempts. The device will vibrate on invalid unlocking attempts and will stop vibrating once fingerprint unlock has been disabled.

Keyboard personalized suggestions

The keyboard has the option of maintaining an internal database to improve suggestions based on past input. It’s entirely local and inaccessible to any other apps like all internal app data, but CopperheadOS disables it by default to avoid gathering persistent statistics about user input that may be valuable to an attacker that has compromised the device. It can be enabled again in Settings -> Languages & input -> Virtual keyboard -> Android Keyboard (AOSP) -> Text correction -> Personalized suggestions, which is also accessible by holding the comma key on the keyboard and pressing Android Keyboard Settings (AOSP).

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

Built-in user-facing apps

CopperheadOS includes most of the standard Android Open Source Project (AOSP) apps.

The following apps are actively developed as part of AOSP and receive both bug fixes and new features. These are the only AOSP apps that can be considered recommended by CopperheadOS:

  • Calculator
  • Clock
  • Contacts
  • Downloads
  • Phone
  • Settings

The following apps are no longer actively developed as part of AOSP and only receive important security fixes. These apps will keep working indefinitely since Android is backwards compatible but they won’t receive new features or overhauls. These are candidates for replacement down the road, but the replacements need to be a good fit for CopperheadOS:

  • Camera
  • Email
  • Gallery
  • Music
  • Search (launcher icon is removed in CopperheadOS, but it’s included for compatibility)

Some of the AOSP apps have been replaced in CopperheadOS:

  • Calendar -> Etar (maintained derivative of the backend-agnostic AOSP Calendar app, can be used with any service exposing a calendar backend via an app)
  • Browser -> Chromium (hardened browser developed by CopperheadOS based on Chromium, see the section on browsing)
  • Messaging -> Silence (replaced to provide end-to-end SMS encryption)

CopperheadOS also includes some additional built-in apps. These apps are included to provide functionality missing in AOSP compared to stock Android or in the case of Net Monitor because it can’t work if it’s not integrated with the OS due to CopperheadOS privacy enhancements.

  • F-Droid: app repositories and updates
  • Offline Calendar: local calendar storage backend as an alternative to cloud-based backends
  • Net Monitor: monitoring network connections
  • PDF Viewer: hardened PDF viewer developed as part of CopperheadOS

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 future, we’ll likely provide hardened builds of Brave for CopperheadOS via our F-Droid repository.

Avoid Gecko-based browsers like Firefox. 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. Firefox Focus currently uses the system WebView rather than Gecko but Mozilla plans to change that.

Red shift

On Pixels, use Settings -> Display -> Night Light instead of a third party app requiring a grant of the special “Display over other apps” permission.

Messaging

Recommended messaging app preference list:

  1. Conversations + OMEMO
  2. Noise to communicate with Signal users and for encrypted calls
  3. Conversations + OTR to communicate with users on XMPP clients without OMEMO if they won’t adopt Signal or an OMEMO client
  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

Functionality rich

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.

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.

Simpler with better usability

maps.me is an alternative with a far better user interface than OSMand, but with fewer features. Unfortunately, it’s not available on F-Droid per the wishes of the app devs. Note that it has analytics but they can be disabled in the settings. An apk download is available on their site which unfortunately requires enabling unknown sources (at least temporarily) and automatic updates aren’t available. There’s also no way to have it use internal app storage instead of using shared storage for internal app data like settings and map downloads.

Google maps

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 other than turn-by-turn navigation is 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.

Uber

Use https://m.uber.com/ instead of the Android app. Open it with Chromium and select ‘Add to Home screen’ from the menu. Unlike most sites, the Uber web app is set up to act as a standalone app when added to the home screen rather than the launcher only acting as a bookmark and opening a Chromium tab. The map isn’t enabled by default since the web app is aimed at the niche of users with low bandwidth but it can be enabled.

Verified boot fingerprint

The bootloader will display a notice with the fingerprint of the verified boot key since it isn’t the built-in OEM key. Current devices attempt to use the TEE to prevent the key from being changed, but the implementation has limitations and there is some value in manually confirming it.

  • Nexus 5X fingerprint: 0AA1-7043-4D5F
  • Nexus 6P fingerprint: 965E-780B-32FC-B686

As of Android Oreo, the Pixel and Pixel XL display the verified boot fingerprint after we reported that it was missing in February 2017. However, the implementation isn’t finished yet. Fingerprints will be listed here when it’s functional.