Details related to fingerprint payment

Copyright notice ： This article is an original blog article , For reprint, please attach the original source link and this statement

# Details related to fingerprint payment ( With QSEE For example )#

## One . AuthToken Handle ##

###1.AuthToken Format and definition （CA Lateral heel TA Same side ）###

	typedef struct __attribute__((__packed__)) {
		uint8_t version;  // Current version is 0
		uint64_t challenge;
		uint64_t user_id;             // secure user ID, not Android user ID
		uint64_t authenticator_id;    // secure authenticator ID
		uint32_t authenticator_type;  // hw_authenticator_type_t, in network order
		uint64_t timestamp;           // in network order
		uint8_t hmac[32];
	} 	hw_auth_token_t;


		Version ： this token Version number of 

		Challenge： Is the previous call preEnroll Yes, I can 64 Bit random number , Prevent this enroll Counterfeit by a third party 

		User SID ：  Security id, No android user id

		Athenticator ID：  Used to indicate different authentication permissions 

		Authenticator Type：0x00 Express Gatekeeper,0x01 Express Fingerprint

		Timestamp： Last boot time stamp 

		AuthToken HMAC key：  Use a special key and SHA-256 After the algorithm calculates the previous pile of parameters , The one I got  hmac value , Ensure the legitimacy and security of the previous parameters .

###2. from Keymaster TA And Auth Token key###

1. Fingerprint HAL Open when ,Fingerprint HAL( It will be abbreviated as HAL) towards Keymaster send out KEYMASTER_GET_AUTH_TOKEN_KEY command , And get the returned encryption key.

2. HAL Directional fingerprint TA( It will be abbreviated as TA) dispatch orders , In memory data sharing mode , towards TA Transmission from Keymater Obtained encryption key.

3. TA Use **qsee_decapsulate_inter_app_message()** Method , Through encryption key To get Keymaster TA The disclosure of the key

4. TA stay authenticate When , Create yourself Token And call QSEE Of qsee_hmac() Method , Use QSEE_HMAC_SHA256 Type algorithm to encrypt token , And share with others TA (Keymaster TA,Gatekeeper TA , also bio TA)

    retval = QSEEcom_start_app(&keymaster_handle,
    						OXI_KEYMASTER_APP_PATH,
    						OXI_KEYMASTER_APP_NAME,
    						shared_buffer_zise);
   
   
   
    km_get_auth_token_req_t* command = (km_get_auth_token_req_t*)
    	keymaster_handle->ion_sbuffer;
    	
    uint32_t command_length = QSEECOM_ALIGN(sizeof(km_get_auth_token_req_t*));
    	
    km_get_auth_token_rsp_t* response = (km_get_auth_token_rsp_t*)
    	(keymaster_handle->ion_sbuffer+command_length);
    	
   
    command->cmd_id = KEYMASTER_GET_AUTH_TOKEN_KEY;
    command->auth_type = HW_AUTH_FINGERPRINT;
   
    uint32_t response_length = shared_buffer_zise-command_length;
   
    retval = QSEEcom_send_cmd(keymaster_handle,
    						command,
    						command_length,
    						response,
    						response_length);
   

### Two . Fingerprint HAL Follow Fingerprint TA Details ###
####1.pre_enroll() Method ：####

TA Side create challenge And save ,TA Put this challenge Send it back to HAL, stay pre_enroll Method inside , direct return This challeng value

####2.enroll(…,const hw_auth_token_t *hat,…) Method ：####

enroll When , The system will send a message token to Fingerprint HAL,HAL This layer needs to be token Pass to TA Side ,TA Do the following related processing ：

1).TA Side meeting pair token Inside challenge With the pre_enroll When ,TA The saved challenge Compare the value of .

2).TA Lateral meeting , According to from keymaster TA Obtained encryption key, use qsee_hmac() Method , Use QSEE_HMAC_SHA256 Type of HMAC encryption , Compare the two hmac Whether the contents of the array are consistent ,
If it's not consistent , Then interrupt enroll process , direct return fall .

// Check the information passed down token->challenge Prior to preEnroll Stage saved g_challenge Are they the same? 
if (token && token->challenge == g_challenge) {
	g_user_id = token->user_id;
} else {
	LOGE(LOG_TAG "[%s] invalid or null auth token", __func__);
}

