第三篇、iOS指纹接入

1.1 引入SDK

1.1.1 添加IFAA生物认证服务SDK

在 Apple Xcode 中，选择 TARGETS，点击 General 标签页， 展开 Linked Frameworks and Libraries 列表，添加用户收到的ios Demo 中 frameworks 文件夹中的SDK，列表如下：

//如果项目之前集成的有其他openssl，在发生冲突时可以删除APOpenSSL.framework保留其他的openssl即可APOpenSSL.frameworkAPSecCrypto.frameworkIFAAAuthenticator.frameworketasSdk.framework

1.1.2 添加系统库

在 Linked Framweworks and Libraries 中添加如下 iOS 系统库：

Security.frameworkAVFoundation.frameworkLocalAuthentication.frameworkFoundation.frameworklibc++.tbd

1.2 初始化信息配置类

字段类型描述

authTypeInt认证方式

trancIdNSString能够唯一区别本次IFAA操作的交易ID。此交易ID可以唯一定位此次操作。

userIdNSString用户ID或者能够区别用户的唯一表示信息。

payloadNSString业务的附加信息，记录在ifaa log 中，作为扩展字段不能为nil，可为空字符串

trancTypeNSString本次IFAA操作的业务场景，比如登录："Login"，支付："Pay"

fallbackTitleNSString验证TouchID时在错误一次的后显示出的可选项按钮标题，若需要取消该按钮的显示，传入一个空字符串即可。

reasonTitleNSString验证理由说明文字，会显示在对话框中部。

cancelTitle

NSString取消按钮显示文字。

useLocalAuthBOOL是否进行本地指纹验证（该属性只能控制注册流程中是否进行本地指纹验证）

EtasConfiguration 是 SDK 的信息配置类，在使用各个功能前，需要实例化 EtasConfiguration ：

EtasConfiguration*_config=[[EtasConfigurationalloc]initWithAuthType:authTypetrancId:trancIduserId:userIdpayload:payloadtrancType:trancTypefallbackTitle:fallbackTitlereasonTitle:reasonTitlecancelTitle:cancelTitle];

1.3 查询机器是否支持ifaa能力

       IFAA 能力虽然覆盖了众多的机型但是始终没有做到百分百的机型覆盖，因此可以通过查询接口来查询设备是否支持ifaa能力。

 ETASManager 中提供了判断当前设备是否支持某种认证类型，现有的认证类型有指纹、人脸两种认证类型，详见 IFAAErrorCodeEnum 的枚举。下面代码是查询方法的定义：

/*****检查本机是否支持ifaa, 支持那种ifaa认证***- returns: ‘code’有可能返回如下状态码IFAA_STATUS_NOT_SUPPORT  : 本机不支持ifaaIFAA_STATUS_FINGERPRINT  : 本机支持ifaa, 认证类型是指纹IFAA_STATUS_FACE_ID  : 本机支持ifaa, 认证类型是本地人脸*/+(enumIFAAErrorCodeEnum)isSupportIFAA

使用此方法示例代码如下所示：

// 检查本机是否支持 指纹 认证类型if([EtasManagerisSupportIFAA]==IFAA_STATUS_FACE_ID) {authtype=AUTHTYPE_FACEID;}elseif([EtasManagerisSupportIFAA]==IFAA_STATUS_FINGERPRINT){authtype=AUTHTYPE_FINGERPRINT;}else{authtype=IFAA_STATUS_NOT_SUPPORT;        }

1.4 查询App是否有面容ID的使用权限

该接口只有在查询本机是否支持IFAA的返回结果为人脸（即设备为iPhone X和之后的使用Face ID的手机）时才有调用的必要。

/*****检查App是否有面容ID的权限***- returns: ‘bool’YES  App拥有面容ID的使用权限或者用户还没有决定面容ID的允许拒绝NO    用户拒绝App使用面容ID的权限*/+(bool)hasPermissionForFaceID;

