HYPR Documentation Portal

HYPR is the leading provider of True Passwordless Security with millions of users deployed across the Global 2000.

Shared secrets are the #1 cause of enterprise breaches, fraud and phishing attacks.

HYPR is the first Authentication Platform designed to eliminate passwords and shared secrets - effectively removing the hackers’ primary target while eliminating fraud, phishing and credential reuse for consumers and employees across the enterprise.

FIDO Client Adapter

🚧

THIS GUIDE ASSUMES THAT YOU ALREADY HAVE THE HYPR SDK SETUP. Follow the Quick Start Setup Guide before continuing.

Overview

Describes the steps for integrating the HYPR FIDO Client Adapter into an app to facilitate decentralized registration, authentication, and deregistration.

Requirements

  • The HYPR AARs are in your Android project's app/libs directory
  • Gradle versions: 4.4
  • Android Plugin Version 3.1.3
  • minSdkVersion 23
  • targetSdkVersion 28

📘

SDK Build Tools

Since we're using Android plugin for Gradle that is higher than 3.0.0, the project automatically uses a default version of the build tools that the plugin specifies.

Update the app/build.gradle

📘

Include the HYPR AARs in your build.gradle

Once you have the HYPR AARs in your app/libs directory, please make sure to add them in your build.gradle. An example of how to include them is at the bottom of the build.gradle file below.

Add the following to your app/build.gradle

apply plugin: 'com.android.application'

