Testing Chrome's support for using Android phones as security keys

[Adam Langley]

Dear all,

Ahead of the plenary meeting we thought it might be useful to share instructions for testing the phone-as-a-security-key functionality that we have been working on. Unlike previous launches, this works for any RP using WebAuthn.

(This feature reflects some of our current thinking but is not a firm commitment by Google to launch this, or even a similar feature, in the future. It is also not the limit of our current thinking, but a step along the way.)

You'll need an Android phone, running 7.0 (Nougat) or above, with Bluetooth support and Google Play Services, and with a screen-lock configured. For the desktop/laptop you’ll need a Chrome OS, macOS, or Windows machine with Bluetooth hardware. The phone must be signed into the same Google account as a profile is on the desktop.

Enabling

On the phone:

1. Install Chrome Canary afresh from the Play Store. (Uninstall/reinstall if already installed.)

2. Open Canary. In the new user flow, decline to enable syncing.

3. Navigate to chrome://version and ensure that the version is >= 93.0.4530.0.

4. Navigate to chrome://flags and search for “cable”.

5. Enable “Web Authentication caBLE v2 support” and relaunch Canary with the button at the bottom.

6. In Canary, use the three-dots menu (top right) to enter Canary’s settings.

7. Enable Sync (it’s at the top of the settings page).

8. Leave the phone for a minute to sync up.

On the desktop:

1. Install Chrome Canary. (Or update to the latest version.)

2. Navigate to chrome://version and ensure that the version is >= 93.0.4530.0

3. Sign into the same account as the phone is syncing to, for example by going to accounts.google.com.

4. Select the account menu in Canary—a circular icon at the top right. If it doesn’t already indicate that Sync is enabled then click “Turn on sync…” and “Yes I’m in”.

5. Open chrome://flags and search for “cable”.

6. Enable “Web Authentication caBLE v2 support” and relaunch Canary with the button at the bottom.

7. Go to your favourite, WebAuthn-using site (not accounts.google.com, see below) and try registering a security key. (For example, webauthn.io)

8. Click your phone in the transports list, unlock the phone, and tap the notification.

The credential store is device-wide so it’s possible to challenge a credential that was created by an app on the phone, so long as the RP ID matches.

If you find yourself without internet access on the phone, you can connect it with a USB cable to a macOS or Chrome OS device while the WebAuthn operation is running. (The phone is not a standard FIDO USB device, however. This does not work on Windows due to the way that the Windows USB stack is structured.)

Limitations

1. No support for discoverable credentials.

2. There must be a screen-lock enabled on the phone. (Disabling the screen lock wipes all registered credentials.)

3. Not applicable on accounts.google.com. Google uses a different Phone as a Security Key system and, since this new system depends on Google’s sync system, there could be a cyclic dependency if you had to use this system to sign into a Google account.

4. You can’t use an Android phone to sign in on another Android phone.

5. Linux is not supported. If you really want to try it you can run Chrome on Linux with --enable-features=WebAuthenticationCable,WebAuthenticationCableSecondFactor (after ensuring that all existing Chrome processes have terminated). You might want to run bluetoothd in a mode where it is automatically restarted after crashing.

Debugging

If having issues, the contents of chrome://device-log will be useful.

Firstly, check that you have correct versions of Canary installed, at least 93.0.4530.0. Secondly, check that you have BLE support on the desktop/laptop.

Some specific tips:

If the phone doesn’t show up on the desktop

Sure you have a screen-lock set on the phone, and that it’s Android 7.0 or above with Bluetooth?

Did you enable the chrome://flags flag after enabling Sync on the phone, perhaps because you already had Canary installed? The device info is only updated every day or two so it’ll take a while in that case. You can uninstall Canary and follow the instructions above if you don’t want to wait.

Still not seeing it? On the desktop, open chrome://sync-internals/. Select “Sync Node Browser” along the top then expand “Device Info” on the left. Your phone should be listed there. If not, are you sure you’re signed into the same account on the phone and desktop? If it’s listed, click it. A section called “paask_fields” should appear in the dump if Phone as a Security Key is enabled on the phone.

If the notification doesn’t appear on the phone after clicking the phone on the desktop

Unlock the phone and check the notifications. (Chrome doesn’t grab a wake lock to force the screen on.) You might also have configured notification appearance in Android Settings, or have enabled Do Not Disturb mode.

If the spinner screen shows but doesn’t advance

Please note the message showing under the spinner, if any. Roughly:

• No message: stuck trying to connect to the relay service. Check your network connection.

• “Waiting for other computer”: the desktop is waiting to receive a BLE advert from the phone. Make sure the phone is close to the computer. Cast whichever wards against evil spirits are traditionally used in your culture to get Bluetooth working.

If the error screen shows

The numeric error codes are enumerated in the Error enum here.

Cheers

AGL