Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Improve qubes-u2f-proxy documentation #4661
Qubes OS version:
Steps to reproduce the behavior:
Following the installation steps described here:
The next step in the doc says to enable the qubes-u2f-proxy service in the work qube, but this doesn't make sense since it hasn't been installed in the template yet. So my next step was to install qubes-u2f in the fedora-29 template, which is step three in the doc.
In the Fedora-29 template:
The work qube isn't running on my box, but if it was, it would need a restart to pick up the changes to the template. The doc is silent on this point.
In dom0, enable the qubes-u2f-proxy service in the work qube:
From here the doc's instructions are to "Repeat the qvm-service --enable) for all qubes that should have the proxy enabled... restart sys-usb and all qubes that use the proxy." Well, which qubes are they? It is implied that sys-usb might be one of them, but it's not clear. Certainly all qubes based on fedora-29 template will have the ability to run the proxy since they now have the proxy package. And we know that something has to be running in sys-usb to act as the browser as shown in the diagram. Maybe the proxy service fills dual roles (backend on sys-usb acting as a browser and frontend on the qube actually running the browser acting as the HID device) depending on where it's running. so let's enable the service there and restart sys-usb.
[admin@dom0 Desktop]$ qvm-service --enable sys-usb qubes-u2f-proxy
That should be it. Let's open Firefox in the work qube. I used the pre-defined Firefox shortcut from the Application Menu on Domain: work
Firefox starts. This version of Firefox is Quantum 64.0 as shown by selecting Help->About Firefox. This version of Firefox does not have U2F enabled by default, so we enable it by opening about:config and setting the security.webauth.u2f property to True.
Now let's sign in to a service that we've configured to use U2F (Dropbox). Navigate to https://www.dropbox.com and enter username and password. A window pops up prompting me to insert my previously registered Yubikey and press the gold button.
I insert one of the YubiKeys and up a window showing that the system sees it as a USB device.
Making sure the focus is in the work qube where dropbox is waiting for me to insert my Yubikey, I press the button on the Yubikey
Authentication string is populated, I click Authenticate, and gain access to my Dropbox.
Nothing happens. No output shows up in the authentication box.
If I connect the YubiKey USB device directly to the work qube and repeat the authentication sequence, it works just fine, but then we've bypassed the U2F proxy.
I could find no information on troubleshooting this issue. There was a Reddit post by someone having a problem that looked like the same one I'm having and his final post indicates he solved this by enabling keyboard USB functionality. I know that the YubiKey looks like a keyboard device to the USB stack, but a) there's no mention of needing to do this in the proxy doc and b) the proxy should be able to recognize and use the YubiKey without needing USB keyboard support. Maybe I'm wrong about that last part, but it seems like that dependency would be mentioned somewhere if it were needed.
It seems odd to expect the U2F proxy package to fill the dual roles of frontend and backend without telling it which role to play. It also doesn't make sense that there would be a dependency on the name of the cube providing USB proxy services to tell it which role to play. The USB proxy qube could be named anything. I could have more than one for different USB hubs, and so forth. So it seems like there is a fundamental piece missing from the docs.
I also tested adding a Yubikey to my Twitter account as a new security key. That worked as expected.
So it seems the proxy works when it is involved in the key registration process, but doesn't for keys registered outside of the proxy
I wanted to try adding a couple of Yubikeys to my Google account, but even though U2F was enabled on my Firefox browser, Google said I needed to use Chrome. It is also known that the Firefox Quantum implementation of U2F doesn't work with all services (ex: Facebook), so I decided to switch to Chrome, which seems to have the best support for U2F of any browser and is enabled by default. I cloned the fedora-29 template to fedora-29-test, installed google-chrome-stable on it and shut it down (it already had the qubes-u2f package installed since it was installed on the base fedora-29 template prior to cloning).
I created a new Qube VM based on the new fedora-29-test template named personal-test
Enabled the U2F proxy service on the new qube:
Added a shortcut to launch Google Chrome to the new qube and then launched Chrome. Help -> About reports my version of Chrome as "Version 71.0.3578.98 (Official Build) (64-bit)"
Next I assign the YubiKey to the personal-test Qube, bypassing the proxy. I repeat the "ADD SECURITY KEY" process, press the button on the YubiKey, and get a pop up asking for permission to use the device. I grant access and the key is registered successfully.
Having had some success registering a Yubikey via the proxy under Firefox with my Twitter account, I launch a Firefox window in the Personal Qube just as before. I navigate to Twitter and sign in. After entering my username and password, I'm prompted to enter the code from Google Authenticator (again, I have multiple 2FA methods on most accounts). I want to test the Yubikey I've registered previosuly so I select "Choose a different verification method".
I remember to check to see if the proxy service is running in this qube. It isn't, so I exit from Firefox, shutdown the qube, enable the proxy service, verify that it's enabled, and restart the qube (the docs aren't clear on whether or not enabling the proxy service requires a reboot and I was surprised to see that it wasn't enabled since I had enabled it on this qube previously. Don't know if this is expected behavior or not).
With the qube freshly restarted, I recheck to verify that the u2f proxy service is on. It is, so I launch Firefox and try again. This time I also check to see if U2F is enabled in Firefox. It isn't. Another surprise. I re-enable it. I am able to log in using the YubiKey via the U2F proxy, so this worked as expected except for having to re-enable the proxy and re-enable U2F in Firefox. Are these not expected to persist across restarts for a template-based qube?
I'm tempted to move on to the advanced configurations with specific qubes granted access to specific keys, but would like to hear back from someone there about the issues I had with Chrome before attempting more complex configurations. There are things I don't understand (as noted above) that you may be able to clear up for me and help me avoid misconfiguration.
Rebooted the "personal" qube that I just registered a key with GitHub with. Noted that both the proxy service and the u2f Firefox setting persisted across the bounce. Logged in with the registered key. Behavior is slow to respond. Had to press the button on the key multiple times. Re-attempted to register a second key. Still won't take it. Is there something the proxy is doing that prevents a second key from being registered with the same account. It works fine outside of Qubes: logged into Win10, launched Chrome, logged into GitHub using the first key. Registered the second key without trouble.
After shutting Win10 down and booting back into Qubes (this is a dual boot machine) and noting that the proxy service was still enabled on my Personal qubue (so it does persist - don't know why it wasn't persisted the first time), I launched Firefox and logged into GitHub with the first key. Attempts to use the second key were not successful. Even with the first key, there were times that I thought it had failed and was about to retry when it would finally log me in.
I also found that the proxy stopped working if I directly connected the key to the qube using the Qubes Devices manager (I needed to get a password from Lastpass and it needed OTP). After disconnecting the qube from the key using the Devices manager, attempts to use the key via the proxy always failed. I resolved this by restarting the qube. After that, the proxy worked again.
Also note that my problems with Dropbox had nothing to do with the proxy. I used a different set of keys for it and was using the wrong key.
This is wrong. The service
The first few times I tried configuring the proxy, I didn’t start it in sys-usb since it doesn’t say to do that on the doc. However, none of those attempts worked. In desperation I tried enabling it there and started having limited success.
Thanks for the information. I'm writing this from a different Qubes host after logging into GitHub using the U2F key that I registered on the other Qubes box yesterday. This is after turning off the proxy service in sys-usb and restarting it and also ensuring that the proxy service was enabled and on in the Qube I'm currently in. Other than it taking repeated attempts to get the browser to see the button press on the key, it's working.
The main question I have now is about the apparent inability to use more than one key with the same account. As mentioned above, I was able to register and use a second YubiKey with GitHub on Win10, but the second key isn't recognized by the qubes-u2f-proxy - only the first key is recognized. Is this expected behavior?
I think the thing to do now is to update the docs to make them clearer. I don't have access to the Announce page. I might be able to update the Readme in GitHub, but I would need to go through the process of registering with you as a dev, generate some signing keys, etc. Bottom line is that I'm willing to help improve the docs, but it will take some time to get setup and I will only be able to update the GitHub readme. Someone else will have to sync that to the Announcement unless I can also gain edit perms for that page.
Also, those two docs should say exactly the same thing and right now there are some minor differences.
In the meantime, I'm going to move on to the more advanced configurations available in Qubes 4 to limit the keys a given browser/Qube has access to, as described in the U2F proxy doc.
And don't forget that we still have at least one outstanding issue on the question of multiple keys for a single account. Either it's a bug and needs to be fixed or it's expected behavior and needs to b changed (or I'm doing something else wrong).
Well, I just logged out and back in using the second key. Again, it took some time for it to recognize the button press, but it did work, so maybe there is no issue with multiple keys and I was just doing something wrong until now. I'll try this with other accounts to verify.
Docs still need updating though :).
As another quick test of basic functionality (no Qubes 4 features used), I cloned the fedora-29 template to fedora-29-test-1. Installed google-chrome-stable in the clone, Created a qube named personal-test-1 using the new template. Ensured that the qubes-u2f-proxy service was enabled and on in personal-test-1, and then logged into GitHub using U2F proxy in both Firefox and Chrome.
It took a little while for the key to be recognized by the new persona-test-1 qube (it had only been used in the personal qube before and now I was trying to use it in the personal-test-1 qube, but it did eventually recognize the key in personal-test-1. I had several timeouts from GitHub waiting for the key, but I kept retrying and it eventually worked. I ended up shutting down the personal qube to ensure that it was not competing for the key. Not sure if this was necessary or not. It should not have been.
This raises some new questions:
Just validated the Twitter example in the proxy doc by making the changes to the policy files in dom0 as described in the doc, de-registering my YubiKey on my Twitter account, cloning the personal-test-1 qube to "twitter", launching Chrome in the twitter qube, registering the Yubikey with my Twitter account from there, and then tried to log in with the key in the personal-test-1 qubue and the twitter qube. Only the Twitter qube was able to get the key, exactly as described in the doc. Huston, we are go for launch.
Thank you for your willingness to help improve the documentation, @jrsmiley!
You should be able to submit a PR against this repo:
Those steps aren't necessary. This is all you have to do:
No, the differences are intentional, because announcements and documentation serve two different purposes.