# 身份验证
[TOC]
身份验证（**IdentityVerifier**），又称为多生物特征融合验证（Multi-biometrics Fusion Verification，简称MFV），支持人脸和声纹的 1:1 单一验证，1:1 融合验证，1:N 鉴别。需下载使用对应的身份验证SDK。
MFV目前提供的功能组合：
| |1：1单一验证|1：1融合验证|1：N检索
| --- | --- | --- | --- |
|人脸|人脸验证|人脸声纹融合验证|人脸鉴别|
|声纹|声纹验证|人脸声纹融合验证|声纹鉴别|
MFV相关概念说明：
| 概念| 英文标识| 说明|
|:---:|:---:|---|
| 用户id| auth_id| 用户身份的唯一标识。|
|组id| group_id| 组的唯一标识。<br>组被用来限定1：N鉴别的用户范围。|
|特征注册| enroll| 上传用户特征数据，在云端生成特征模型。<br>其中，人脸图像数据的大小应控制在200K以下。|
|特征验证| verify| 上传用户特征数据，云端将其与已注册的特征模型<br>进行比对，返回结果（相似度、是否通过验证等）。|
|融合验证| mixed verify| 上传用户多项特征数据，云端将其与已注册的多项<br>特征模型进行比对，返回结果（综合相似度、是否通过验证等）。|
|特征鉴别| identify| 上传用户特征数据，并指定鉴别组id，云端将上传<br>数据与组内用户对应的已注册的特征模型进行比对，<br>返回结果（相似度排行、用户名称）。|
|业务场景| scenes| 会话的场景。<br>包括：人脸（ifr），声纹（ivp），<br>人脸声纹融合（ifr \| ivp），组管理（ipt）。|
|业务类型| sst| 会话的业务类型。<br>在不同的会话场景（scenes）下有不同的业务类型。|
|子业务类型| ssub| 子业务类型。<br>包括：人脸（ifr），声纹（ivp），组管理（ipt）。|
业务场景与业务类型组合：
| 场景类型 | 人脸（ifr） | 声纹（ivp） | 人脸声纹融合<br>（ifr \| ivp） | 组管理（ipt） |
|:---:|:---:|:---:|:---:|:---:|
|注册|√|√|-|-|
|验证|√|√|√|-|
|鉴别|√|√|-|-|
子业务操作组合：
| |人脸（ifr）|声纹（ivp）|组管理（ipt）|
|:---:|:---:|:---:|:---:|
|创建|-|-|√|
|加入|-|-|√|
|查询|-|√|√|
|删除|√|√|√|
|密码下载|-|√|-|
在 1:1 的首次验证前，需要先指定用户 ID 进行注册。
组鉴别前，需要先创建组，然后把用户 ID 加入到组中；在组鉴别时，指定组 ID，上传数据（音频或图片）后，将返回组内最匹配的几个用户 ID 及相似度。目前仅提供10个鉴别组进行开发调试。
注册或验证声纹或人脸时，须指定以下参数：
* 业务类型（MFV_SST）
* 业务场景（MFV_SCENES）
* 用户 ID（AUTH_ID）
* 验证模式（MFV_VCM）
## 注册
在声纹注册时，需要先获取密码：
~~~
// 设置业务场景：声纹（ivp）
mIdVerifier.setParameter(SpeechConstant.MFV_SCENES, "ivp" );
// 设置声纹密码组数
mIdVerifier.setParameter( "rgn", rgn );
// 执行密码下载操作，密码类型：数字密码（pwdt=3）
mIdVerifier.execute("ivp", "download", "pwdt=3", listener );
~~~
密码结果通过 listener 中的回调获取。
进行注册：
~~~
// 设置业务场景：人脸（ifr）或声纹（ivp）
mIdVerifier.setParameter( SpeechConstant.MFV_SCENES, scence );
// 设置业务类型：注册（enroll）
mIdVerifier.setParameter( SpeechConstant.MFV_SST, "enroll" );
// 设置用户id
mIdVerifier.setParameter( SpeechConstant.AUTH_ID, authID );
// 设置监听器，开始会话
mIdVerifier.startWorking( listener );
// 在注册声纹时，需要多次写入音频数据
while( !isDataFinished ){
if( scence.equals("ivp") ){
// 在注册声纹时，需要在 params 中，指定声纹注册的参数，包括注册次数（rgn），密码类型（pwdt），以及密码（ptxt）
params = "pwdt=3,ptxt="+pwdTxt+",rgn="+rgn;
}
mIdVerifier.writeData( scence, params, data, offset, length );
}
// 写入完成后，需要调用stopWrite停止写入，在停止的时候同样需要指定子业务类型。只有
// stopWrite之后，才会触发 listener 中的回调接口，返回结果或者错误信息。
mIdVerifier.stopWrite( scence );
~~~
注册人脸时，只要上传一张图片即可；而声纹注册时，则可能需要多次写入音频数据。注册结果状态通过 listener 的回调获取。
## 验证
验证时，可通过 MFV_VCM 指定验证模式为单一（人脸或声纹），还是混合（人脸+声纹）。在混合模式下，需要分别写入图片和音频数据。
~~~
// 设置业务场景
mIdVerifier.setParameter( SpeechConstant.MFV_SCENES, scene );
// 设置业务类型
mIdVerifier.setParameter( SpeechConstant.MFV_SST, "verify" );
// 设置验证模式
mIdVerifier.setParameter( SpeechConstant.MFV_VCM, vcm );
// 设置用户id
mIdVerifier.setParameter( SpeechConstant.AUTH_ID, authID );
// 设置监听器，开始会话
mIdVerifier.startWorking( listener );
while( !isDataFinished ){
// 写入数据
mIdVerifier.writeData( scence, params, data, offset, length );
}
mIdVerifier.stopWrite( scence );
~~~
## 1:N检索
鉴别与验证的过程相似，不过鉴别需要设置组 ID，以指定要鉴别的组。
清参考身份识别中1:N检索部分。
## 模型和组管理
声纹模型目前支持的操作有查询（query）、删除（delete）、密码下载（download）3种。人脸模型目前支持删除（delete）操作。组管理包括创建，查询，加入和删除。
~~~
// 设置业务场景，ifd, ivp, ipt
mIdVerifier.setParameter( SpeechConstant.MFV_SCENES, scene );
// 设置用户id
mIdVerifier.setParameter( SpeechConstant.AUTH_ID, authID );
// params 根据不同的操作而不同
if( isCreateGroup ){
//创建组
params="scope=group,group_name=" + groupName;
cmd = "add";
}else if( isDeleteGroup ){
//删除组
params = "scope=group,group_id=" + groupID );
cmd = "delete";
}else if( isAddGroupMember ){
//加入组员
params = "scope=person,group_id=" + groupID+",auth_id=" + authID;
cmd = "add";
}else if( isDeleteGroupMember ){
//删除组员
params = "scope=person,group_id=" + groupID+",auth_id=" + authID;
cmd = "delete";
}else if( isQueryGroupMember ){
//查询组员
params = "scope=group,group_id=" + groupID );
cmd = "query";
}else{
// 人脸或声纹的模型管理 query, delete, download
cmd = ...;
}
// cmd 为 操作，模型管理包括 query, delete, download，组管理包括 add，query，delete
mIdVerifier.execute( scene, cmd , params, listener );
~~~
操作结果通过 listener 回调获取。
## 参数设置
多生物特征融合验证平台的参数分为两种，分别为MFV主参数和子业务参数。
MFV主参数通过 IdentityVerifier.setParameter(String key, String value) 方法进行设置，参数下表所示。
|名称|说明|取值范围|默认值|
| --- |--- |--- |--- |--- |
|auth_id|用户id，用户身份的唯一标识|自拟，长度6-18位，仅包括英文、数字|无|
|group_id|通过组管理功能创建的鉴别组的唯一标识|长度20以内的字符串，由组管理功能创建得到，或由他人告知|无，在鉴别场景下必须指定|
|scenes|会话场景|ifr（人脸），ivp（声纹），ifr\|ivp（人脸+声纹），组管理（ipt）|无，必须指定|
|sst|会话的业务类型|enroll（注册），verify（验证），identify（鉴别）|无，必须指定|
|vcm|验证模式，仅在验证场景下使用|sin（单一特征），mix（融合），agi（灵活）|无，在验证场景下必须指定|
|afc|灵活验证保留结果时间|0-43200s|无，只在vcm设置成agi时生效|
|prot_type|联网协议|ssl|非ssl协议|
|sslcert|证书内容|证书内容|赛门铁克安全证书（仅在prot_type=ssl时生效）|
注意：
1. scenes 和 vcm 必须组合使用：例如指定 vcm 为 sin 则 scenes 只可以选择 ifr 或者 ivp 单独业务，vcm 选择 mix 则 scenes 只可以选择 ifr|ivp。另：agi(灵活)模式可以设置 sences=ifr|ivp，在当次会话只发送一种业务数据，服务端保留验证结果，如在设置的时间间隔内再传入另外的业务数据即可做到混合验证。
2. prot_type、sslcert 参数也可在 SpeechUtility. createUtility 时传入，之后每次会话都会生效。
3. 支持服务端回调通知业务。当用户进行了注册、验证操作后，讯飞服务端发送结果消息给开发者的业务服务器，如需此服务请联系：msp_support@iflytek.com
子业务参数以String格式的键-值对在调用 IdentityVerifier.writeData(String ssub, String params, byte[] data, int offset, int length) 写入，子业务特征数据调用 IdentityVerifier.execute(String ssub, String cmd, String params, IdentityListener listener) 执行模型操作时传入，对应于params参数。详见 Demo。
|子业务|名称|说明|取值|默认值|
| --- | --- | --- | --- | --- |
|ivp（声纹）|rgn|注册次数。|2-9。|5(建议使用默认值，效果最好) |
|ivp（声纹）|ptxt|密码文本，指定声纹密码注册时使用的声纹密码内容。|由服务端下发，比如数字密码所需的数字串。|无，必须指定|
|ivp（声纹）|pwdt|密码类型，指定声纹密码注册时使用的声纹密码类型。|3（数字密码）注：其他类型暂不支持。|无，必须指定|
|ifr（人脸）|暂无||||
|ipt（组管理）|auth_id|用户id||设备id，必须指定|
|ipt（组管理）|scope|操作对象|group（组）person（成员）|无，必须指定|
|person（成员）|group_name|创建的组名称||无，必须指定|
|person（成员）|group_id|加入的组id||无，必须指定|
结果格式说明详见附录。
## 安全性问题
从前面模型和组管理的章节可以看到，在身份验证时，除在注意在声纹密码和人脸识别章节提到的安全性问题外（参考对应的章节内容），还需要**注意对组 ID 的保密**。在组管理中，通过指定组 ID，即可查询到所有组员的 AUTH_ID，当他人同时也获取到 libmsc.so （通过 APK 解压等）以及 APPID 时，通过 group_id 查到所有组员 auth_id，便可直接修改对应 auth_id 的模型。应用可以对展示给用户的组 ID 进行映射，例如可以让展示界面显示的，只是一个组的昵称等。
从组 ID 需要保密可以知道，为了安全性，组管理并未提供通过 APPID 查询其所有组 ID 的功能——因为这样获取到 libmsc.so 和 APPID 的人就会获取到所有组 ID，从而获取到所有组员的 AUTH_ID，继而修改其模型。所以，应用在创建组后，需要保存组 ID，以在组管理和鉴别时使用。
此外，模型更新，APPID 和 用户 ID 要注意的问题，可参考声纹密码章节中的安全性问题说明，此处不再重复。
