5. Perform CDCVM verification

Overview

During a contactless transaction, NFC Wallet SDK can require the end user to authenticate to complete CDCVM verification.

Your digital wallet application must perform this authentication using the CDCVM method you configured earlier. See Set CDCVM method.

SDK integration

Handle authentication in ContactlessPaymentServiceListener.onAuthenticationRequired(). See Implement contactless payment callbacks.

To authenticate the end user, use the CHVerificationMethod provided by the SDK. Use it to obtain a DeviceCVMVerifier instance, then start authentication and listen for the result using DeviceCVMVerifyListener.

cvmResetTimeout tells you how long the verification stays valid. Use it to guide the end user for the second tap.

CDCVM verification with device keyguard

When the device keyguard is used as the CDCVM method:

//From a ContactlessPaymentServiceListener() implementation
//...

@Override
public void onAuthenticationRequired(
  PaymentService activatedPaymentService,
  CHVerificationMethod cvm,
  long cvmResetTimeout) {

    // check the CDCVM type
    if(cvm == CHVerificationMethod.DEVICE_KEYGUARD) {
        // Launch the Activity implemented to manage the Keyguard authentication screen
        // In this example the activity is called 'KeyguardActivity'
        Intent intent = new Intent(getApplicationContext(), KeyguardActivity.class);
        intent.putExtra(Tags.CVM, cvm);
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        startActivity(intent);
    }
}

//...

Implement KeyguardActivity in your digital wallet application. It must extend DeviceCVMKeyguardActivity. This enables CDCVM verification using device credentials.

The following example shows the implementation of the KeyguardActivity class:

public class KeyguardActivity extends DeviceCVMKeyguardActivity{

     private static String TAG = KeyguardActivity.class.getName();
     private PaymentBusinessService paymentBusinessService;
     private DeviceCVMVerifier chDeviceCVMVerifier;
     private TextView message;
     private boolean keyguardVerificationStart = false;
     private CharSequence title;
     private CharSequence message1;

     @Override
     protected void onCreate(Bundle savedInstanceState) {

      Log.d(TAG, "KeyguardActivity:onCreate");
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_device_keyguard);
      Log.d(TAG, "KeyguardActivity:unlockAndWake : start");
      unlockAndWake();
      Log.d(TAG, "KeyguardActivity:unlockAndWake : end");

      title=getString(R.string.keyguard_title);
      message1=getString(R.string.keyguard_message);

      Bundle extras = getIntent().getExtras();

      // get the cvm object from the bundle passed
      CHVerificationMethod cvm = (CHVerificationMethod) extras.getSerializable(Tags.CVM);

      message = (TextView) findViewById(R.id.message);

      paymentBusinessService = PaymentBusinessManager.getPaymentBusinessService();

      PaymentService paymentService = paymentBusinessService.getActivatedPaymentService();

      // thanks to the cvm object, get an instance of the corresponding DeviceCVMVerifier object
      chDeviceCVMVerifier = (DeviceCVMVerifier) paymentService.getCHVerifier(cvm);

      // set then the corresponding listener to the DeviceCVMVerifier object
      chDeviceCVMVerifier.setDeviceCVMVerifyListener(new DeviceCVMVerifyListener() {

      @Override
      public void onVerifySuccess() {
         // Verification was OK!
         message.setText("");
         KeyguardActivity.this.finish();
     }


      @Override
      public void onVerifyError(int errorCode, CharSequence charSequence) {
          //Not expected to be called
      }

      @Override
      public void onVerifyFailed() {
        // Verification is Not OK! User shall be asked to retry
        message.setText("Unable to autheticate. Please try again.");
      }


      @Override
      public void onVerifyHelp(int i, CharSequence charSequence) {
          //Not expected to be called
      }

      });

      cbDeviceCVMVerifier.setKeyguardActivity(this);

      //Start Authentication when the screen is ON and Unlock
      if (DeviceUtil.isDeviceScreenOn(getApplicationContext())) {

             Log.d(TAG, "Starting device keyguard authentication");
             keyguardVerificationStart = true;
             DeviceCVMVerifierInput input = new  DeviceCVMVerifierInput(title,message1);
             chDeviceCVMVerifier.startAuthentication(input);
       } else {
             Log.d(TAG, "Screen is disactivate, skiping keyguard authentication");
       }

     }

}

