iOS SDK接入

1. 概述

官网下载iOS客户端SDK进行解压,解压后包含:

  • Demo工程

  • IDaaSDoraemonSDK.framework(安全认证静态库)

  • 具体认证服务SDK,包括:手机号认证,生物识别(IFAA)

2. 前期准备

2.1 准备工作

请确保已在安全认证控制台创建应用,并开启生物识别(IFAA)服务。

1

2.2 运行demo工程

解压后包含DoraemonDemo工程, 需要将bundleID 、应用密钥修改为创建应用后获取的值。

2.3 搭建开发环境

运行环境:iOS 9.0+平台上。

支持语言:Object-C、Swift

2.3.1 添加主库

Targets->General->Linked Frameworks and Libraries 中添加主库

IDaaSDoraemonSDK.framework

如果应用授权了认证方式,添加额外的认证方式主库:

首先 Targets->General->Linked Frameworks and Libraries 中添加主库

IFAAAuthenticator.framework
etasSdkframework
APOpenSSL.framework
APSecCrypto.framework

然后 Targets->General->Linked Frameworks and Libraries 中添加系统库

Security.framework
AVFoundation.framework
LocalAuthentication.framework
Foundation.framework
libc++.tbd

最后 Targets->Build Phases->Copy Bundle Resources 中添加资源文件

etasSdk.bundle

说明

如果项⽬之前集成的有其他openssl,在发⽣冲突时可以删除APOpenSSL.framework保留其他的openssl;

如果项⽬之前有集成⽀付宝AlipaySDK.framework,会与APSecCrypto.framework产⽣冲突,需删除APSecCrypto.framework。

2.3.2 Target->BuildSettings设置
Xcode 中还需要进行设置,Targets->BuildSettings 中 , Other Linker Flags增加-ObjC,⼀定要添加此选项,注意是⼤写C,不是⼩写c,否则⼯程运⾏会crash!

1

3. SDK 调用说明

SDK 提供 EtasManager 实现 SimpleIFAA 的认证操作, 以下是主要的函数定义:

字段 类型 描述

fallbackTitle

NSString

验证TouchID或FaceID时在错误⼀次的后显示出的可选项按钮标题,若需要取消该按钮的显示,传⼊⼀个空字符串。

12

reasonTitle

NSString

验证理由说明⽂字,会显示在对话框中部。

12

ifaaMsg

NSString

SimpleIFAA认证初始化请求或SimpleIFAA认证请求到IFAA 服务端返回的响应报⽂

  • 要完成整个认证流程,⾸先需要调⽤sAuthInit方法,当etasResult.code时为IFAA_SUCCES将字符串

    etasResult.msg作为消息体发送到服务端。

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

  • 最后调用sAuthFinish方法来完成SimpleIFAA认证操作,其中ifaaMsgSimpleIFAA认证第二次请求服务端返回的报文,当执行方法返回的etasResult.codeIFAA_SUCCESSimpleIFAA认证成功,至此整个SimpleIFAA认证流程结束。

4. SDK 方法说明

4.1 主类EtasManager 接⼝简介
4.1.1 SimpleIFAA认证初始化

/**
* SimpleIFAA认证初始化
* @param reasonTitle 指纹弹出框的reasonTitle
* @param fallbackTitle 指纹弹出框的 fallbackTitle
* @return EtasResult 
**/
- (EtasResult *)sAuthInit:(NSString*)reasonTitle fallbackTitle: (NSString*)fallbackTitle;

4.1.2 SimpleIFAA认证

/**
* SimpleIFAA认证
* @param ifaaMsg SimpleIFAA认证初始化请求到IFAA服务端返回的响应报⽂
* @param etasCallback 结果回调函数 `typedef void (^EtasCallback)(EtasResult*
etasResult);`
**/
- (void)sAuth:(NSString *)ifaaMsg etasCallback:(EtasCallback)etasCallback;

4.1.3 SimpleIFAA认证完成方法
/**
* SimpleIFAA认证完成⽅法
* @param ifaaMsg SimpleIFAA认证请求到IFAA服务端返回的响应报⽂
* @return EtasResult 22 
**/
- (EtasResult *)sAuthFinish:(NSString *)ifaaMsg;

4.2 SDK返回码
4.2.1 Simple认证初始化

响应码

响应码描述

IFAA_STATUS_SUPPORT_OTHERS

SimpleIFAA功能只支持TouchID与FaceID的认证方式

IFAA_STATUS_PASSCODE_NOT_SET

锁屏密码未设置

IFAA_STATUS_NOT_ENROLLED

设备没有录入任何指纹

IFAA_STATUS_NOT_REGISTERED

本地尚未注册

IFAA_PERMISSION_DENIED

当前应用未授权Face_ID权限

4.2.2 Simple认证

响应码

响应码描述

IFAA_SERVER_ERROR

返回的报⽂数据异常

IFAA_POLICY_REJECTED

IFAA 已被策略管理禁⽤

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

点击了fallback

IFAA_STATUS_RESULT_AUTH_FAIL

连续三次本地认证失败

IFAA_AUTHENTICATOR_DISABLE

认证器被禁⽤

IFAA_AUTHENTICATOR_NOT_FOUND

未找到相应的认证器

IFAA_DEVICE_KEY_NOT_FOUND

设备密钥被禁⽤