// testing token Whether the version is the same 
if (token && token->version != cmd->data.enroll.system_auth_token_version) {
	LOGE(LOG_TAG "[%s] invalid hat version code detected", __func__);
	err = ERROR_INVALID_HAT_VERSION;
	break;
}
// testing authenticator_type Whether the version is the same 
if (token && (token->authenticator_type & GF_HW_AUTH_FINGERPRINT)) {
	LOGE(LOG_TAG "[%s] invalid challenge detected", __func__);
	err = ERROR_INVALID_CHALLENGE;
	break;
}
/*token in , except hmac Take out other data , Then take this part of the data and use key And the corresponding encryption algorithm hmac*/
cpl_memcpy(&hat, token, sizeof(gf_hw_auth_token_t));
cpl_memset(&(hat.hmac), 0, hmac_len);
generate_hmac(&hat);
/* Compare newly generated hmac And passed down from the previous top token The built-in hmac Are they the same? , If it is the same, it is considered that this time enroll legal , Next IC It will switch to a working mode of drawing collection */
if (0 != cpl_memcmp(hat.hmac, token->hmac, hmac_len)) {
	LOGE(LOG_TAG "[%s] token authenticate failed", __func__);
	err = ERROR_UNTRUSTED_ENROLL;
	break;
}

####3.user_id problem ：####

user_id Is in enroll When the system passes to fingerprint HAL Layer of ,HAL The layer needs to pass this value to fingerprint TA Binding with fingerprint template in ,enroll When the system came in user_id
How much is the , be authenticate Returned to the system after success user_id How much should it be .

1).user_id stay enroll When generating fingerprint template after completion , Bind with fingerprint template .
2) After the fingerprint match is successful , obtain user_id, Assign this value to TA Created Token Medium user_id Elements .

3).TA Would be right Token Conduct HMA Algorithm encryption .

4).TA Will include user_id Of Token Pass to fingerprint Hal, from Hal Callback to system .

####4.authenticator_id problem :####

stay enroll After successful completion , The database that needs to generate fingerprint template according to id To generate authenticator_id, This is used to generate authenticator_id Will be used in two places ;

1). This value needs to be returned to fingerprint Hal, stay get_authenticator_id() Method inside , Go straight back to .

2). After the fingerprint match is successful , stay TA establish Token, Assign this value to Token Medium authenticator_id Elements .

3).TA Would be right Token Conduct HMA Algorithm encryption .

4).TA Will include authenticator_id Of Token Pass to fingerprint Hal, from Hal Callback to system .

####5.operation_id problem ：####

This value is very important , Because of the payment bio The interface will use this value , The procedure is as follows ：

1).authenticate(…, uint64_t operation_id,…) When , The system will pass this value to fingerprint HAL, Hal The layer needs to pass this value to fingerprint TA;

2). After the fingerprint match is successful , stay TA establish Token, Assign this value to Token Medium challenge Elements .

3).TA Would be right Token Conduct HMAC Algorithm encryption

4) call bio Interface set_auth_result(), Put this operation_id Pass to bio Interface .

    int32_t set_auth_result(boolean result, uint64_t finger_id, uint64_t operation_id)
{
 int32_t status = 0;
 bio_result bio_res;
 BIO_ERROR_CODE bio_err;

 bio_res.method = BIO_FINGERPRINT_MATCHING;
 bio_res.result = result;
 bio_res.user_id = BIO_NA;

 if (bio_res.result) {
      bio_res.user_entity_id = finger_id;
      bio_res.transaction_id = operation_id;//session_id
 } else {
      bio_res.user_entity_id = BIO_NA;
      bio_res.transaction_id = BIO_NA;
 }
 if ((bio_err = bio_set_auth_result(&bio_res, NULL)) != BIO_NO_ERROR) {
      status = -1;
 }
 return status;
}

### 3、 ... and . Alipay 、 Wechat payment ###

Pay this , Two interfaces need to be implemented , One is fingerprints list Interface , One is the interface that matches successfully .

1). The fingerprint list Interface , Need to initialize , Fingerprint template increase 、 to update 、 When deleting, call , Please refer to the code for details

2). Successful interface matching ( above set_auth_result Namely ), After the fingerprint matching is successful , stay TA Conduct Token HMAC After encryption, call base note

Both interfaces end up calling bio API Of bio_set_auth_result() Method . Our fingerprint manufacturer , Just implement the previous details , Just connect with the above two interfaces , The rest are platforms ,TEE And the payment to the manufacturer .

Reference resources ：auth token Here, please refer to google Official statement