CDCVM verification with biometrics (fingerprint example)

Use this method when the device supports biometric authentication (fingerprint is shown in the example).

The following example shows how this mechanism can be implemented:

//From a ContactlessPaymentServiceListener() implementation
//...

@Override
public void onAuthenticationRequired(
  PaymentService activatedPaymentService,
  CHVerificationMethod cvm,
  long cvmResetTimeout) {

    // check the CDCVM type
    if(cvm == CHVerificationMethod.FINGERPRINT) {
        // Launch the  activity that manages the Fingerprint authentication screen
        // In this case this activity is called 'BioFingerprintActivity'
        Intent intent = new Intent(getApplicationContext(),
        BioFingerprintActivity.class);
        intent.putExtra(Tags.CVM, cvm);
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        startActivity(intent);
    }
}

//...

Implement a dedicated Activity that extends DeviceCVMKeyguardActivity. This enables fallback to device keyguard when biometric verification fails.

public class BioFingerprintActivity extends DeviceCVMKeyguardActivity {

    private static String TAG = BioFingerprintActivity.class.getName();
    private PaymentBusinessService paymentBusinessService;
    private DeviceCVMVerifier deviceCVMVerifier;
    private CancellationSignal cancellationSignal;
    private TextView message;
    private boolean isBioFPVerificationStarted = false;


    @Override
    protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_bio_fingerprint_2);
      unlockAndWake();
      Bundle extras = getIntent().getExtras();

      // get the cvm object passed through the bundle
      CHVerificationMethod cvm = (CHVerificationMethod) extras.getSerializable(Tags.CVM);

      message = (TextView) findViewById(R.id.message);
      paymentBusinessService = PaymentBusinessManager.getPaymentBusinessService();
      PaymentService paymentService = paymentBusinessService.getActivatedPaymentService();

      // thanks to the cvm object get an intance to the 'DeviceCVMVerifier'
      deviceCVMVerifier = (DeviceCVMVerifier) paymentService.getCHVerifier(cvm);

			// set the corresponding listener
      deviceCVMVerifier.setDeviceCVMVerifyListener(new DeviceCVMVerifyListener() {

            @Override
            public void onVerifySuccess() {
              // Verification is OK!
              message.setText("");
              BioFingerprintActivity.this.finish();
            }

            @Override
            public void onVerifyError(int errorCode, CharSequence charSequence) {

              Log.d(TAG, "BioFingerprintActivity:error :" + errorCode);

              // Special case when triggered in lock screen mode
              // FINGERPRINT_ERROR_CANCELED error is raised
              if (errorCode == FingerprintManager.FINGERPRINT_ERROR_CANCELED) {
                  Log.d(TAG, "restart Fp");
                  if (cancellationSignal != null)
                      cancellationSignal.cancel();

              isBioFPVerificationStarted=true;
              cancellationSignal = new CancellationSignal();
              DeviceCVMVerifierInput input = new DeviceCVMVerifierInput(cancellationSignal);
              deviceCVMVerifier.startAuthentication(input);
              }
              // usual handling of error code
              else {
                        message.setText(charSequence + ". Please try again...");
                        if(errorCode == FingerprintManager.FINGERPRINT_ERROR_LOCKOUT) {
                            confirmCredential("Verify by Keyguard", "Too many attempts. Please verify  using your PIN / Pattern / Password");
                  }
              }
            }

            @Override
            public void onVerifyFailed() {
                message.setText("Unable to recognize the fingerprint. Please try again.");
            }


            @Override
            public void onVerifyHelp(int i, CharSequence charSequence) {
                message.setText(charSequence + ". Please try again.");
            }

        });

        deviceCVMVerifier.setKeyguardActivity(this);
        cancellationSignal = new CancellationSignal();

        //Start Authentication when the screen is ON and Unlock
        if (DeviceUtil.isDeviceScreenOn(getApplicationContext())) {
            Log.d(TAG, "Starting Fingerprint authentication");
            DeviceCVMVerifierInput input = new DeviceCVMVerifierInput(cancellationSignal);
            deviceCVMVerifier.startAuthentication(input);
        } else {
            Log.d(TAG, "Screen is de-activated, skipping Fingerprint authentication");
        }
    }

  	/* In case of fingerprint verification failure, implementing the following callback is possible
    to fallback on the Keyguard verification.
    **/
    public void onKeyguardFallback(View v) {

      Log.d(TAG, "onKeyguardFallback");
      // call deviceCVMVerifier.startAuthentication(input)


    }

  	@Override
  	public void onCancel(View v) {
      Log.d(TAG, "Cancel authentication");
      cancelTransaction("The transaction has been cancelled.");
    }

    @Override
    public void onBackPressed() {
        Log.d(TAG, "onBackPressed()");
        cancelTransaction("The transaction has been cancelled.");
    }


    /*
    After cancelling the fingerprint biometric authentication, the Payment service shall be deactivated
    **/
  	private void cancelTransaction(String message) {
          if (cancellationSignal != null) {
              cancellationSignal.cancel();
          }
          PaymentBusinessManager.getPaymentBusinessService().deactivate();
    }

}

