Egomet FIDO SDK for Android

Egomet Android SDK turns the FIDO Protocol in a Java interface, allowing a rapid integration with the FIDO Services.

This guide allows the developer to integrate the SDK in the Relying Party Client App (AKA RPClient).

Table of Contents

1. System Requirements

2. Request your Egomet FIDO SDK license

In order to make your App work with the SDK, you must enable your SDK license by submitting your App SHA-1 certificate and CSR.

2.1 Retrieve App SHA-1 certificate

2.1.1 Via Android Studio

In your Android Studio project:

  1. Go to the Gradle panel (the Gradle panel is placed on the right side of the Android studio interface)
  2. Once you've opened the Gradle panel, navigate to "Project name"->"Project name (root)"->Tasks->android and run the task signingReport.

android studio signing report androidStudioSigningReport

2.1.2 Without Android Studio

  1. Go to the keystore location
  2. Open CMD
  3. Run the following command
$ keytool -list -keystore < fileName >.keystore

NOTE: replace < filename > with your file name. eg: debug.keystore.

prompt sha1 keystore promptSha1

2.2 Generate CSR

The following instructions will guide you through the CSR generation process via OpenSSL. If you already generated the CSR and received your trusted SSL certificate, check "License file integration" and disregard the steps below.

  1. Open a terminal with OpenSSL
  2. Generate both, private key and CSR by running the following command:
    openssl req -new -newkey rsa:2048 -nodes -keyout yourPrivete.key -out fidoSdkCertificateRequest.csr
  3. Enter the following CSR details when prompted:
    • Country Name: The official two-letter country code (i.e. IT, US) where your organization is legally incorporated.
    • State or Province: The state or province where your organization is legally incorporated. Do not abbreviate.
    • Locality Name: The locality or city where your organization is legally incorporated. Do not abbreviate.
    • Organization Name: The full legal name of your organization including the corporate identifier.
    • Organization Unit (OU): Your department such as ‘Information Technology’ or ‘Website Security’.
    • Common Name: Use the FQDN (fully-qualified domain name) to indicate your service name (e.g.: demo.movenda.com).

3. How to integrate Egomet FIDO SDK

3.1 Android studio integration

  1. From the Android studio menu, click File, select New and then click New Module.
  2. From the New Module window, select Import .JAR/.AAR Package, and click Next.
  3. In the File name field, enter the path of movenda-fido-sdk.aar.
  4. In the Subproject name field, enter movenda-fido-sdk and click Finish.
  5. In your app's build.gradle, add dependency to movenda-fido-sdk:
dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.5.0'
    implementation 'com.squareup.retrofit2:converter-scalars:2.5.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.5.0'
    implementation 'com.afollestad.material-dialogs:core:0.9.6.0'
    implementation 'org.parceler:parceler-api:1.1.11'
    annotationProcessor 'org.parceler:parceler:1.1.11'
    implementation project(':movenda-fido-sdk')
}

3.2 License file integration

The following instructions will guide you through the PKCS#12 generation process with OpenSSL. If you already received your trusted SSL certificate and generated the PKCS#12, go to the third step of this section.

  1. Open a terminal with OpenSSL
  2. Generate a PKCS#12 by running the following command:
    openssl pkcs12 -export -out yourKeyStore.p12 -inkey yourPrivete.key -in yourSignedCertificate.crt
  3. Place your licence file "yourKeyStore.p12" in your application's raw folder

3.3 SDK initialization

To initialize the SDK, in your application class, you must pass to the “init” method your PKCS#12 (e.g.: yourKeyStore.p12) and its related password.

Use the method initStaging only during the testing phase of the Egomet service.

Use the method initProduction for production phase.

Here's an example for the staging enviroment:

public class MyApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        InputStream is = getResources().openRawResource(R.raw.yourKeyStore);
        String pkcs12Password = "changeit";
        try {
            MovendaApplicationSDK.initStaging(this, is, pkcs12Password);
        } catch (CertificateExpiredException e){
            // Client certificate has expired: please contact egomet-support@movenda.com for certificate renewal
        }
    }
}