1.5 IFAA注册

SDK 对外提供 EtasRegister 类实现 IFAA 的注册流程，以下是主要的函数定义：

// 注册初始化-(EtasResult*)regInit;// 执行注册操作-(void)register:(NSString*)msgetasCallback:(EtasCallback)etasCallback;// 完成注册操作-(EtasResult*)regFinish:(NSString*)msg;

上面时序图中，客户端只需要关注 客户端APP,ETAS SDK 以及 客户业务服务器。

要完成整个注册流程，首先需要调用 regInit方法，当 etasResult.code为 IFAA_SUCCESS 时将字符串 etasResult.msg作为消息体 发送到服务端。

其他code：IFAA_STATUS_PASSCODE_NOT_SET锁屏密码没设置IFAA_STATUS_NOT_ENROLLED本地没有录入任何指纹

接着，调用register来完成注册操作，其中参数 ifaaMsg为服务端接收到注册初始化产生的报文后返回的响应报文。参数 etasCallback 为注册操作的回调， 当 etasResult.code 为 IFAA_SUCCESS时，将etasResult.msg 作为注册第二次请求需要发送到服务端的报文。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_CLIENT_ERROR本地注册失败IFAA_STATUS_RESULT_CANCELED点击了取消IFAA_STATUS_RESULT_FALLBACK点击了fallbackIFAA_STATUS_RESULT_AUTH_FAIL连续三次本地认证失败IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配IFAA_PERMISSION_DENIED当前应用未获取FaceID权限

最后调用 regFinish方法来完成注册操作， 其中 ifaaMsg 为注册第二次请求服务端返回的报文，当执行方法返回的 EtasResult.code为IFAA_SUCCESS 时注册成功，至此，整个注册流程结束。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配

以下是示例代码：

