google / u2f-ref-code

U2F reference implementations
BSD 3-Clause "New" or "Revised" License
588 stars 182 forks source link

Reference code for U2F specifications

This code implements the FIDO U2F specifications being developed at http://fidoalliance.org/. This code is intended as a reference and resource for developers who are interested in exploring U2F. The code consists of the following components:

Java U2F implementation

This code can verify U2F registrations and signatures. A web application built to accept U2F 2nd factor is built on top of a code base such as this. The code base includes a trivial web application so the user can experiment with registration and signatures (also see the sample web app below).

A virtual (software) U2F device

This is a Java implementation of a U2F device. It generates registration and signature statements and is meant for testing against your server implementation. A physical U2F device will generate similar statements.

A sample web app that uses U2F

This is a sample application built on the Google App Engine web platform which demonstrates a possible UX for user interaction with U2F in a web page. The sample application is deployed and available live at https://u2fdemo.appspot.com/. The underlying U2F capability is provided by the Java U2F implementation. A developer can take the core ideas from here and integrate U2F into a web application on their own favorite web app platform.

Getting started

u2f-ref-code is a self contained java project that includes a basic web server and includes packages for all crypto, utilities, etc. It does not need to run in a container or application server like Tomcat. To run the demo server, run the main class in com.google.u2f.tools.httpserver.U2fHttpServer

To compile and run the server in Eclipse, import the Maven project into your workspace. You may need to fix the classpath if your version of JDK is different (this has been tested with Java 1.7). The simple demo web server is in com.google.u2f.tools.httpserver.U2fHttpServer.java and runs on port

  1. Run this class as a regular Java application (right click, select Run As and Java Application). Note that you need to have the U2F extension installed in Chrome in order for the demo app to talk to your U2F token.

To run directly with Maven, run mvn compile exec:java from the u2f-ref-code directory.

U2F-GAE-Demo

The u2f-gae-demo project is a sample application built on the Google App Engine web platform which demonstrates a possible UX for user interaction with U2F in a web page.

To start the development server with Maven, run mvn appengine:devserver. This will run the server locally at http://localhost:8888/.

As above, if importing the Maven project into Eclipse you might have to adjust JDK versions, App Engine SDK version, etc. Once everything compiles, you can run the App Engine server locally and point Google Chrome at http://localhost:8888/.

The built-in support for U2F in Google Chrome only works on HTTPS sites. To test the app on http://localhost:8888, which uses HTTP, you need to do the following:

Use the built-in chrome support

You can deploy this App Engine app to your own domain by changing the application name in u2f-gae-demo/war/WEB-INF/appengine-web.xml.