README

== java-u2flib-server

NOTE: _OBSOLETE: This project is no longer maintained.
U2F has been superseded by https://www.w3.org/TR/webauthn/[Web Authentication],
and this project is superseded by https://github.com/Yubico/java-webauthn-server/[java-webauthn-server].
We recommend using WebAuthn instead._

image:https://travis-ci.org/Yubico/java-u2flib-server.svg?branch=master["Build Status", link="https://travis-ci.org/Yubico/java-u2flib-server"]
image:https://coveralls.io/repos/github/Yubico/java-u2flib-server/badge.svg["Coverage Status", link="https://coveralls.io/github/Yubico/java-u2flib-server"]

Server-side https://developers.yubico.com/U2F[U2F] library for Java. Provides functionality for registering
U2F devices and authenticating with said devices.

== Migrating to WebAuthn

See the https://github.com/Yubico/java-webauthn-server#migrating-from-u2f[Migrating from U2F] section
in the https://github.com/Yubico/java-webauthn-server/[java-webauthn-server] documentation.

=== Dependency

Maven:
[source, xml]
 <dependency>
   <groupId>com.yubico</groupId>
   <artifactId>u2flib-server-core</artifactId>
   <version>0.19.12</version>
 </dependency>

Gradle:
[source, groovy]
 repositories{ mavenCentral() }
 dependencies {
   compile 'com.yubico:u2flib-server-core:0.19.12'
 }

=== Example Usage
NOTE: Make sure that you have read https://developers.yubico.com/U2F/Libraries/Using_a_library.html[Using a U2F library] before continuing.

[source, java]
----

private abstract Iterable<DeviceRegistration> getRegistrations(String username);

@GET
public View startAuthentication(String username) throws NoEligibleDevicesException {

    // Generate a challenge for each U2F device that this user has registered
    SignRequestData requestData
        = u2f.startSignature(SERVER_ADDRESS, getRegistrations(username));

    // Store the challenges for future reference
    requestStorage.put(requestData.getRequestId(), requestData.toJson());

    // Return an HTML page containing the challenges
    return new AuthenticationView(requestData.toJson(), username);
}

@POST
public String finishAuthentication(SignResponse response, String username) throws
        DeviceCompromisedException {

    // Get the challenges that we stored when starting the authentication
    SignRequestData signRequest
        = requestStorage.remove(response.getRequestId());

    // Verify the that the given response is valid for one of the registered devices
    u2f.finishSignature(signRequest,
                             response,
                             getRegistrations(username));

    return "Successfully authenticated!";
}
----

In the above example `getRegistrations()` will return the U2F devices currently associated with a given user.
This is most likely stored in a database. 
See link:u2flib-server-demo[`u2flib-server-demo`] for a complete demo server (including registration and storage of U2F devices).

=== JavaDoc
JavaDoc can be found at https://developers.yubico.com/java-u2flib-server[developers.yubico.com/java-u2flib-server].


=== Attestation
The attestation module (`u2flib-server-attestation`) enables you to restrict registrations to certain U2F devices (e.g. devices made by a specific vendor). It can also provide metadata for devices.

=== Serialization
All relevant classes implement `Serializable`, so instead of using `toJson()`, you can use Java's built in serialization mechanism.
Internally the classes use Jackson to serialize to and from JSON, and the ObjectMapper from Jackson can be used.