Guide: FIDO U2F

FIDO Example

A complete FIDO example can be found on github.com/cotechde/hwsecurity-example-fido.

You can also directly try it out via Google Play: Get it on Google Play

This documentation is a work in progress and will soon be updated (2019-05-15).

Get Access to our Maven Repository

To get a username and password for our Maven repository, please contact us for a license.

Add the SDK to Your Project

Add this to your build.gradle:

repositories {
    google()
    jcenter()
    maven {
        credentials {
            username 'xxx'
            password 'xxx'
        }
        url "https://maven.cotech.de"
    }
}

dependencies {
    implementation 'de.cotech:hwsecurity-fido:2.0.0-alpha01'
}

FIDO Security Key Registration

Show our FidoDialogFragment using to register a security key:

private void showFidoRegisterDialog() {
    // Make a registration request to the server. In a real application, this would perform
    // an HTTP request. The server sends us a challenge (and some other data), that we proceed
    // to sign with our FIDO Security Key.
    FidoRegisterRequest registerRequest = fidoFakeServerInteractor.fidoRegisterRequest(USERNAME);

    // This opens a UI fragment, which takes care of the user interaction as well as all FIDO
    // internal operations for us, and triggers a callback to #onRegisterResponse(FidoRegisterResponse).
    FidoDialogFragment fidoDialogFragment = FidoDialogFragment.newInstance(registerRequest);
    fidoDialogFragment.show(getSupportFragmentManager());
}

Let your Activity implement OnFidoRegisterCallback and implement onRegisterResponse:

@Override
public void onRegisterResponse(@NonNull FidoRegisterResponse registerResponse) {
    try {
        // Output some debug information. Usually, we would not care about the actual content of the
        // response and just forward it to the server.
        ParsedFidoRegisterResponse parsedResponse = registerResponse.toParsedFidoRegisterResponse();
        showDebugInfo(parsedResponse);

        // Forward the registration response from the FIDO Security Key to our server application.
        // The server will perform some checks, and then remember this FIDO key as a registered
        // login mechanism for this user.
        fidoFakeServerInteractor.fidoRegisterFinish(USERNAME, registerResponse);

        // Success!
        Toast.makeText(this, "Registration successful!", Toast.LENGTH_LONG).show();
    } catch (IOException e) {
        Timber.e(e);
        Toast.makeText(this, "Register operation failed!", Toast.LENGTH_LONG).show();
    }
}

FIDO Authentication

Authentication is now done by creating a FidoAuthenticateRequest:

private void showFidoAuthenticateDialog() {
    // Make an authentication request to the server. In a real application, this would perform
    // an HTTP request. The server will send us a challenge based on the FIDO key we registered
    // before (see above), asking us to prove we still have the same key.
    FidoAuthenticateRequest authenticateRequest;
    try {
        authenticateRequest = fidoFakeServerInteractor.fidoAuthenticateRequest(USERNAME);
    } catch (NoSuchElementException e) {
        Toast.makeText(this, "No FIDO key registered - use register operation first!", Toast.LENGTH_LONG).show();
        return;
    }

    // This opens a UI fragment, which takes care of the user interaction as well as all FIDO internal
    // operations for us, and triggers a callback to #onAuthenticateResponse(FidoAuthenticateResponse).
    FidoDialogFragment fidoDialogFragment = FidoDialogFragment.newInstance(authenticateRequest);
    fidoDialogFragment.show(getSupportFragmentManager());
}

Let your Activity implement OnFidoAuthenticateCallback and implement onAuthenticateResponse:

@Override
public void onAuthenticateResponse(@NonNull FidoAuthenticateResponse authenticateResponse) {
    try {
        // Output some debug information. Usually, we would not care about the actual content of the
        // response and just forward it to the server.
        ParsedFidoAuthenticateResponse parsedResponse = authenticateResponse.toParsedFidoAuthenticateResponse();
        showDebugInfo(parsedResponse);

        // Forward the authentication response from the FIDO Security Key to our server application.
        // The server will check that the signature matches the FIDO key we registered with, and if
        // so we have successfully logged in.
        fidoFakeServerInteractor.fidoAuthenticateFinish(USERNAME, authenticateResponse);

        // Success!
        Toast.makeText(this, "Authentication successful!", Toast.LENGTH_LONG).show();
    } catch (IOException e) {
        Timber.e(e);
        Toast.makeText(this, "Authentication operation failed!", Toast.LENGTH_LONG).show();
    }
}