EtasRegister*etasRegister=[[EtasRegisteralloc]initWithEtasConfiguration:_config];etasResult=[etasRegisterregInit];if(etasResult.code!=IFAA_SUCCESS) {//错误处理return;        }...//post request and return response as msg[etasRegisterregister:ifaaMsgetasCallback:^(EtasResult*etasResult) {if(etasResult.code!=IFAA_SUCCESS) {//错误处理return;            }...//post request and return response as msgEtasResult*etasResult=[etasRegisterregFinish:ifaaMsg];        }];

1.6 IFAA认证

1.6.1 IFAA认证

      SDK 提供 EtasVerify 实现 IFAA 的认证操作, 以下是主要的函数定义：

// IFAA 认证初始化-(EtasResult*)authInit;// 执行本地认证操作-(void)auth:(NSString*)msgetasCallback:(EtasCallback)etasCallback;// 完成认证操作-(EtasResult*)authFinish:(NSString*)msg;

要完成整个认证流程，首先需要调用 authInit方法，当 etasResult.code为 IFAA_SUCCESS 时将字符串 etasResult.msg作为消息体 发送到服务端。

其他code：IFAA_STATUS_PASSCODE_NOT_SET锁屏密码没设置IFAA_STATUS_NOT_ENROLLED本地没有录入任何指纹IFAA_STATUS_NOT_REGISTERED本地尚未注册IFAA_PERMISSION_DENIED当前应用未获取FaceID权限

接着，调用auth来完成认证操作，其中参数 ifaaMsg 为 ，为服务端接收到认证初始化产生的报文后返回的响应报文。参数 etasCallback 为注册操作的回调， 当 etasResult.code 为 IFAA_SUCCESS时，将etasResult.msg 作为注册第二次请求需要发送到服务端的报文。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_CLIENT_ERROR本地注册失败IFAA_STATUS_RESULT_CANCELED点击了取消IFAA_STATUS_RESULT_FALLBACK点击了fallbackIFAA_STATUS_RESULT_AUTH_FAIL连续三次本地认证失败IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配IFAA_PERMISSION_DENIED当前应用未获取FaceID权限

最后调用 authFinish方法来完成认证操作，其中 ifaaMsg 为注册第二次请求服务端返回的报文，当执行方法返回的 EtasResult.code为IFAA_SUCCESS 时认证成功，至此，整个认证流程结束。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_WRONG_AUTHDATAINDEX指位/人脸不匹配，需要更新指位/人脸IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配

以下是示例代码：

EtasVerify*etasVerify=[[EtasVerifyalloc]initWithEtasConfiguration:_config];etasResult=[etasVerifyauthInit];if(etasResult.code!=IFAA_SUCCESS) {//错误处理return;        }...//post request and return response as msg[etasVerifyauth:ifaaMsgetasCallback:^(EtasResult*etasResult) {if(etasResult.code!=IFAA_SUCCESS) {//错误处理return;            }...//post request and return response as msgEtasResult*etasResult=[etasVerifyauthFinish:ifaaMsg];        }];

1.6.2 IFAA多指位更新

1.6.2.1 为什么要更新指位/人脸

要使用IFAA认证，首先要进行IFAA的注册，而IOS 中IFAA 的一次注册是绑定当前所有的系统指纹的指纹集/人脸集的，也就是说一次注册以后注册时系统存在的所有指纹/人脸都能够认证成功，当系统指纹/人脸相对于注册时的系统指纹/人脸集发生变更时（新增或删除）。IFAA 需要通过更新指位/人脸的方式实现当前指纹/人脸集的更新。

1.6.2.2 何时进行指位/人脸更新

在完成认证接口中，若etasResult.code为IFAA_ERR_WRONG_AUTHDATAINDEX，则需要进行指纹/人脸更新的操作。

1.6.2.3 指位/人脸更新需要注意哪些问题

指位/人脸更新是一个比较敏感的操作，建议(不是必须)先进行密码或者支付码等操作后再进行指位更新操作。指位/人脸更新和指纹/人脸认证是一个连续的流程，当完成认证接口authFinish的返回值etasResult.code为IFAA_ERR_WRONG_AUTHDATAINDEX，进行指纹/人脸更新的操作。

// 指位更新初始化-(EtasResult*)templateUpdaInit:(NSString*)ifaaMessage;//完成指位更新操作-(EtasResult*)templateUpdaFinish:(NSString*)msg;

要更新指位需要调用 templateUpdata方法，其中参数 msg 是在认证流程的认证操作完成中（authFinish方法），如果返回 etasResult.code 错误码为IFAA_WRONG_AUTHDATAINDEX 时，etasResult.msg就作为参数传入 templateUpdata方法中，此方法执行结束后，返回的报文 EtasResult 类型中，当 etasResult.code 为IFAA_SUCCESS 时 ，etasResult.msg 为指纹更新请求需要发送到服务端的报文。

其他code：无

接着调用 templateUpdaFinish方法，其中参数 ifaaMsg 为 指纹更新请求服务端返回的报文，方法执行完毕后返回 EtasResult对象，其中当 etasResult.code为 IFAA_SUCCESS 时，更新指位成功。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配

注：

指位更新是一个比较敏感的操作，建议(不是必须)先进行密码或者支付码等操作后再进行指位更新操作。

指位更新和指纹认证是一个连续的流程，必须在指纹认证失败，并且返回状态码为 IFAA_WRONG_AUTHDATAINDEX 的时候执行。

以下是示例代码：

EtasTemplateUpdater*etasTemplateUpdater=[[EtasTemplateUpdateralloc]initWithEtasConfiguration:_config];etasResult=[etasTemplateUpdatertemplateUpdaInit:msg];...//post request and return response as message    etasResult=[etasTemplateUpdatertemplateUpdaFinish:ifaaMsg];

1.7 IFAA注销

SDK 提供 EtasRegister 类进行 IFAA 注销操作，主要有如下函数：

// 注销初始化-(EtasResult*)deregInit;// 执行终端注销操作-(void)dereg:(NSString*)msgetasCallback:(EtasCallback)etasCallback;

要完成整个认证流程，首先需要调用 deregInit方法，当 etasResult.code为 IFAA_SUCCESS 时将字符串 etasResult.msg作为消息体 发送到服务端。

其他code：IFAA_STATUS_PASSCODE_NOT_SET锁屏密码没设置IFAA_STATUS_NOT_ENROLLED本地没有录入任何指纹IFAA_STATUS_NOT_REGISTERED本地尚未注册

接着，调用dereg来完成认证操作，其中参数 ifaaMsg 为 ，为服务端接收到注销初始化产生的报文后返回的响应报文。参数 etasCallback 为注册操作的回调， 当 etasResult.code 为 IFAA_SUCCESS时，将etasResult.msg 作为注销第二次请求需要发送到服务端的报文。 当 etasResult.code 为 IFAA_SUCCESS 时，完成注销。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_STATUS_NOT_REGISTERED为未注册状态IFAA_CLIENT_ERROR本地注销失败IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配

以下是示例代码：

// 初始化EtasDeregister*etasDeregister=[[EtasDeregisteralloc]initWithEtasConfiguration:_config];etasResult=[etasDeregisterderegInit];// 判断操作是否成功if(etasResult.code!=IFAA_SUCCESS) {//错误处理return;        }...//post request and return response as msg    [etasDeregisterdereg:ifaaMsgetasCallback:^(EtasResult*etasResult) {if(etasResult.code!=IFAA_SUCCESS) {//错误处理return;                }//注销成功        }];

1.8 IFAA状态查询

状态查询主要用于客户APP在需要确定用户是否已经在该终端注册过指纹的场景，如用户启动新安装的客户APP时，需要检查该用户是否已在该设备上注册过指纹，以避免用户重复注册。SDK 提供 EtasStatus 类进行 IFAA状态查询，主要有如下函数：

// 查询 ifaa 注册状态初始化-(EtasResult*)checkStatusInit;// 解析查询结果-(EtasResult*)parseResult:(NSString*)msg;// 查询手机终端是否已经注册-(EtasResult*)checkLocalStatus:(NSString*)token;

要完成整个认证流程，首先需要调用 checkStatusInit方法，当返回码不同时有不同的处理：

当 etasResult.code为IFAA_STATUS_REGISTERED 时，表示本地取到了 token，已经是注册状态，就不发请求到服务端

当 etasResult.code为 IFAA_SUCCESS 时将字符串 etasResult.msg作为消息体 发送到服务端。

其他code：无

接着，调用parseResult来解析查询结果，其中参数 ifaaMsg 为服务端接收到认证初始化产生的报文后返回的响应报文。当etasResult.code 为 IFAA_SUCCESS 时 ，etasResult.msg为 token，在查询手机终端是否已经注册中要使用。

其他code：IFAA_SERVER_ERROR返回的报文数据异常IFAA_POLICY_REJECTEDIFAA已被策略管理禁用IFAA_USER_REJECTE用户已被禁用IFAA_APPID_NOT_FOUND应用白名单中未设置应用标识IFAA_DEVICE_MODEL_NOT_FOUND设备型号不存在IFAA_SIGNATURE_FAIL未获取到签名数据IFAA_STATUS_NOT_REGISTERED为未注册状态IFAA_AUTHENTICATOR_DISABLE认证器被禁用IFAA_AUTHENTICATOR_NOT_FOUND未找到相应的认证器IFAA_DEVICE_KEY_NOT_FOUND设备密钥被禁用IFAA_PROTECT_PAYLOAD_NOT_MATCH受保护的业务数据不匹配

最后调用 checkLocalStatus(方法来 查询手机终端是否已经注册， 其中 token 为在解析查询结果中在成功码情况下的etasResult.msg 中字符。因为注册数据放在 TEE 里面，和 apk 无关，所以需要这一步，返回结果中当 etasResult.code为 IFAA_SUCCESS 时，已经注册。

其他code：IFAA_STATUS_NOT_REGISTERED为未注册状态IFAA_CLIENT_ERROR本地注册状态异常

以下是示例代码：

EtasStatus*etasStatus=[[EtasStatusalloc]initWithEtasConfiguration:_config];etasResult=[etasStatuscheckStatusInit];if(etasResult.code==IFAA_STATUS_REGISTERED) {//已经注册return;        }      ...//post request and return response as msgetasResult=[etasStatusparseResult:ifaaMsg];etasResult=[etasStatuscheckLocalStatus:etasResult.msg];

1.9 IFAAErrorCodeEnum 的枚举值

EtasResult 实体类中的 code 的枚举

枚举值值业务意义

IFAA_SUCCESS0成功

IFAA_STATUS_NOT_SUPPORT1终端不支持 IFAA

IFAA_STATUS_FINGERPRINT2终端支持IFAA的指纹服务（Touch ID）

IFAA_STATUS_FACE_ID3终端支持IFAA的人脸服务（Face ID）

IFAA_STATUS_NOT_ENROLLED4终端没有录入指纹/人脸 (此时可以引导用户去录入指纹/人脸再做操作)

IFAA_STATUS_NOT_REGISTERED5IFAA 尚未注册 (比如认证/注销/指位更新等操作都需要注册后才可以进行)

IFAA_STATUS_REGISTERED6IFAA 已经注册 (这只是一个状态，并不是错误)

IFAA_STATUS_PASSCODE_NOT_SET7尚未设置屏幕锁密码 （IFAA 需要设置屏幕锁后才能进行，否则不安全，此处可引导用户去设置屏幕锁）

IFAA_CLIENT_ERROR8本地执行异常

IFAA_SERVER_ERROR9服务器错误

IFAA_NETWORK_ERROR10网络错误

IFAA_WRONG_AUTHDATAINDEX11指位不匹配，需要更新指位

IFAA_POLICY_REJECTED12被风险策略拒绝时

IFAA_USER_REJECTED13用户被禁用时

IFAA_APPID_NOT_FOUND14应用白名单中未设置应用标识

IFAA_DEVICE_MODEL_NOT_FOUND15设备型号不存在

IFAA_SIGNATURE_FAIL16未获取到签名数据

IFAA_STATUS_DELETED17本地指纹已经注册，但是注册的指纹模组数据已经被删除(Android独有)

IFAA_CLIENT_ERROR_MULTI_FP_NOT_SUPPORT18此手机不支持多指位(Android独有)

IFAA_STATUS_RESULT_CANCELED19用户取消

IFAA_STATUS_RESULT_TIMEOUT20超时(Android独有)

IFAA_STATUS_RESULT_AUTH_FAIL21验证失败，系统指纹不匹配

IFAA_STATUS_RESULT_SYSTEM_BLOCK22连续多次校验失败，指纹校验被暂时锁定(暂时Android独有)

IFAA_STATUS_RESULT_FALLBACK23点击了 FALLBACK 按钮

IFAA_STATUS_RESULT_TEE_ERROR24TEE 错误(Android独有)

IFAA_STATUS_RESULT_SYSTEM_ERROR25手机系统问题，请升级系统版本(Android独有)

IFAA_PERMISSION_DENIED26-Android:当前设备未获取相机权限

-IOS:当前应用未获取Face ID权限

IFAA_AUTHENTICATOR_DISABLE27认证器被禁用

IFAA_AUTHENTICATOR_NOT_FOUND28未找到相应的认证器

IFAA_DEVICE_KEY_NOT_FOUND29设备密钥被禁用

IFAA_PROTECT_PAYLOAD_NOT_MATCH30受保护的业务数据不匹配

接入IFAA及了解详情，阿里云地址：

https://market.aliyun.com/products/57000002/cmapi00037211.html?