New in Android Samples: Authenticating to remote servers using the Fingerprint API

Posted by Takeshi Hagikura, Yuichi Araki, Developer Programs Engineer

As we announced in the previous blog post, Android 6.0 Marshmallow is now publicly available to users. Along the way, we’ve been updating our samples collection to highlight exciting new features available to developers.

This week, we’re releasing AsymmetricFingerprintDialog, a new sample demonstrating how to securely integrate with compatible fingerprint readers (like Nexus Imprint) in a client/server environment.

Let’s take a closer look at how this sample works, and talk about how it complements the FingerprintDialog sample we released earlier during the public preview.

Symmetric vs Asymmetric Keys

The Android Fingerprint API protects user privacy by keeping users’ fingerprint features carefully contained within secure hardware on the device. This guards against malicious actors, ensuring that users can safely use their fingerprint, even in untrusted applications.

Android also provides protection for application developers, providing assurances that a user’s fingerprint has been positively identified before providing access to secure data or resources. This protects against tampered applications, providing cryptographic-level security for both offline data and online interactions.

When a user activates their fingerprint reader, they’re unlocking a hardware-backed cryptographic vault. As a developer, you can choose what type of key material is stored in that vault, depending on the needs of your application:

• Symmetric keys: Similar to a password, symmetric keys allow encrypting local data. This is a good choice securing access to databases or offline files.
• Asymmetric keys: Provides a key pair, comprised of a public key and a private key. The public key can be safely sent across the internet and stored on a remote server. The private key can later be used to sign data, such that the signature can be verified using the public key. Signed data cannot be tampered with, and positively identifies the original author of that data. In this way, asymmetric keys can be used for network login and authenticating online transactions. Similarly, the public key can be used to encrypt data, such that the data can only be decrypted with the private key.

This sample demonstrates how to use an asymmetric key, in the context of authenticating an online purchase. If you’re curious about using symmetric keys instead, take a look at the FingerprintDialog sample that was published earlier.

Here is a visual explanation of how the Android app, the user, and the backend fit together using the asymmetric key flow:

1. Setting Up: Creating an asymmetric keypair

First you need to create an asymmetric key pair as follows:

KeyPairGenerator.getInstance(KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
keyPairGenerator.initialize(
        new KeyGenParameterSpec.Builder(KEY_NAME,
                KeyProperties.PURPOSE_SIGN)
                .setDigests(KeyProperties.DIGEST_SHA256)
                .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
                .setUserAuthenticationRequired(true)
                .build());
keyPairGenerator.generateKeyPair();

Note that .setUserAuthenticationRequired(true) requires that the user authenticate with a registered fingerprint to authorize every use of the private key.

Then you can retrieve the created private and public keys with as follows:

KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
PublicKey publicKey =
        keyStore.getCertificate(MainActivity.KEY_NAME).getPublicKey();

KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
PrivateKey key = (PrivateKey) keyStore.getKey(KEY_NAME, null);

2. Registering: Enrolling the public key with your server

Second, you need to transmit the public key to your backend so that in the future the backend can verify that transactions were authorized by the user (i.e. signed by the private key corresponding to this public key). This sample uses the fake backend implementation for reference, so it mimics the transmission of the public key, but in real life you need to transmit the public key over the network.

boolean enroll(String userId, String password, PublicKey publicKey);

3. Let’s Go: Signing transactions with a fingerprint

To allow the user to authenticate the transaction, e.g. to purchase an item, prompt the user to touch the fingerprint sensor.

Then start listening for a fingerprint as follows:

Signature.getInstance("SHA256withECDSA");
KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
keyStore.load(null);
PrivateKey key = (PrivateKey) keyStore.getKey(KEY_NAME, null);
signature.initSign(key);
CryptoObject cryptObject = new FingerprintManager.CryptoObject(signature);

CancellationSignal cancellationSignal = new CancellationSignal();
FingerprintManager fingerprintManager =
        context.getSystemService(FingerprintManager.class);
fingerprintManager.authenticate(cryptoObject, cancellationSignal, 0, this, null);

4. Finishing Up: Sending the data to your backend and verifying

After successful authentication, send the signed piece of data (in this sample, the contents of a purchase transaction) to the backend, like so:

Signature signature = cryptoObject.getSignature();
// Include a client nonce in the transaction so that the nonce is also signed 
// by the private key and the backend can verify that the same nonce can't be used 
// to prevent replay attacks.
Transaction transaction = new Transaction("user", 1, new SecureRandom().nextLong());
try {
    signature.update(transaction.toByteArray());
    byte[] sigBytes = signature.sign();
    // Send the transaction and signedTransaction to the dummy backend
    if (mStoreBackend.verify(transaction, sigBytes)) {
        mActivity.onPurchased(sigBytes);
        dismiss();
    } else {
        mActivity.onPurchaseFailed();
        dismiss();
    }
} catch (SignatureException e) {
    throw new RuntimeException(e);
}

Last, verify the signed data in the backend using the public key enrolled in step 2:

@Override
public boolean verify(Transaction transaction, byte[] transactionSignature) {
    try {
        if (mReceivedTransactions.contains(transaction)) {
            // It verifies the equality of the transaction including the client nonce
            // So attackers can't do replay attacks.
            return false;
        }
        mReceivedTransactions.add(transaction);
        PublicKey publicKey = mPublicKeys.get(transaction.getUserId());
        Signature verificationFunction = Signature.getInstance("SHA256withECDSA");
        verificationFunction.initVerify(publicKey);
        verificationFunction.update(transaction.toByteArray());
        if (verificationFunction.verify(transactionSignature)) {
            // Transaction is verified with the public key associated with the user
            // Do some post purchase processing in the server
            return true;
        }
    } catch (NoSuchAlgorithmException | InvalidKeyException | SignatureException e) {
        // In a real world, better to send some error message to the user
    }
    return false;
}

At this point, you can assume that the user is correctly authenticated with their fingerprints because as noted in step 1, user authentication is required before every use of the private key. Let’s do the post processing in the backend and tell the user that the transaction is successful!

Other updated samples

We also have a couple of Marshmallow-related updates to the Android For Work APIs this month for you to peruse:

We hope you enjoy the updated samples. If you have any questions regarding the samples, please visit us on our GitHub page and file issues or send us pull requests.