How do I use FIDO U2F to allow users to authenticate with my website?

Question

With all the recent buzz around the FIDO U2F specification, I would like to implement FIDO U2F test-wise on a testbed to be ready for the forthcoming roll out of the final specification.

So far, I have a FIDO U2F security key produced by Yubico and the FIDO U2F (Universal 2nd Factor) extension installed in Chrome. I have also managed to set up the security key to work with my Google log-in.

Now, I'm not sure how to make use of this stuff for my own site. I have looked through Google's Github page for the U2F project and I have checked their web app front-end. It looks really simple (JavaScript only). So is implementing second factor auth with FIDO as simple as implementing a few JavaScript calls? All that seems to be happening for the registration in the example is this:

      var registerRequest = {
            appId: enrollData.appId,
            challenge: enrollData.challenge,
            version: enrollData.version
      };

      u2f.register([registerRequest], [], function (result) {
          if (result.errorCode) {
        document.getElementById('status')
          .innerHTML = "Failed. Error code: " + result.errorCode;
        return;
          }
          document.location = "/enrollFinish"
          + "?browserData=" + result.clientData
          + "&enrollData=" + result.registrationData
          + "&challenge=" + enrollData.challenge
          + "&sessionId=" + enrollData.sessionId;             
      });

But how can I use that for an implementation myself? Will I be able to use the callback from this method call for the user registration?

Answer 1

What you are trying to do is implement a so called "relying party", meaning that your web service will rely on the identity assertion provided by the FIDO U2F token.

You will need to understand the U2F specifications to do that. Especially how the challenge-response paradigm is to be implemented and how app ids and facets work. This is described in the spec in detail.

You are right: The actual code necessary to work with FIDO U2F from the front end of you application is almost trivial (that is, if you use the "high-level" JavaScript API as opposed to the "low-level" MessagePort API). Your application will however need to work with the messages generated by the token and validate them. This is not trivial.

To illustrate how you could pursue implementing a relying party site, I will give a few code examples, taken from a Virtual FIDO U2F Token Extension that I have programmed lately for academic reasons. You can see the page for the full example code.

---

Before your users can use their FIDO U2F tokens to authenticate, they need to register it with you. In order to allow them to do so, you need to call window.u2f.register in their browser. To do that, you need to provide a few parameters (again; read the spec for details). Among them a challenge and the id of your app. For a web app, this id must be the web origin of the web page triggering the FIDO operation. Let's assume it is example.org:

window.u2f.register([
    {
        version : "U2F_V2",
        challenge : "YXJlIHlvdSBib3JlZD8gOy0p",
        appId : "http://example.org",
        sessionId : "26"
    }
], [], function (data) {

});

Once the user performs a "user presence test" (e.g. by touching the token), you will receive a response, which is a JSON object (see spec for more details)

dictionary RegisterResponse {
    DOMString registrationData;
    DOMString clientData;
};

This data contains several elements that your application needs to work with.

1. The public key of the generated key pair -- You need to store this for future authentication use.
2. The key handle of the generated key pair -- You also need to store this for future use.
3. The certificate -- You need to check whether you trust this certificate and the CA.
4. The signature -- You need to check whether the signature is valid (i.e. confirms to the key stored with the certificate) and whether the data signed is the data expected.

I have prepared a rough implementation draft for the relying party server in Java that shows how to extract and validate this information lately.

---

Once the registration is complete and you have somehow stored the details of the generated key, you can sign requests.

As you said, this can be initiated short and sweet through the high-level JavaScript API:

window.u2f.sign([{
    version : "U2F_V2",
    challenge : "c3RpbGwgYm9yZWQ/IQ",
    app_id : "http://example.org",
    sessionId : "42",
    keyHandle: "ZHVtbXlfa2V5X2hhbmRsZQ"
}], function (data) {

});

Here, you need to provide the key handle, you have obtained during registration. Once again, after the user performs a "user presence test" (e.g. by touching the token), you will receive a response, which is a JSON object (again, see spec for more details)

dictionary SignResponse {
    DOMString keyHandle;
    DOMString signatureData;
    DOMString clientData;
};

You the need to validate the signature data contained herein.

1. You need to make sure that the signature matches the public key you have obtained before.
2. You also need to validate that the string signed is appropriate.

Once you have performed these validations, you can consider the user authenticated. A brief example implementation of the server side code for that is also contained in my server example.