Goldfinger

Quick guide

Add dependency

implementation 'co.infinum:goldfinger:1.0.0-rc1'

Initialize

Goldfinger.Builder(context).build()

Check prerequisites

if (goldfinger.hasEnrolledFingerprint()) {
  /* Authenticate */
}

Authenticate

goldfinger.authenticate(new Goldfinger.Callback() {

  @Override
  public void onSuccess(String value) {
    /* Authenticated */
  }

  @Override
  public void onWarning(Warning warning) {
    /* Authentication failed, Fingerprint authentication still active */
  }

  @Override
  public void onError(Error error) {
    /* Critical error, Fingerprint authentication not active */
  }
});

You can see all Goldfinger methods here.

Fingerprint authentication flow

To use the Android Fingerprint API you must:

• Create a new or load an existing SecretKey
• Create a Cipher with a created or loaded SecretKey
• Create a CryptoObject with a created Cipher
• Start Fingerprint authentication with a created CryptoObject
• Handle possible exceptions at every step due to complexity of the Android Fingerprint API

The CryptoObject is locked when created and it is unlocked when the user successfully authenticates. Once it is unlocked, you can use it to cipher data.

Fingerprint authentication is used to either:

1. Authenticate the user, e.g. for payment
2. Perform encryption or decryption operations over user’s case-sensitive information, e.g. passwords

Goldfinger wraps everything mentioned and provides an intuitive and easy-to-use interface.

Configuration

If you don’t like Default implementations, you can easily modify them using Goldfinger.Builder object.

Goldfinger.Builder(context)
  .setLogEnabled(true)
  .setCryptoCreator(cryptoCreator)
  .setCrypto(crypto)
  .build()

Logging

Logging is off by default. You can enable it by calling Goldfinger.Builder(context).setLogEnabled(true).

CryptoFactory

Creating a CryptoObject is a complicated process that has multiple steps. CryptoFactory allows you to modify CryptoObject creation and adjust it to your needs.

new CryptoFactory() {

    @Nullable
    @Override
    public FingerprintManagerCompat.CryptoObject createAuthenticationCryptoObject(String keyName) {}

    @Nullable
    @Override
    public FingerprintManagerCompat.CryptoObject createEncryptionCryptoObject(String keyName) {}

    @Nullable
    @Override
    public FingerprintManagerCompat.CryptoObject createDecryptionCryptoObject(String keyName) {}
};

All methods should return a CryptoObject instance or a null value if an error happens during object creation.

You can find the default implementation here.

Crypto

Goldfinger automatically handles encryption and decryption operations via a Crypto implementation which you can implement yourself in case you want a custom cipher.

new Crypto() {

    @Nullable
    @Override
    public String encrypt(FingerprintManagerCompat.CryptoObject cryptoObject, String value) {}

    @Nullable
    @Override
    public String decrypt(FingerprintManagerCompat.CryptoObject cryptoObject, String value) {}
}

Crypto methods receive an unlocked CryptoObject that ciphers data and a String value as data you should cipher. The return value should be ciphered data or null if an error happens.

The default Crypto implementation can be found here.

Known issues

• Android Oreo doesn't throw KeyPermanentlyInvalidatedException - Link

Contributing

Feedback and code contributions are very much welcome. Just make a pull request with a short description of your changes. By making contributions to this project you give permission for your code to be used under the same license.

Credits

Maintained and sponsored by Infinum.