4. Operations

Commons usage patterns for enabling the operations:

For all those operations you need to instantiate the MovendaFIDOComboSDK class and override the method onActivityResult by using the processFIDOClientResponse method in your Activity:

public class MyActivity extends AppCompatActivity {
    private MovendaFIDOComboSDK movendaFidoSDK;

    @Override
    protected void onCreate(Bundle bundle) {
        super.onCreate(bundle);
        // setup views, as you would normally do in onCreate

        this.movendaFidoSDK = new MovendaFIDOComboSDK(this);
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        this.movendaFidoSDK.processFIDOClientResponse(resultCode, data);
    }
}

4.1 User registration

This operation permits to enroll your device as a fast and secure authentication method.

First of all you must implement the callback interfaces:

public class MyActivity extends AppCompatActivity implements RegistrationCallback, FidoSDKErrorCallback
{
    //interfaces methods implementation
}

Now you can start the user registration process by invoking the registration method:

this.movendaFidoSDK.registration(<username>, <registrationCallback>, <fidoSdkErrorCallback>);

NOTE: the string username must be a human-readable username intended to allow the user to distinguish and select from among different accounts (e.g: email address).

Now you can manage the success registration response:

@Override
public void onRegistrationSuccess(AuthenticatorOwnership authenticatorOwnership) {
    Log.i(TAG, "Reg Success with username:" + authenticatorOwnership.getUsername());
}

The AuthenticatorOwnership is the object that identifies your username and the current device in the Egomet FIDO system.

We recommend to store this object in your system in order to perform the next FIDO operation.

In the AuthenticatorOwnership there are two properties: the registered username and the fidoID assigned by the Egomet FIDO system.

4.2 User authentication

This operation permits to authenticate the user.

First of all you must implement the callback interfaces:

public class MyActivity extends AppCompatActivity implements AuthenticationCallback, FidoSDKErrorCallback
{
    //interfaces methods implementation
}

Then start the user authentication process by invoking the authentication method:

this.movendaFidoSDK.authentication(<authenticationCallback>, <fidoSdkErrorCallback>);

Now you can manage the success authentication response:

@Override
public void onAuthenticationSuccess(AuthenticatorOwnership authenticatorOwnership) {
    Log.i(TAG, "Auth Success with username:" + authenticatorOwnership.getUsername());
}

4.3 User de-registration

This operation permits to de-register the device that was registered as an authentication method for a user.

First of all you must implement the callback interfaces:

public class MyActivity extends AppCompatActivity implements DeregistrationCallback, FidoSDKErrorCallback
{
    //interfaces methods implementation
}

Now you can start the de-register process by invoking the deregistration method:

this.movendaFidoSDK.deregistration(<authenticatorOwnership.getFidoId()>, <deregistrationCallback>, <fidoSdkErrorCallback>);

Now you can manage the de-registration response:

@Override
public void onDeregistrationCompleted() {
    Log.i(TAG, "Dereg completed...for username:" + authenticatorOwnership.getUsername());
}

4.4 Creation and confirmation of business transaction

The SDK permits to build and confirm business transaction in order to accomplish various scenarios where a digital signature is required.

The SDK comes with 3 out-of-the-box transaction types:

More transactions types can be added later by submitting a request to egomet-support@movenda.com

Start by implementing the callback interfaces:

public class MyActivity extends AppCompatActivity implements BusinessTransactionCallback, TransactionConfirmationCallback, FidoSDKErrorCallback
{
    //interfaces methods implementation
}

4.4.1 Payment transaction

This operation permits to create a payment transaction that can be confirmed later using the confirm transaction method.

In order to create a payment transaction, you must create the PaymentTransaction object. After that, invoke the createTransaction method by passing in input the PaymentTransaction object:

Payee payee = new Payee("AMAZON IT", "www.amazon.it", Locale.ITALY,

TimeZone.getTimeZone("Europe/Rome"));

PaymentTransaction paymentTransaction = new PaymentTransaction(<authenticatorOwnership>, payee, "8991101200003200013", "MASTERCARD", "MAY 2021", "8364648888", "***********738", "231,75");

this.movendaFidoSDK.createTransaction(paymentTransaction, <businessTransactionCallback>, <fidoSdkErrorCallback>);

Now you can manage the success creation response:

@Override
public void onTransactionCreated() {
    Log.i(TAG, "Transaction created ...");
}

At this point you can ask the user confirmation:

this.movendaFidoSDK.confirmTransaction(<authenticatorOwnership.getFidoId()>, <transactionConfirmationCallback>, <fidoSdkErrorCallback>);

Finally manage the response:

public void onTransactionConfirmed(AuthenticatorOwnership authenticatorOwnership) {
    Log.i(TAG, "Transaction confirmed for username:" + authenticatorOwnership.getUsername());
}

@Override
public void onNotFound() {
    Log.i(TAG, "Transaction not confirmed ..." );
}

The image generated by the Egomet FIDO system will look like this:

fido payment transaction paymentTransaction

4.4.2 Free-text transaction

This operation permits to create a free-text transaction that can be confirmed later using the confirmTransaction method.

In order to create a transaction that includes a generic content, you must create the FreeTextTransaction object. After that, invoke the createTransaction method by passing in input the FreeTextTransaction object:

String freeText = "I hereby agree to pay the CARs LTD for use of the Vehicle as follows: Fees: $10 per day/week. Fuel: is not required to pay for the use of fuel. Excess Mileage: $15 per mile Deposit: $200.";

FreeTextTransaction freeTextTransaction = new FreeTextTransaction(<authenticatorOwnership>, freeText);

this.movendaFidoSDK.createTransaction(freeTextTransaction, <businessTransactionCallback>, <fidoSdkErrorCallback>);

Now you can manage the creation response:

@Override
public void onTransactionCreated() {
    Log.i(TAG, "Transaction created ...");
}

At this point you can ask the user confirmation:

this.movendaFidoSDK.confirmTransaction(<authenticatorOwnership.getFidoId()>, <transactionConfirmationCallback>, <fidoSdkErrorCallback>);

Finally manage the response:

@Override
public void onTransactionConfirmed(AuthenticatorOwnership authenticatorOwnership) {
    Log.i(TAG, "Transaction confirmed for username:" + authenticatorOwnership.getUsername());
}

@Override
public void onNotFound() {
    Log.i(TAG, "Transaction not confirmed ..." );
}

The image generated by the Egomet FIDO system will look like this:

free-text transaction freeTextTransaction

4.4.3 Bank transfer transaction

In order to create a transaction that includes a bank transfer, you must create the BankTransferTransaction object. After that, invoke the createTransaction method by passing in input the BankTransferTransaction object:

Locale locale = Locale.ITALY;

TimeZone timeZone = TimeZone.getTimeZone("Europe/Rome");

BankTransferTransaction bankTransferTransaction = new BankTransferTransaction(<authenticatorOwnership>,
        "00000035001110",
        "Steve Guinnes",
        "IT70U176012000001111452",
        "124423108400006231239111IT", "Car loan", "237", timeZone.getID(), locale.getLanguage(), locale.getCountry());

this.movendaFidoSDK.createTransaction(bankTransferTransaction, <businessTransactionCallback>, <fidoSdkErrorCallback>);

Now you can manage the creation response:

@Override
public void onTransactionCreated() {
    Log.i(TAG, "Transaction created ...");
}

At this point you can ask the user confirmation:

this.movendaFidoSDK.confirmTransaction(<authenticatorOwnership.getFidoID()>, <transactionConfirmationCallback>, <fidoSdkErrorCallback>);

Finally manage the response:

@Override
public void onTransactionConfirmed(AuthenticatorOwnership authenticatorOwnership)
    Log.i(TAG, "Transaction confirmed for username:" + authenticatorOwnership.getUsername());
}

@Override
public void onNotFound() {
    Log.i(TAG, "Transaction not confirmed ..." );
}

The image generated by the Egomet FIDO system will look like this:

bank transfer transaction bankTransferTransaction

5. SDK error management

The SDK can generate the following types of errors: