Foreword

The provisioning is the step that consists in feeding the Secure Client with all the necessary information it needs to connect to the Secure Backend.

The following figure describes the provisioning process:

• The provisioning is part of the merchant application onboarding process.

• It is assumed that the merchant’s backend administrator has defined the device models, and registered devices and users for each application instance.

• The way these parameters are persisted, encoded, and transmitted to the application onboarding process is not known to the SCSDK.

Howto

Provisioning can be achieved via the singleton instance of the SecureClient class.

// Get the class instance and start provisioning
var secureClient = SecureClient.getInstance(activity, AOneAppSecurityCbk(activity))

...

secureClient.provision(settings)
            

Now there are a few things to consider in this example: the callbacks class AOneAppSecurityCbk and the provisioning settings.

Callbacks

Some of the SecureClient class methods are asynchronous. The AOneAppSecurityCbk class purpose is to provide callback functions for when the asynchronous tasks are complete or terminated for some reason.

The AOneAppSecurityCbk class must derive the IAppSecurityCbk interface. The rest of its content is implementation dependent. Find below an basic implementation example:

class AOneAppSecurityCbk() : IAOneAppSecurityCbk {
    
    override fun getApplicationInfo(): String {
        Log.v("${this::class.java.simpleName}", "getApplicationInfo")
        return "{}"
    }

    override fun notifyError(error: Int) {
        Log.v("${this::class.java.simpleName}", "notifyError - error: " + error)
    }

    override fun notifyException(e: Exception) {
        Log.v("${this::class.java.simpleName}", "notifyException - exception: " + e)
    }

    override fun notifyExit() {
        Log.v("${this::class.java.simpleName}", "notifyExit")
    }

    override fun notifyRemediation(data: String?) {
        Log.v("${this::class.java.simpleName}", "notifyRemediation")
    }

    override fun pinEnterResult(params: Any?, status: IAOneAppSecurityCbk.PinStatus, 
                                pin: ByteArray?, error: Int) {
        Log.v("${this::class.java.simpleName}", "pinEnterResult - params: ${params},
              status: ${status}, error: ${error}")
    }

    override fun syncExecuteResult(params: Any?, error: Int) {
        Log.v("${this::class.java.simpleName}", "syncExecuteResult - error: ${error},
              params: ${params}")
    }
}

Provisioning settings

The provisioning settings are the information the Secure Client will need to connect to the Backend Server. There are to be provided as a JSON string with the following parameter:

• domain: Secure Backend IP address or hostname

• port

• osType (should be set to “Android”)

• hardwareDescription

• terminalId: terminal ID received when registering the device in the database

• clientId: client ID received when registering the user in the database

• secret: client secret received when registering the user in the database

• ownCertPass: the owner of the backend certificate

• checkServCert: some field to be verified inside the backend certficates

• certDir: certificates location inside the phone

• safetynetKey: the Google Safetynet access key

Which gives us the following code as example:

// Provisioning parameters
val settings = """
    |{
    |"domain":"dev.atheos.ca",
    |"port":443,
    |"osType":"Android",
    |"hardwareDescription":"AmadisOneClient",
    |"terminalId":"11111111111",
    |"clientId":"<client_id>",   
    |"secret":"<client_secret>",
    |"ownCertPass":"amadis",
    |"checkSrvCert":"iSSuer.Cn =  Alexandre Munsch    |   subJect/St   ~    Quebec   ",
    |"certDir": "${getSecureClientDir()}",
    |"safetynetKey":"<safetynet_key>"
    |}""".trimMargin()

Flow

The provisioning step is supposed to happen only once in the application lifetime (unless some parameters need to be changed - for example, a change of user ID or a change of domain name, etc…).

If you want to verify whether provisioning has already been completed, please call the isProvisioned() function. In case you need to change the provisioning data a call to the clearProvision() function must be made beforehand.