If the digital wallet application goes to the background, stop listening for fingerprint authentication.

This can be accomplished using the following code snippet:

@Override
public void onResume() {
       super.onResume();
       cancellationSignal=new CancellationSignal();
       deviceCVMVerifier.startAuthentication(cancellationSignal);
   }

@Override
public void onPause() {
     if(cancellationSignal != null)
             cancellationSignal.cancel();
}

Support lock screen scenarios (optional)

If you need to support authentication prompts when the device is locked, verify the following:

• Activities shown during payment are declared with showOnLockScreen=true.
• A wake lock is acquired and window flags are set to show the UI on the lock screen.
• Release the wakeLock when the payment completes to reduce battery usage.

Configure the following settings in the manifest, and implement the sample code as needed:

<activity
        android:name=".BioFingerprintActivity"
        android:showOnLockScreen="true"
        android:screenOrientation="portrait" />

@Override
public void onCreate() {
        //…
        unlockAndWake();
        //…
}

private void unlockAndWake() {

    PowerManager.WakeLock mWl;
    PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
    if (!pm.isScreenOn()) {
        mWl = pm.newWakeLock(
                PowerManager.SCREEN_BRIGHT_WAKE_LOCK | 
                PowerManager.FULL_WAKE_LOCK | 
                PowerManager.ACQUIRE_CAUSES_WAKEUP, "");
        mWl.acquire();
    }

    getWindow().addFlags(
            WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED | 
            WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON   | 
            WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON   | 
            WindowManager.LayoutParams.FLAG_DISMISS_KEYGUARD);
}

@Override
public void onDestroy() {

  try{
      if(null!=mW1){
          mWl.release();
      }
  }
 	catch(Exception e){ }
}

Delegated authentication

Delegated authentication lets your digital wallet application prompt the end user for authentication and then inform the SDK that the payment can proceed.

The authentication can use device keyguard or biometrics to unlock the underlying keystore protected by user authentication.

This flow applies when the SDK requests authentication during payment. Your digital wallet application can either:

• Prompt the end user for authentication, then call DeviceCVMVerifier.onDelegatedAuthPerformed(timeOfAuth).
• Reuse a recent successful authentication (within the configured key validity period) and call DeviceCVMVerifier.onDelegatedAuthPerformed(timeOfAuth) immediately.

If the end user aborts the transaction, call DeviceCVMVerifier.onDelegatedAuthCancelled().

@Override
public void onAuthenticationRequired(final PaymentService service, CHVerificationMethod cvm, long cvmResetTimeout) {
                            
  // only applicable for Biometric or KeyGuard method
   if(cvm == CHVerificationMethod.BIOMETRICS || cvm == CHVerificationMethod.DEVICE_KEYGUARD){
      // obtain the verifier
      final DeviceCVMVerifier verifier = (DeviceCVMVerifier)service.getCHVerifier(cvm);
                                
      // MPA perform authentication, providing the time-stamp of the authentication
      ...

      // time stamp is used by SDK to compare against current time, to make sure that it is still within the Key-Validity-Duration

      // MPA could configure CVM Type as FINGERPRINT if verification method is biometrics
      verifier.setCVMType(CVMType.FINGERPRINT);

      // it is also recommended that MPA performs a check and ensure that there are enough time left for the end user to perform the 2nd tap of a transaction.
      verifier.onDelegatedAuthPerformed(timeOfAuth);
                                
      // if user does not wish to perform the authentication MPA shall cancel the transaction
      verifier.onDelegatedAuthCancelled();
  }
}