Foreword

PIN entry on Tap to Phone solutions, because of its very sensitive nature, is handled by the Secure Client (and the Secure Backend). The flow is relatively simple, the PIN prompt is triggered by one API call. The output of the PIN entry is provided through a callback.

PIN prompt

To launch the PIN entry screen, once must call the pinEnter() method from the AOneAppSecurity class as follows:

AOneAppSecurity.getInstance(this.context, AOneAppSecurityCbk(this.activity))
               .pinEnter(activity, amount, message, min, max, timeout, feedback)

With:

• amount: the amount string, including currency (ex: $ 51.00)

• message: the customer message (ex: Please enter PIN)

• min: the minimum number of PIN digits (usually 4)

• max: the maximum number of PIN digits

• timeout: the PIN entry timeout in seconds

• feedback: physical and audible feedback flags (ex: AOneAppSecurity.PIN_ENTRY_FB_HAPTIC or AOneAppSecurity.PIN_ENTRY_FB_SOUND)

PIN entry result

After one of the above events happens (e.g. Enter, Cancel or timeout), display control is given back to the application and the PIN entry result is provided by the pinEnterResult() callback:

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}")  
}

With:

• params: optional parameters (null for now)

• status: PIN entry result (Success, Cancelled, Timeout, etc…)

• pin: the encrypted PIN block

• error: error code

PIN block format

The partial PIN block is encrypted using the AES-ECB algorithm and a 128 bits AES key, K_pin-session. K_pin-session is unique for each PIN block. The 8 bytes partial PIN block is padded with an 8 bytes random byte string. K_pin-session is wrapped using the RSA-2048 K_pin-pub using the PKCS#1 RSA-OAEP algorithm with SHA-1 as digest.

The format of the partial PIN block cryptogram is:

Which translates into:

The pseudo PIN block is encoded in ISO-0 format, with the PIN set as expected and the PAN set to “F…F”: