Guida android
FIDO UAF SDK
Egomet Android SDK turns the FIDO Protocol in a Java interface, allowing a rapid integration with the FIDO Services.
This pseudo-code guide introduces the relevant details to the developer who wish integrating
the SDK in the Relying Party Client App (AKA RPClient).
Please refer to SDK javadocs for full details and information
System Requirements
- Android 6.0+ (API level 23+)
- Fingerprint scanner
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 a CSR.
Retrieve App SHA-1 certificate
Via Android Studio
In your Android Studio project:
- Go to the Gradle panel (the Gradle panel is placed on the right side of the Android studio interface)
- Once you’ve opened the Gradle panel, navigate to “Project name”->“Project name (root)”->Tasks->android and run the task signingReport.
Without Android Studio
- Go to the keystore location
- Open CMD
- Run the following command
$ keytool -list -keystore < fileName >.keystore
NOTE: replace < filename > with your file name. eg: debug.keystore.
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.
- Open a terminal with OpenSSL
- Generate both, private key and CSR by running the following command:
openssl req -new -newkey rsa:2048 -nodes -keyout yourPrivete.key -out fidoSdkCertificateRequest.csr
- 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).
How to integrate Egomet FIDO SDK
Android studio integration
- From the Android studio menu, click File, select New and then click New Module.
- From the New Module window, select Import .JAR/.AAR Package, and click Next.
- In the File name field, enter the path of movenda-fido-sdk.aar.
- In the Subproject name field, enter
movenda-fido-sdk
and click Finish. - In your app’s
build.gradle
, add dependency tomovenda-fido-sdk
:
android{
//your other project characteristics
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
dependencies {
implementation 'com.squareup.retrofit2:retrofit:2.8.1'
implementation 'com.squareup.retrofit2:converter-scalars:2.8.1'
implementation 'com.squareup.retrofit2:converter-gson:2.8.1'
implementation 'androidx.biometric:biometric:1.0.1'
implementation project(':movenda-fido-sdk')
}
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.
- Open a terminal with OpenSSL
- Generate a PKCS#12 by running the following command:
openssl pkcs12 -export -out yourKeyStore.p12 -inkey yourPrivete.key -in yourSignedCertificate.crt
- Place your licence file “yourKeyStore.p12” in your application’s raw folder
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
}
}
}
Operations
Commons usage patterns for enabling the operations:
- User Registration;
- User Authentication;
- User De-registration;
- Confirm transaction.
For the above operations you need to:
- implement several callback interfaces depending on the operations you need to perform (e.g.: RegistrationCallback, AuthenticationCallback)
- instantiate the
MovendaFIDOComboSDK
public class MyActivity extends AppCompatActivity implements RegistrationCallback, AuthenticationCallback, ...{
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);
}
}
You can check the SDK version by using the following method:
this.movendaFidoSDK.getSDKVersionName()
User registration
This operation permits to enroll your device as a fast and secure authentication method.
you can start the user registration process by invoking the registration
method:
this.movendaFidoSDK.registration(<rpRandomUuid>, <username>, <registrationCallback>);
NOTE:
- the rpRandomUuid is a random UUID (RFC 4122) generated by RPClient App back-end
- 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 registration result:
@Override
public void onRegistrationResult(UafServerResponse uafServerResponse) {
// submit registration result to RPClient App back-end
}
The UafServerResponse represents the result of the FIDO Server computation: it contains the registration result along with the AuthenticatorOwnership
which carries on the username and the fidoId (i.e.: the current device in the Egomet FIDO system).
{
"operation_result" : {
"status" : "EXECUTED_SUCCESS"
},
"authenticator_ownership" : {
"fido_id" : "8963298209427",
"username" : "john.doe@aol.com"
},
"rp_challenge" : "ddcd964f-f89c-4896-b2e4-9a1976d39d48",
"signature" : "MzAyMDgyODI3NzgyODI4MjgyMUFGODI3MzI2NjM2NjY2NjYyMjBCQURDQUZFREVBRDY2REVBRkJBQkU4MjczNDc2NDY0Ng"
}
We recommend sending UafServerResponse
to RP back-end in order to:
- verify the signature with the FIDO Server public key
- inform your back-end about the registration result
We recommend also storing AuthenticatorOwnership
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.
User authentication
This operation permits to authenticate the user.
Start the user authentication process by invoking the authentication
method:
this.movendaFidoSDK.authentication(<rpRandomUuid>, <authenticationCallback>);
Now you can manage the success authentication result:
@Override
public void onAuthenticationResult(UafServerResponse uafServerResponse) {
// submit authentication result to RPClient App back-end
}
We recommend sending UafServerResponse
to RP back-end in order to:
- verify the signature with the FIDO Server public key
- inform your back-end about the authentication result
User de-registration
This operation permits to de-register the device that was registered as an authentication method for a user.
You can start the de-register process by invoking the deregistration
method:
this.movendaFidoSDK.deregistration(<authenticatorOwnership.getFidoId()>, <deregistrationCallback>);
Now you can manage the de-registration response:
@Override
void onDeregistrationCompleted();
...
}
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:
- Payment transaction;
- Freetext transaction;
- Bank transfer transaction.
More transactions types can be added later by submitting a request to egomet-support@movenda.com
Payment transaction
This operation permits to confirm a payment transaction.
In order to create a payment transaction, you must create 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");
At this point you can ask the user confirmation:
this.movendaFidoSDK.confirmTransaction(<rpRandomUuid>, <paymentTransaction>, <transactionConfirmationCallback>);
Finally manage the response:
@Override
public void onTransactionResult(UafServerResponse response) {
// submit transaction result to RPClient App back-end
}
The image generated by the Egomet FIDO system will look like this:
Free-text transaction
This operation permits to confirm a free-text transaction.
In order to create a free-text transaction, you must create 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);
At this point you can ask the user confirmation:
this.movendaFidoSDK.confirmTransaction(<rpRandomUuid>, <freeTextTransaction>, <transactionConfirmationCallback>);
Finally manage the response:
@Override
public void onTransactionResult(UafServerResponse response) {
// submit transaction result to RPClient App back-end
}
The image generated by the Egomet FIDO system will look like this:
Bank transfer transaction
This operation permits to confirm a bank transfer transaction.
In order to create a bank transfer transaction, you must create 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());
At this point you can ask the user confirmation:
this.movendaFidoSDK.confirmTransaction(<rpRandomUuid>, <bankTransferTransaction>, <transactionConfirmationCallback>);
Finally manage the response:
@Override
public void onTransactionResult(UafServerResponse response) {
// submit transaction result to RPClient App back-end
}
The image generated by the Egomet FIDO system will look like this:
SDK error management
The SDK can generate the following types of errors:
UAFApplicationError :
- onUserCancelled → The user declined the UAF operation by pressing the Cancel button
- onUserActionTimeout → User didn’t perform any action (accept/cancel) on FIDO request
- onNoSuitableAuthenticator → No authenticator matching the authenticator policy
NetworkError:
- onConnectionError → Called when a transport connection error occurs;
- onServerUnderMaintenance → Called when FIDO System is under maintenance;
SDKError:
- onSDKGenericError → Called when SDK internal error occurs
on the Egomet FIDO System
- onSDKGenericError → Called when SDK internal error occurs
BusinessTransactionError:
- onUserNotFound → Called if transaction creation fails due to invalid user
Adesso sei pronto.
Compila le informazioni richieste e richiedi l'SDK. Se hai ancora dei dubbi, consulta le guide che troverai di seguito.
Scarica la FIDO UAF SDK