android {
    compileSdkVersion 28
    defaultConfig {
        applicationId "<Place your application id here>"
        minSdkVersion 23
        targetSdkVersion 28
        multiDexEnabled true
        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
          
        ndk {
            abiFilters "armeabi-v7a", "x86", "armeabi", "mips"
        }
    }
  
    buildTypes {
        debug {
            minifyEnabled false
        }
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    dexOptions {
        javaMaxHeapSize "8g"
        jumboMode = true
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    testImplementation 'junit:junit:4.12'
    androidTestImplementation 'com.android.support.test:runner:1.0.2'
    androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'

    // Android
    implementation 'com.android.support:multidex:1.0.3'
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support:design:28.0.0'
    implementation 'com.android.support.constraint:constraint-layout:1.1.3'

    // GJON / POJO
    implementation 'com.google.code.gson:gson:2.8.2'
    implementation 'org.apache.commons:commons-lang3:3.5'

    // RxAndroid
    implementation group: 'io.reactivex.rxjava2', name: 'rxandroid', version: '2.0.2'
    implementation group: 'io.reactivex.rxjava2', name: 'rxjava', version: '2.1.12'
    implementation 'javax.annotation:jsr250-api:1.0'

    // Retrofit
    implementation 'com.squareup.retrofit2:retrofit:2.4.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.4.0'
    implementation 'com.squareup.retrofit2:adapter-rxjava2:2.4.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:3.9.0'

    // HYPR Common
    implementation(name: 'HyprCommonAdp', version: '3.9.0', ext: 'aar')

    // HYPR Fingerprint Authenticator Component
    implementation(name: 'HyprFingerprintAdp', version: '3.9.0', ext: 'aar')

    // HYPR Pin Component
    implementation(name: 'HyprPinAdp', version: '3.9.0', ext: 'aar')

    // HYPR FaceVoice Component
    implementation(name: 'HyprFaceVoiceAdp', version: '3.9.0', ext: 'aar')

    // Sensory SMMA
    implementation 'com.sensory:vvutils:3.8.2'
    implementation 'com.sensory.smma:model:1.11.1:[email protected]'
    implementation 'com.sensory.smma:model:1.11.1:[email protected]'
    implementation 'com.sensory.smma:model:1.11.1:[email protected]'

    // HYPR TEE
    implementation(name: 'crypto-release-2.2.1', ext: 'aar') {transitive=true}
    implementation(name: 'THPAgent', ext: 'aar') {transitive=true}
    implementation(name: 'TeeClient', ext: 'aar') {transitive=true}
    implementation(name: 'caCrypto', ext: 'aar') {transitive=true}
}

Sensory Face libs/m2repository

If Sensory Face is being used, then the libs/m2repository needs to be copied to the top-level application and the build.gradle file needs to be modified. Here is an example of adding the m2repository path to the top-level build.gradle file.

allprojects {
    repositories {
        maven { url "file://$rootProject.projectDir/libs/m2repository" }
        mavenLocal()
    }
}

HYPR Setup

📘

HyprInit and HyprFCA must be initiated before any fido client calls are made.

With that in mind, we suggest initializing during creation of the main activity as described below:

public class MainActivity extends AppCompatActivity {
   
      // This will be set to true when an action was successful
    private boolean mIsSuccess;
      // This will contain the payload that was sent to the "server"
    private String  mFidoPayloadToSendToServer;
    // This will contain the payload that was sent back from the "server"
    private String  mResultToString;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Set defaults
        mIsSuccess = false;
        mFidoPayloadToSendToServer = "";
        mResultToString = "";

        // Setup HyprInit
        HyprInit.getInstance().setup();
        // Initialize ADP/TrustData
        HyprInit.getInstance().initAdp(this, new HyprInit.InitTrustDataCallback() {
            @Override
            public void onInstallComplete() {
                // Initialize the FidoClientAdapter
                HyprFCA.getInstance().init(MainFCAActivity.this, true);
            }

            @Override
            public void onInstallError(@NonNull String error,
                                       @Nullable Throwable throwable) {
            }
        });
    }

Unintended behavior may occur when backgrounding the app during registration, authentication, deregistration, etc.

To prevent this behavior, include the following line in your MultiDexApplication subclass.

If you wish to not explicitly add the HyprLifecycleObserver, you can subclass HyprLifeCycleObserver and use the subclass instead.

Besides subclassing, you can also wrap this function call in your own function with whichever name you'd like.

@Keep
public final class App extends MultiDexApplication {

    @Override
    public void onCreate() {
        super.onCreate();
        ProcessLifecycleOwner.get().getLifecycle().addObserver(new HyprLifecycleObserver());
    }
}

Include MultiDexApplication subclass in AndroidManifest.xml

<manifest>
  <application
               android:name="<your file path to>/App"
</manifest>

Testing Reg/Auth/Dereg

📘

You can use commands from the HyprFCA to process FIDO Payloads.

📘

Registration requires a callback to handle the response.

// To process a registration request 
HyprFCA.getInstance().registerRequest(MainActivity.this, "<Payload goes here>", getRegisterCallback());

// To complete a registration, this should be done in the Register Callback shown below
HyprFCA.getInstance().registerComplete(MainActivity.this, boolean isSuccess, getRegisterCompleteCallback());


    private HyprFCACallback getRegisterCallback() {
        return new HyprFCACallback() {
            @Override
            public void onSuccess(@NonNull HyprStatusResult hyprStatusResult) {
                // TODO: Process the payload

                // TODO: Send to Fido server

                // TODO: Get real results back from server
                boolean resultsFromServer = getYourResultsFromServer();

                // send register complete
                HyprFCA.getInstance().registerComplete(MainFCAActivity.this, resultsFromServer, getRegisterCompleteCallback());
            }

            @Override
            public void onFail(@NonNull HyprStatusResult hyprStatusResult) {
                // send register complete
                HyprFCA.getInstance().registerComplete(MainFCAActivity.this, false, getRegisterCompleteCallback());
            }
        };
    }

    private HyprFCACallback getRegisterCompleteCallback() {
        return new HyprFCACallback() {
            @Override
            public void onSuccess(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Fido Operation sequence
                cleanup();
            }

            @Override
            public void onFail(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Fido Operation sequence
                cleanup();
            }
        };
    }

📘

Authenticate requires a callback to handle the response.

// To process an authentication request 
HyprFCA.getInstance().authenticateRequest(MainActivity.this, "<Payload goes here>", getAuthenticateCallback());

// To complete an authentication, this should be done in the Authenticate Callback shown below
HyprFCA.getInstance().authenticateComplete(MainActivity.this, boolean isSuccess, getAuthenticateCompleteCallback());

    private HyprFCACallback getAuthenticateCallback() {
        return new HyprFCACallback() {
            @Override
            public void onSuccess(@NonNull HyprStatusResult hyprStatusResult) {
                // TODO: Process the payload

                // TODO: Send to Fido server

                // TODO: Get real results back from server
                boolean resultsFromServer = getYourResultsFromServer();

                // send authenticate complete
                HyprFCA.getInstance().authenticateComplete(MainFCAActivity.this, resultsFromServer, getAuthenticateCompleteCallback());
            }

            @Override
            public void onFail(@NonNull HyprStatusResult hyprStatusResult) {
                mErrorCode = hyprStatusResult.getErrorCode();
                mErrorDisplayText = hyprStatusResult.getLowestLevelDisplayText();

                // send authenticate complete
                HyprFCA.getInstance().authenticateComplete(MainFCAActivity.this, false, getAuthenticateCompleteCallback());
            }
        };
    }

    private HyprFCACallback getAuthenticateCompleteCallback() {
        return new HyprFCACallback() {
            @Override
            public void onSuccess(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Fido Operation sequence
                cleanup();
            }

            @Override
            public void onFail(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Fido Operation sequence
                cleanup();
            }
        };
    }

📘

Deregistration requires a callback to handle the response.

// To deregister an authenticator
HyprFCA.getInstance().deregister(MainActivity.this, "<Payload goes here>", getDeregisterCallback());


    private HyprFCACallback getDeregisterCallback() {
        return new HyprFCACallback() {
            @Override
            public void onSuccess(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Fido Operation sequence
                cleanup();
            }

            @Override
            public void onFail(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Fido Operation sequence
                cleanup();
            }
        };
    }

Reset Fido Client Adapter

📘

You can use a command from the HyprFidoClientAdapter to reset the FIDO Client Adapter. This will clear the FIDO Client Adapter database of all authenticators and states.

// To reset the FIDO Client Adapter
HyprFCA.getInstance().reset(this, getResetCallback());


    private HyprFCACallback getResetCallback() {
        return new HyprFCACallback() {
            @Override
            public void onSuccess(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Operation sequence
                cleanup();
            }

            @Override
            public void onFail(@NonNull HyprStatusResult hyprStatusResult) {
                // cleanup at end of Operation sequence
                cleanup();
            }
        };
    }

Offline Mode

When there is no internet, offline mode will be enabled. We determine this by:

((ConnectivityManager) activity.getSystemService(Context.CONNECTIVITY_SERVICE)).getActiveNetworkInfo().isConnected() == false

In offline mode, a failure will be returned when:

  • There is no response cache
  • There is cache, but the facetId cannot be verified

In online mode, any network error will return a failure.

Error Handling and HyprStatusResult

Please see Error Handling for more info on the HyprStatusResult, HyprDisplayResult, and HyprDisplayCodes.

Localization

The strings.xml file in the Sample App contains all of the overridable strings. For more information on Android Localization please see:
https://developer.android.com/guide/topics/resources/localization

<!-- Loading Screen -->
    <string name="hypr_loading_button_skip">Skip</string>
    <string name="hypr_loading_button_learn">Learn About This App</string>

    <!-- Begin Screen -->
    <string name="hypr_begin_text_description">True Password-less Security\nPowered By\nDecentralized Authentication</string>
    <string name="hypr_begin_button_lets_begin">Let\'s Begin</string>

    <!-- Selection License Screen -->
    <string name="hypr_selection_text_description">To complete setup please scan QR code or input 6-digit PIN to pair your mobile device</string>
    <string name="hypr_selection_text_qr">SCAN QR</string>
    <string name="hypr_selection_text_info">ABOUT HYPR</string>
    <string name="hypr_selection_text_pin">ENTER PIN</string>

    <!-- Info Screen -->
    <string name="hypr_settings_manage">Manage</string>
    <string name="hypr_powered_by">POWERED BY</string>
    <string name="hypr_version">APP VERSION&#160;</string>
    <string name="hypr_contact_us">Contact Us</string>
    <string name="hypr_support">Support</string>

    <!-- Oob license accepted -->
    <string name="hypr_oob_license_accepted_title">Stay tuned…</string>
    <string name="hypr_oob_license_accepted_description">We are building your personalized experience</string>

    <!-- Browser Main Screen -->
    <string name="hypr_main_browser_instructions">Begin your demo experience on the web at</string>
    <string name="hypr_main_browser_instructions_1">Login to an online banking portal with Multi-Factor Biometrics.</string>
    <string name="hypr_main_browser_instructions_2">Approve a wire transfer with FIDO-certified Step-up Authentication.</string>
    <string name="hypr_main_browser_instructions_3">Learn how HYPR decentralized authentication eliminates credential reuse, prevents phishing and minimizes the risk of a breach.</string>
    <string name="hypr_main_browser_options">On the website, you can demo a secure password-less experience powered by HYPR:</string>
    <string name="hypr_main_browser_bank_url">demo.hypr.com</string>
    <string name="hypr_main_browser_login_successful_text">Login Successful</string>
    <string name="hypr_action_add_account">Add Account</string>

    <string name="hypr_main_browser_landing_screen_title">True-Passwordless Authentication</string>
    <string name="hypr_main_browser_landing_screen_subtitle">From HYPR</string>

    <!-- Workstation Main Screen -->
    <string name="hypr_main_workstation_title">Paired Workstations</string>

    <!-- Workstation Main No Internet Screen -->
    <string name="hypr_main_workstation_no_internet_one">Seems like you have no internet connection…</string>
    <string name="hypr_main_workstation_no_internet_two">Make sure you are connected to the internet and try again</string>
    <string name="hypr_main_workstation_no_internet_popup">No internet connection available</string>
    <string name="hypr_main_workstation_no_internet_popup_reconnecting">Reconnecting…</string>

    <!-- Workstation No Internet Screen -->
    <string name="hypr_workstation_no_internet_dialog_title">No Internet Connection</string>
    <string name="hypr_workstation_no_internet_dialog_message_delete">Could not delete selected workstation(s)… please check your internet connection and try again</string>
    <string name="hypr_workstation_no_internet_dialog_message_add_workstation">Could not add workstation… please check your internet connection and try again</string>
    <string name="hypr_workstation_no_internet_dialog_message_support">Support email could not be sent… please check your internet connection and try again</string>
    <string name="hypr_workstation_no_internet_dialog_message_reset">Could not reset application… please check your internet connection and try again</string>
    <string name="hypr_workstation_no_internet_dialog_message_workstation">Please check your internet connection and try again</string>

    <!-- Workstation Main None Screen -->
    <string name="hypr_main_workstation_none_add">Add a Workstation</string>

    <!-- Workstation Main Single Screen -->
    <string name="hypr_main_workstation_single_add">Add More Workstations</string>
    <string name="hypr_main_workstation_single_unlock">Tap to Unlock or Long Press for More Options</string>

    <!-- Browser Success Overlay Screen -->
    <string name="hypr_common_nicely_done_text">Nicely Done.</string>
    <string name="hypr_common_logged_in_welcome_text_long">You have successfully enrolled your decentralized biometrics and registered your trusted device with the Highlands Bank Demo Experience</string>

    <!-- Workstation Success Overlay Screen -->
    <string name="hypr_workstation_license_enroll_success_title">Nicely done.</string>
    <string name="hypr_workstation_license_enroll_success_text">Your mobile device is now paired with your workstation.</string>
    <string name="hypr_workstation_added_success_text">Added</string>
    <string name="hypr_workstation_unlocked_success_text">Unlocked</string>
    <string name="hypr_workstation_delete_success_text">Workstation Deleted</string>
    <string name="hypr_workstation_delete_multiple_success_text">Workstations Deleted</string>
    <string name="hypr_workstation_edit_success_text">Edit Successful</string>

    <!-- Workstation Fail Overlay Screen -->
    <string name="hypr_workstation_try">TRY</string>
    <string name="hypr_workstation_again">AGAIN</string>
    <string name="hypr_workstation_edit_fail_text">Edit Failed</string>
    <string name="hypr_workstation_already_exists">This computer is already paired.</string>
    <string name="hypr_workstation_max_limit_fail_text">You have reached the limit of paired workstations. Please remove unused workstations and try again.</string>
    <string name="hypr_workstation_logged_out_state_error">You must be logged in before you can unlock.</string>

    <!-- Workstation Config Overlay Screen -->
    <string name="hypr_overlay_config_edit">EDIT</string>
    <string name="hypr_overlay_config_delete">DELETE</string>
    <string name="hypr_overlay_config_history">HISTORY</string>

    <!-- Workstation Status Update Overlay Screen -->
    <string name="hypr_workstation_status_update">This workstation is already unlocked</string>

    <!-- Browser History Screen -->
    <string name="hypr_history_browser_title_1">Personal Account</string>
    <string name="hypr_history_browser_title_2">Login History</string>
    <string name="hypr_history_browser_no_history">No login history</string>

    <!-- Workstation History Screen -->
    <string name="hypr_history_workstation_title_2">Unlock History</string>
    <string name="hypr_history_workstation_no_history">No unlock history</string>

    <!-- Workstation Edit Screen -->
    <string name="hypr_edit_workstation_title">Edit Workstation Details</string>
    <string name="hypr_edit_workstation_name_hint">New Workstation Name</string>
    <string name="hypr_edit_workstation_default">This is my Default Workstation</string>

    <!-- Workstation Delete Screen -->
    <string name="hypr_delete_workstation_title">Deleting Workstation</string>
    <string name="hypr_delete_workstation_warning">WARNING</string>
    <string name="hypr_delete_workstation_text_1">You are about to delete a workstation that is paired with your mobile device.</string>
    <string name="hypr_delete_workstation_text_2">Please don’t forget to remove this mobile device from this workstation.</string>
    <string name="hypr_delete_workstation_question">Are you sure?</string>

    <!-- Workstation Delete Multiple Screen -->
    <string name="hypr_delete_multiple_workstations_title">Deleting Workstations</string>
    <string name="hypr_delete_multiple_workstations_text_1">You are about to delete %1$d workstations that are paired with your mobile device.</string>
    <string name="hypr_delete_multiple_workstations_text_2">Please don’t forget to remove this mobile device from the following workstations.</string>

    <!-- Workstation Manage Screen -->
    <string name="hypr_manage_workstations_default">default</string>
    <string name="hypr_manage_workstations_title">Manage Workstations</string>
    <string name="hypr_manage_workstations_none">You do not have any paired workstations.</string>

    <!-- Step-Up Authentication Screens -->
    <string name="hypr_transaction_step_up">Step-Up Authentication Required</string>
    <string name="hypr_transaction_higher_level">This transaction requires a higher level of security</string>
    <string name="hypr_transaction_amount_text">$1000.00</string>
    <string name="hypr_transaction_amount">$5,750.00</string>
    <string name="hypr_transaction_success_result">Bank Wire Complete</string>
    <string name="hypr_transaction_generic_error">Something went wrong&#8230;</string>

    <!-- PIN Screens -->
    <string name="hypr_pin_entry_text">Please enter your 6-digit pin to approve authentication.</string>
    <string name="hypr_pin_entry_transaction_text">Please enter your 6-digit pin to approve step-up authentication.</string>
    <string name="hypr_pin_transaction_error">PIN Authentication Failed. Please Try Again.</string>

    <!-- Finger Screens -->
    <string name="hypr_transaction_finger_instructions">Please Authenticate to approve step-up authentication.</string>
    <string name="hypr_transaction_fingerprint_error">Fingerprint Authentication Failed. Please Try Again.</string>

    <!-- Face Screens -->
    <string name="hypr_transaction_face_error">Face Authentication Failed. Please Try Again.</string>

    <!-- Settings Screen -->
    <string name="hypr_info_title">TRUST ANYONE</string>
    <string name="hypr_info_text_1">"HYPR is the leading provider of decentralized authentication with millions of password-less users secured across the Fortune 500. Named a “Cool Vendor” by Gartner, HYPR is trusted by major enterprises such as Mastercard and Samsung to eliminate fraud, enhance user experience, and minimize the risk of a breach."</string>
    <string name="hypr_info_text_2">"Companies often store user credentials in a centralized database targeted by hackers. Centralized passwords create a single point of failure and have remained the #1 cause of mass breaches and credential reuse – until now."</string>
    <string name="hypr_info_text_3">"The HYPR solution ensures that your users’ credentials always remain safe on personal devices. Eliminating centralized passwords enables HYPR to remove the target and provide a secure password-less experience for your customers and employees."</string>
    <string name="hypr_info_text_4">"By decentralizing user authentication, HYPR minimizes the risk of a breach, eliminates credential reuse, and enables enterprises to <b>Trust Anyone</b>."</string>
    <string name="hypr_info_email">[email protected]</string>

    <!-- Reset App -->
    <string name="hypr_reset_app">Reset Application</string>
    <string name="hypr_reset_app_workstation">Reset App</string>
    <string name="hypr_reset_app_text">Are you sure you want to reset the application?</string>

    <!-- Reset App -->
    <string name="hypr_contact_support_email">[email protected]</string>
    <string name="hypr_contact_support_subject">Questions? Feedback? We\'ll be happy to hear from you!</string>
    <string name="hypr_contact_support_email_title">Send HYPR an email&#8230;</string>
    <string name="hypr_contact_support_email_body_top">-= PLEASE DO NOT TYPE BELOW THIS LINE =-</string>
    <string name="hypr_contact_support_email_body_app_id">App Id:&#160;</string>
    <string name="hypr_contact_support_email_body_app_version">App Version:&#160;</string>
    <string name="hypr_contact_support_email_body_os">OS:&#160;</string>
    <string name="hypr_contact_support_email_body_api">API:&#160;</string>
    <string name="hypr_contact_support_email_body_manufacturer">Manufacturer:&#160;</string>
    <string name="hypr_contact_support_email_body_model">Model:&#160;</string>
    <string name="hypr_contact_support_email_body_rp_url">RP URL:&#160;</string>
    <string name="hypr_contact_support_email_body_rp_app">RP App:&#160;</string>
    <string name="hypr_contact_support_email_body_identifier">Identifier:&#160;</string>

Updated 11 months ago

FIDO Client Adapter


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.