1# IUserAuthInterface 2 3 4## **概述** 5 6声明用户认证驱动的API接口。 7 8**Since：** 9 103.2 11 12**Version：** 13 141.0 15 16**所属模块:** 17 18[HdfUserAuth](_hdf_user_auth.md) 19 20 21## **汇总** 22 23 24### Public 成员函数 25 26 | 名称 | 描述 | 27| -------- | -------- | 28| [Init](#init)() | 初始化用户认证驱动缓存信息，用于用户认证框架进程启动时初始化信息。 | 29| [AddExecutor](#addexecutor)([in] struct ExecutorRegisterInfo info, [out] unsigned long index, [out] unsigned char[] publicKey, [out] unsigned long[] templateIds) | 添加认证执行器来获取认证能力，用于各认证基础服务如口令认证服务等将认证能力对接到用户认证框架。 | 30| [DeleteExecutor](#deleteexecutor)([in] unsigned long index) | 删除执行器，用于清理失效的执行器信息。 | 31| [OpenSession](#opensession)([in] int userId, [out] unsigned char[] challenge) | 开启一个认证凭据管理会话，用于在请求管理用户认证凭据前获取有效挑战值。 | 32| [CloseSession](#closesession)([in] int userId) | 关闭认证凭据管理会话，完成用户认证凭据管理请求处理后，调用该接口使原挑战值失效。 | 33| [BeginEnrollment](#beginenrollment)([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, [out] struct ScheduleInfo info) | 开始注册用户认证凭据。当注册凭据类型为口令且该用户已经注册了口令凭据时，将会更新口令凭据。 | 34| [UpdateEnrollmentResult](#updateenrollmentresult)([in] int userId, [in] unsigned char[] scheduleResult, [out] unsigned long credentialId, [out] struct CredentialInfo oldInfo) | 更新用户凭据注册结果，完成凭据注册。 | 35| [CancelEnrollment](#cancelenrollment)([in] int userId) | 取消注册请求。 | 36| [DeleteCredential](#deletecredential)([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken, [out] struct CredentialInfo info) | 删除用户凭据信息。 | 37| [GetCredential](#getcredential)([in] int userId, [in] enum AuthType authType, [out] struct CredentialInfo[] infos) | 查询用户凭据信息。 | 38| [GetUserInfo](#getuserinfo) ([in] int userId, [out] unsigned long secureUid, [out] enum PinSubType pinSubType, [out] struct EnrolledInfo[] infos) | 查询用户认证相关信息。 | 39| [DeleteUser](#deleteuser)([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos) | 删除用户口令认证凭据，在用户IAM系统内删除该用户，该请求由用户触发。 | 40| [EnforceDeleteUser](#enforcedeleteuser)([in] int userId, [out] struct CredentialInfo[] deletedInfos) | 强制删除用户，该请求由系统内管理用户的模块触发。 | 41| [BeginAuthentication](#beginauthentication)([in] unsigned long contextId, [in] struct AuthSolution param, [out] struct ScheduleInfo[] scheduleInfos) | 开始认证用户，并生成认证方案。 | 42| [UpdateAuthenticationResult](#updateauthenticationresult)([in] unsigned long contextId, [in] unsigned char[] scheduleResult, [out] struct AuthResultInfo info) | 更新认证结果，评估认证方案的认证结果。 | 43| [CancelAuthentication](#cancelauthentication)([in] unsigned long contextId) | 取消用户认证请求。 | 44| [BeginIdentification](#beginidentification)([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge, [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo) | 开始用户身份识别，并生成识别方案。 | 45| [UpdateIdentificationResult](#updateidentificationresult)([in] unsigned long contextId, [in] unsigned char[] scheduleResult, [out] struct IdentifyResultInfo info) | 更新用户身份识别结果，生成身份识别方案的结果。 | 46| [CancelIdentification](#cancelidentification)([in] unsigned long contextId) | 取消用户身份识别请求。 | 47| [GetAuthTrustLevel](#getauthtrustlevel)([in] GetUserInfoint userId, [in] enum AuthType authType, [out] unsigned int authTrustLevel) | 获取当前认证类型的认证结果可信等级。 | 48| [GetValidSolution](#getvalidsolution)([in] int userId, [in] enum AuthType[] authTypes, [in] unsigned int authTrustLevel, [out] enum AuthType[] validTypes) | 获取指定认证结果可信等级下有效的认证方式。 | 49 50 51## **成员函数说明** 52 53 54### AddExecutor() 55 56 57``` 58IUserAuthInterface::AddExecutor ([in] struct ExecutorRegisterInfo info, [out] unsigned long index, [out] unsigned char[] publicKey, [out] unsigned long[] templateIds ) 59``` 60 61**描述：** 62 63添加认证执行器来获取认证能力，用于各认证基础服务如口令认证服务等将认证能力对接到用户认证框架。 64 65**参数：** 66 67 | 名称 | 描述 | 68| -------- | -------- | 69| info | 执行器注册信息[ExecutorRegisterInfo](_executor_register_info.md)。 | 70| index | 用户认证框架的执行器索引。 | 71| publicKey | 用户认证框架公钥。 | 72| templateIds | 该执行器已注册的模版ID列表。 | 73 74**返回：** 75 760 表示操作成功。 77 78非0 表示操作失败。 79 80 81### BeginAuthentication() 82 83 84``` 85IUserAuthInterface::BeginAuthentication ([in] unsigned long contextId, [in] struct AuthSolution param, [out] struct ScheduleInfo[] scheduleInfos ) 86``` 87 88**描述：** 89 90开始认证用户，并生成认证方案。 91 92**参数：** 93 94 | 名称 | 描述 | 95| -------- | -------- | 96| contextId | 上下文索引。 | 97| param | 认证方案[AuthSolution](_auth_solution.md)。 | 98| scheduleInfos | 调度信息[ScheduleInfo](_schedule_info.md)。 | 99 100**返回：** 101 1020 表示操作成功。 103 104非0 表示操作失败。 105 106 107### BeginEnrollment() 108 109 110``` 111IUserAuthInterface::BeginEnrollment ([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, [out] struct ScheduleInfo info ) 112``` 113 114**描述：** 115 116开始注册用户认证凭据。当注册凭据类型为口令且该用户已经注册了口令凭据时，将会更新口令凭据。 117 118**参数：** 119 120 | 名称 | 描述 | 121| -------- | -------- | 122| userId | 用户ID。 | 123| authToken | 用户口令认证令牌。 | 124| param | 注册凭据参数[EnrollParam](_enroll_param.md)。 | 125| info | 调度信息[ScheduleInfo](_schedule_info.md)。 | 126 127**返回：** 128 1290 表示操作成功。 130 131非0 表示操作失败。 132 133 134### BeginIdentification() 135 136 137``` 138IUserAuthInterface::BeginIdentification([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge, [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo) 139``` 140 141**描述：** 142 143开始用户身份识别，并生成识别方案。 144 145**参数：** 146 147 | 名称 | 描述 | 148| -------- | -------- | 149| contextId | 上下文索引。 | 150| authType | 用户身份识别类型[AuthType](_hdf_user_auth.md#authtype)。 | 151| challenge | 随机挑战值，用于生成用户身份识别令牌，防止重放。 | 152| executorSensorHint | 执行器传感器提示，用于找到对应认证方式的传感器。 | 153| scheduleInfo | 调度信息[ScheduleInfo](_schedule_info.md)。 | 154 155**返回：** 156 1570 表示操作成功。 158 159非0 表示操作失败。 160 161 162### CancelAuthentication() 163 164 165``` 166IUserAuthInterface::CancelAuthentication ([in] unsigned long contextId) 167``` 168 169**描述：** 170 171取消用户认证请求。 172 173**参数：** 174 175 | 名称 | 描述 | 176| -------- | -------- | 177| contextId | 上下文索引。 | 178 179**返回：** 180 1810 表示操作成功。 182 183非0 表示操作失败。 184 185 186### CancelEnrollment() 187 188 189``` 190IUserAuthInterface::CancelEnrollment ([in] int userId) 191``` 192 193**描述：** 194 195取消注册请求。 196 197**参数：** 198 199 | 名称 | 描述 | 200| -------- | -------- | 201| userId | 用户ID。 | 202 203**返回：** 204 2050 表示操作成功。 206 207非0 表示操作失败。 208 209 210### CancelIdentification() 211 212 213``` 214IUserAuthInterface::CancelIdentification ([in] unsigned long contextId) 215``` 216 217**描述：** 218 219取消用户身份识别请求。 220 221**参数：** 222 223 | 名称 | 描述 | 224| -------- | -------- | 225| contextId | 上下文索引。 | 226 227**返回：** 228 2290 表示操作成功。 230 231非0 表示操作失败。 232 233 234### CloseSession() 235 236 237``` 238IUserAuthInterface::CloseSession ([in] int userId) 239``` 240 241**描述：** 242 243关闭认证凭据管理会话，完成用户认证凭据管理请求处理后，调用该接口使原挑战值失效。 244 245**参数：** 246 247 | 名称 | 描述 | 248| -------- | -------- | 249| userId | 用户ID。 | 250 251**返回：** 252 2530 表示操作成功。 254 255非0 表示操作失败。 256 257 258### DeleteCredential() 259 260 261``` 262IUserAuthInterface::DeleteCredential ([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken, [out] struct CredentialInfo info ) 263``` 264 265**描述：** 266 267删除用户凭据信息。 268 269**参数：** 270 271 | 名称 | 描述 | 272| -------- | -------- | 273| userId | 用户ID。 | 274| credentialId | 凭据ID。 | 275| authToken | 用户口令认证令牌。 | 276| info | 删除的凭据信息[CredentialInfo](_credential_info.md)。 | 277 278**返回：** 279 2800 表示操作成功。 281 282非0 表示操作失败。 283 284 285### DeleteExecutor() 286 287 288``` 289IUserAuthInterface::DeleteExecutor ([in] unsigned long index) 290``` 291 292**描述：** 293 294删除执行器，用于清理失效的执行器信息。 295 296**参数：** 297 298 | 名称 | 描述 | 299| -------- | -------- | 300| index | 用户认证框架的执行器索引。 | 301 302**返回：** 303 3040 表示操作成功。 305 306非0 表示操作失败。 307 308 309### DeleteUser() 310 311 312``` 313IUserAuthInterface::DeleteUser ([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos ) 314``` 315 316**描述：** 317 318删除用户口令认证凭据，在用户IAM系统内删除该用户，该请求由用户触发。 319 320**参数：** 321 322 | 名称 | 描述 | 323| -------- | -------- | 324| userId | 用户ID。 | 325| authToken | 用户口令认证令牌。 | 326| deletedInfos | 删除的凭据信息[CredentialInfo](_credential_info.md)。 | 327 328**返回：** 329 3300 表示操作成功。 331 332非0 表示操作失败。 333 334 335### EnforceDeleteUser() 336 337 338``` 339IUserAuthInterface::EnforceDeleteUser ([in] int userId, [out] struct CredentialInfo[] deletedInfos ) 340``` 341 342**描述：** 343 344强制删除用户，该请求由系统内管理用户的模块触发。 345 346**参数：** 347 348 | 名称 | 描述 | 349| -------- | -------- | 350| userId | 用户ID。 | 351| deletedInfos | 删除的凭据信息[CredentialInfo](_credential_info.md)。 | 352 353**返回：** 354 3550 表示操作成功。 356 357非0 表示操作失败。 358 359 360### GetAuthTrustLevel() 361 362 363``` 364IUserAuthInterface::GetAuthTrustLevel ([in] int userId, [in] enum AuthType authType, [out] unsigned int authTrustLevel ) 365``` 366 367**描述：** 368 369获取当前认证类型的认证结果可信等级。 370 371**参数：** 372 373 | 名称 | 描述 | 374| -------- | -------- | 375| userId | 用户ID。 | 376| authType | 认证类型[AuthType](_hdf_user_auth.md#authtype)。 | 377| authTrustLevel | 认证结果可信等级。 | 378 379**返回：** 380 3810 表示操作成功。 382 383非0 表示操作失败。 384 385 386### GetCredential() 387 388 389``` 390IUserAuthInterface::GetCredential ([in] int userId, [in] enum AuthType authType, [out] struct CredentialInfo[] infos ) 391``` 392 393**描述：** 394 395查询用户凭据信息。 396 397**参数：** 398 399 | 名称 | 描述 | 400| -------- | -------- | 401| userId | 用户ID。 | 402| authType | 凭据类型[AuthType](_hdf_user_auth.md#authtype)。 | 403| infos | 凭据信息[CredentialInfo](_credential_info.md)。 | 404 405**返回：** 406 4070 表示操作成功。 408 409非0 表示操作失败。 410 411 412### GetUserInfo() 413 414 415``` 416IUserAuthInterface::GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] enum PinSubType pinSubType, [out] struct EnrolledInfo[] infos) 417``` 418 419**描述：** 420 421查询用户认证相关信息。 422 423**参数：** 424 425 | 名称 | 描述 | 426| -------- | -------- | 427| userId | 用户ID。 | 428| secureUid | 安全用户ID。 | 429| pinSubType | 口令认证子类型[PinSubType](_hdf_user_auth.md#pinsubtype)。 | 430| infos | 注册信息[EnrolledInfo](_enrolled_info.md)。 | 431 432**返回：** 433 4340 表示操作成功。 435 436非0 表示操作失败。 437 438 439### GetValidSolution() 440 441 442``` 443IUserAuthInterface::GetValidSolution ([in] int userId, [in] enum AuthType[] authTypes, [in] unsigned int authTrustLevel, [out] enum AuthType[] validTypes ) 444``` 445 446**描述：** 447 448获取指定认证结果可信等级下有效的认证方式。 449 450**参数：** 451 452 | 名称 | 描述 | 453| -------- | -------- | 454| userId | 用户ID。 | 455| authTypes | 用于筛选的认证方式列表[AuthType](_hdf_user_auth.md#authtype)。 | 456| authTrustLevel | 认证结果可信等级。 | 457| validTypes | 有效的认证方式列表[AuthType](_hdf_user_auth.md#authtype)。 | 458 459**返回：** 460 4610 表示操作成功。 462 463非0 表示操作失败。 464 465 466### Init() 467 468 469``` 470IUserAuthInterface::Init () 471``` 472 473**描述：** 474 475初始化用户认证驱动缓存信息，用于用户认证框架进程启动时初始化信息。 476 477**返回：** 478 4790 表示操作成功。 480 481非0 表示操作失败。 482 483 484### OpenSession() 485 486 487``` 488IUserAuthInterface::OpenSession ([in] int userId, [out] unsigned char[] challenge ) 489``` 490 491**描述：** 492 493开启一个认证凭据管理会话，用于在请求管理用户认证凭据前获取有效挑战值。 494 495**参数：** 496 497 | 名称 | 描述 | 498| -------- | -------- | 499| userId | 用户ID。 | 500| challenge | 随机挑战值，用于生成用户身份认证令牌。 | 501 502**返回：** 503 5040 表示操作成功。 505 506非0 表示操作失败。 507 508 509### UpdateAuthenticationResult() 510 511 512``` 513IUserAuthInterface::UpdateAuthenticationResult ([in] unsigned long contextId, [in] unsigned char[] scheduleResult, [out] struct AuthResultInfo info ) 514``` 515 516**描述：** 517 518更新认证结果，评估认证方案的认证结果。 519 520**参数：** 521 522 | 名称 | 描述 | 523| -------- | -------- | 524| contextId | 上下文索引。 | 525| scheduleResult | 执行器签发的认证结果。 | 526| info | 认证结果信息[AuthResultInfo](_auth_result_info.md)。 | 527 528**返回：** 529 5300 表示操作成功。 531 532非0 表示操作失败。 533 534 535### UpdateEnrollmentResult() 536 537 538``` 539IUserAuthInterface::UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] struct EnrollResultInfo info) 540``` 541 542**描述：** 543 544更新用户凭据注册结果，完成凭据注册。 545 546**参数：** 547 548 | 名称 | 描述 | 549| -------- | -------- | 550| userId | 用户ID。 | 551| scheduleResult | 执行器签发的注册结果。 | 552| oldInfo | 录入结果信息[EnrollResultInfo](_enroll_resultinfo.md)。 | 553 554**返回：** 555 5560 表示操作成功。 557 558非0 表示操作失败。 559 560 561### UpdateIdentificationResult() 562 563 564``` 565IUserAuthInterface::UpdateIdentificationResult ([in] unsigned long contextId, [in] unsigned char[] scheduleResult, [out] struct IdentifyResultInfo info ) 566``` 567 568**描述：** 569 570更新用户身份识别结果，生成身份识别方案的结果。 571 572**参数：** 573 574 | 名称 | 描述 | 575| -------- | -------- | 576| contextId | 上下文索引。 | 577| scheduleResult | 执行器签发的用户身份识别结果。 | 578| info | 用户身份识别结果[IdentifyResultInfo](_identify_result_info.md)。 | 579 580**返回：** 581 5820 表示操作成功。 583 584非0 表示操作失败。 585