Exposure Notifications debug mode

Stay organized with collections Save and categorize content based on your preferences.

Exposure Notifications (EN) debug mode increases the following:

  • flexibility over testing signed bundle verification functionality
  • control over service internal behavior
  • information in bug reports

This feature is available only for allowlisted development accounts starting from the v1.1 version of the framework. It is not designed to be visible to devices with consumer accounts.

You should also be aware that debug mode has some potentially unexpected behavior. In particular, if debug mode is turned off, the device does not behave exactly like a consumer device. The state of a device is determined as follows:

Is device in allowlist?

  • No. Consumer device; no debug features are enabled.
  • Yes. Is debug mode turned on?
    • No. Device gets default debug options. The exact features are subject to change, but presently when in this state "Return all TEKs immediately" is enabled. Quotas on method calls that apply to consumer devices may not be applicable.
    • Yes. Debug options are as configured by the UI. Quotas also don't apply.

Enable debug mode

To enable debug mode on a device, the primary account on the device must be a development account that is on the allowlist.

Access debug mode using the settings UI. To open the settings UI, tap Settings > Google > COVID-19 notifications > Debug mode.

Debug mode options in API version 1.6

The Debug mode page in settings contains the configuration options shown in the following image.


Figure 1. Configuration options for debug mode with API version 1.6

Return today’s TEK with shortened rolling period

When enabled, the Return today's TEK with shortened rolling period option allows you to simulate early TEK release on a given key by executing these actions:

  1. Disabling the current key for the rest of the day.

  2. Shortening the key's rollingPeriod.

  3. Generating a new key to be used for the rest of the day.

This is different from the preexisting Return all TEKs immediately option, which returns the current day's TEK but doesn't invalidate it or affect its rollingPeriod.

Note: As of v1.6, early TEK release is not currently enabled in the Exposure Notifications API. This may be the default behavior of getTemporaryExposureKeyHistory() in a future update.

It is critical that internet-accessible servers and Exposure Notifications apps are compatible with both modes of operation for getTemporaryExposureKeyHistory().

Use this option to test TEK release behaviors:

Toggling the Return today’s TEK with shortened rolling period option on or off determines different behavior and handling, as follows:

  • If this option is disabled when a user’s report of their infection results in calling getTemporaryExposureKeyHistory() in the middle of the day, only the keys of the last 14 days up to the previous day are returned.

    To support this behavior, an app must wait until the current day ends to make another call to the API that includes the TEK for the day on which the report originated.

  • If this option is enabled, getTemporaryExposureKeyHistory() returns the keys of the last 14 days and the current day’s TEK, with an adjusted rollingPeriod value up to the moment of the call. When the current key is released, the device stops using it and replaces it with a new key. The new key is used to generate BLE beacons from this point forward.

    As a result, if getTemporaryExposureKeyHistory() is called multiple times, several keys with different rollingPeriod and identical rollingStartNumber objects can be released for those days with multiple calls.

    To support this behavior, ensure your server doesn’t introduce any restrictions to the number of TEKs for a particular day or the rollingPeriod values associated with them. In addition, if you choose to use chaff requests or request padding when submitting keys to your servers to report a case, make sure to evaluate the size of this dummy content so you can accommodate the real TEKs, given the flexibility in the number of TEKs per day explained here.

Debug mode options in API version 1.5

The Debug mode page contains the configuration options shown in the following image.


Figure 2. Configuration options for debug mode with API version 1.5

Bypass app signature check

When enabled, allows users to bypass application signature (SHA-256) verification.

Enable diagnosis key file signature check

When enabled, checks the signature and fields of the export signature.

Enable custom diagnosis key file signature fields

When enabled, allows an allowlisted user to specify HA public key for diagnosis keys and SignatureInfo parameters. Expected input has the following format:

  • Diagnosis key file signature: Base64-encoded public key. This is the same public key bytes that are sent to Google. This key is used for signature verification in apps in which the package name matches the diagnosis key file package name as shown in the following sections, and the key file being processed has the specified version and ID.
  • Diagnosis key file package name: Android package name used to look up the configured public signature verification keys for an application.
  • Diagnosis key file ID: The alias or ID used in the SignatureInfo to identify the public key to be used for verification.
  • Diagnosis key file version: The version identifier set in the SignatureInfo.

The following are examples of correctly configured fields.

Debug mode:

Diagnosis key file signature: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEml59itec9qzwVojreLXdPNRsUWzfYHc1cKvIIi6/H56AJS/kZEYQnfDpxrgyGhdAm+pNN2GAJ3XdnQZ1Sk4amg==
Diagnosis key file package name: my.package.name
Diagnosis key file ID: 001
Diagnosis key file version: v1

Signature info:

signature_infos {
  verification_key_version: "v1"
  verification_key_id: "001"
  signature_algorithm: "1.2.840.10045.4.3.2"
}

By default, the module versions associated with a debug mode rely on the signature check state specified in the debug settings. This means that an app user must explicitly opt out from signature verification using the debug mode. In the previous behavior, the signature check was bypassed for allowlisted accounts. If the user has not explicitly opted out, the signature verification check will fail unless the app is already allowlisted in Google Play services.

Debug mode options in API version 1.1

The Debug mode page contains the configuration options shown in the following image.


Figure 3. Configuration options for debug mode for API version 1.1

For information on the fields other than Return all TEKs immediately, see Debug mode options in API version 1.5.

Return all TEKs immediately

When enabled, the getTemporaryExposureKeyHistory() method returns Temporary Exposure Keys (TEKs), including a current day. When this is not enabled, TEKs are released only on the next day.

Retrieve debug data

Debug dumping works both when debug mode is on or off, but the level of information is different:

  • When debug mode is enabled, the dump contains much more detailed information, though it does not contain the details prior to when debug mode was turned on. This is necessary to preserve user privacy.
  • When debug mode is disabled, the additional information that debug mode captures is deleted.

Re-enabling debug mode will not reveal past data, even if the past data was captured during debug mode.

To dump debug data, do one of the following:

  • Capture a bug report and search for SERVICE com.google.android.gms/.nearby.exposurenotification.service.ExposureNotificationInternalService in the output.
  • Run the command: 
    adb shell dumpsys activity service com.google.android.gms/.nearby.exposurenotification.service.ExposureNotificationInternalService