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)

Once the pinEnter() function is called the screen control is taken over by our security layer until the user presses Enter, Cancel or the timeout is reached.

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 PIN block generated by the Secure Client follows EMV PIN block format recommendations but does not contain the PAN as it would be against PCI security requirements. This is why we call it “pseudo” PIN block.

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:

E(PIN block) = ID(K_pin-pub)||E_{RSA-OAEP-SHA-1}(K_pin-pub, K_pin-session)||E_aes-ecb(K_pin-session, pin-block)

Which translates into:

Object

Length (bytes)

Comments

Key ID

5

RSA key ID used for the session key encryption

Encrypted KEK

256

Encrypted KEK block:

encrypted with RSA key (RSA/ECB/OAEPWithSHA-256AndMGF1Padding)
cleartext contains the KEK (16 bytes) and the IV (16 bytes)

Encrypted pseudo PIN block

256

Encrypted pseudo PIN block:

encrypted with KEK key (AES/CBC/NoPadding)
cleartext contains the pseudo PIN block (see below)

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

Object	Length (bytes)	Comments
x	1
Length	1
PIN	4 to 16	Non-used digits set to random padding

Example

Below is an example of data received after a successful PIN entry:

3cb9dd2f5021af506a74a0b14bf1d67479173e1302404d645fe2ddd382a26097be43c799a6d79bd759e3a
e0cabab835b31cb859ed8d900264522c2cef426de597becad0738c78578aa5538df3ad9f9f6a0c5c25e45
30d1754021c99faa037aabfe90cd1af8c3a68ebeabd9dce2df3cdf9208a55e7c94a13331b362fc3fedc57
e766c8aa8bc3ce750196857b832ff81027bd4168422a7b8ca1334a9df358038c48f9fb3d96c80f06d2899
87ffd313984cd540faa08e280911524fde4956091c8704455d7c652022a244955d6c60407b32a31c52f23
c93896f292f489e9c9349047997024ae33cf997bb5436bfdfb53eed28021354baab0fecd30bf3c58cacf0
d6a309d25919948c521e8d795d16b74a3fe4a114709e

Which can be split into:

The key ID:

3cb9dd2f50

The encrypted KEK:

21af506a74a0b14bf1d67479173e1302404d645fe2ddd382a26097be43c799a6d79bd759e3ae0cabab835
b31cb859ed8d900264522c2cef426de597becad0738c78578aa5538df3ad9f9f6a0c5c25e4530d1754021
c99faa037aabfe90cd1af8c3a68ebeabd9dce2df3cdf9208a55e7c94a13331b362fc3fedc57e766c8aa8b
c3ce750196857b832ff81027bd4168422a7b8ca1334a9df358038c48f9fb3d96c80f06d289987ffd31398
4cd540faa08e280911524fde4956091c8704455d7c652022a244955d6c60407b32a31c52f23c93896f292
f489e9c9349047997024ae33cf997bb5436bfdfb53eed28021354baab0fecd30bf3c58cacf0d6a309d259
19

The encrypted pseudo PIN-block:

948c521e8d795d16b74a3fe4a114709e

Applying an RSA decryption (RSA/ECB/OAEPWithSHA-256AndMGF1Padding) on the “encrypted KEK” block will lead to:

The KEK:

eaa5e9bbd66899cc561ee20ca9b3e775

The IV:

00000000000000000000000000000000

Applying a AES decryption (AES/CBC/NoPadding) on the “encrypted pseudo PIN-block” will provide the following pseudo PIN block data:

1415958944b2c2d77cb7fad1622bb213