README

== java-u2flib-server
Server-side https://developers.yubico.com/U2F[U2F] library for Java. Provides functionality for registering
U2F devices and authenticate with said devices.

=== Dependency
[source, xml]
 <dependency>
   <groupId>com.yubico</groupId>
   <artifactId>u2flib-server-core</artifactId>
   <version>0.15.0</version>
 </dependency>

=== 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]
----
@GET
public View startAuthentication(String username) throws NoEligableDevicesException {

    // Generate a challenge for each U2F device that this user has registered
    AuthenticateRequestData requestData
        = u2f.startAuthentication(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(AuthenticateResponse response, String username) throws 
        DeviceCompromisedException {

    // Get the challenges that we stored when starting the authentication
    AuthenticateRequestData authenticateRequest
        = requestStorage.remove(authenticateResponse.getRequestId());

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

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

In the above example `getRegistrations()` returns 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 implements `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.