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?