IFAA_PROTECT_PAYLOAD_NOT_MATCH

受保护的业务数据不匹配

IFAA_PERMISSION_DENIED

当前应⽤未获取Face ID权限

4.2.3 Simple认证

响应码

响应码描述

IFAA_SERVER_ERROR

返回的报⽂数据异常

IFAA_POLICY_REJECTED

IFAA 已被策略管理禁⽤

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

受保护的业务数据不匹配

4.3 IFAAErrorCodeEnum的枚举值

枚举值

业务意义

IFAA_SUCCESS

0

成功

IFAA_STATUS_SUPPORT_OTHERS

1

⽀持除指纹/⼈脸以外的认证类型,如pin/⼿势等

IFAA_STATUS_NOT_ENROLLED

4

终端没有录⼊指纹/⼈脸 (此时可以引导⽤户去录⼊指纹/⼈脸再做操作)

IFAA_STATUS_PASSCODE_NOT_SET

7

尚未设置屏幕锁密码 (IFAA 需要设置屏幕锁后才能进⾏,否则不安全,此处可引导⽤户去设置屏幕锁)

IFAA_CLIENT_ERROR

8

本地执⾏异常

IFAA_SERVER_ERROR

9

服务器错误

IFAA_POLICY_REJECTED

12

被⻛险策略拒绝时

IFAA_USER_REJECTED

13

⽤户被禁⽤时

IFAA_APPID_NOT_FOUND

14

应⽤⽩名单中未设置应⽤标识

IFAA_DEVICE_MODEL_NOT_FOUND

15

设备型号不存在

IFAA_SIGNATURE_FAIL

16

未获取到签名数据

IFAA_STATUS_DELETED

17

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

IFAA_CLIENT_ERROR_MULTI_FP_NOT_SUPP ORT

18

此⼿机不⽀持多指位(Android独有)

IFAA_STATUS_RESULT_CANCELED

19

⽤户取消

IFAA_STATUS_RESULT_TIMEOUT

20

超时(Android独有)

IFAA_STATUS_RESULT_AUTH_FAIL

21

验证失败,系统指纹不匹配

IFAA_STATUS_RESULT_SYSTEM_BLOCK

22

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

IFAA_STATUS_RESULT_FALLBACK

23

点击了 FALLBACK 按钮

IFAA_STATUS_RESULT_TEE_ERROR

24

TEE 错误(Android独有)

IFAA_STATUS_RESULT_SYSTEM_ERROR

25

⼿机系统问题,请升级系统版本(Android独有)

IFAA PERMISSION DENIED

26

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

IFAA_AUTHENTICATOR_DISABLE

27

-IOS:当前应⽤未获取FaceID权限

IFAA_AUTHENTICATOR_NOT_FOUND

28

认证器被禁⽤

IFAA_DEVICE_KEY_NOT_FOUND

29

未找到相应的认证器

IFAA_PROTECT_PAYLOAD_NOT_MATCH

30

设备密钥被禁⽤

5. 认证示例

//认证初始化    
self.etasManager = [[EtasManager alloc] init];
    EtasResult *etasResult = [self.etasManager sAuthInit:@"simpleIFAA 认证" fallbackTitle:@"密码认证"];
    if (etasResult.code == IFAA_SUCCESS) {

        HKLog(@"etasResult.msg=========== %@",etasResult.msg);
        //生成SimpleIFAA初始化应用签名信息
        [[IDaaSDoraemonManager sharedInstance] getMobileExtendParamsJson:etasResult.msg phoneNumber:@"" serviceCode:@"IFAA" complete:^(NSDictionary * _Nonnull resultDic) {

            HKLog(@"初始化获取生成应用签名信息返回:%@", resultDic);
            HKLog(@"接下来可以拿着应用签名信息去服务端进行校验,SDK提供服务到此结束");

        }];
    }else{
        [self logError:etasResult.msg];
    }
//开始认证
NSString *authMsgString = @"后端SimpleAuthInit认证初始化接口返回";
    HKLog(@"authMsgString=========== %@",authMsgString);
    [self.etasManager sAuth:authMsgString etasCallback:^(EtasResult *etasResult) {
        if (etasResult.code == IFAA_SUCCESS) {
            //生成应用签名信息
            HKLog(@"etasResult.msg=========== %@",etasResult.msg);
            [[IDaaSDoraemonManager sharedInstance] getMobileExtendParamsJson:etasResult.msg phoneNumber:@"" serviceCode:@"IFAA" complete:^(NSDictionary * _Nonnull resultDic) {

                HKLog(@"认证获取生成应用签名信息返回:%@", resultDic);
                HKLog(@"接下来可以拿着应用签名信息去服务端进行校验,SDK提供服务到此结束");

            }];

        }else{
            [self logError:etasResult.msg];
        }
    }];
//认证完成
NSString *authFinishString = @"后端SimpleAuth认证接口返回";
    EtasResult *etasResult = [self.etasManager sAuthFinish:authFinishString];
    if(etasResult.code == IFAA_SUCCESS){
        [self logMsg:[NSString stringWithFormat:@"SimpleIFAA认证成功,生物认证标识为:%@", etasResult.msg]];
    }else{
        [self logError:[NSString stringWithFormat:@"SimpleIFAA认证失败:%@", etasResult.msg]];
    }