1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup HdfUserAuth
18 * @{
19 *
20 * @brief Provides APIs for the user_auth driver.
21 *
22 * The user_auth driver provides a unified interface for the user_auth service to access the user_auth driver.
23 * After obtaining the user_auth driver proxy, the service can call related APIs to register executors,
24 * manage credentials, and complete password and biometric authentication.
25 * @since 3.2
26 * @version 1.0
27 */
28
29/**
30 * @file IUserAuthInterface.idl
31 *
32 * @brief Declares the user_auth driver APIs, which can be used to register executors,
33 * manage credentials, and complete password and biometric authentication.
34 *
35 * @since 3.2
36 * @version 1.0
37 */
38
39package ohos.hdi.user_auth.v3_0;
40
41import ohos.hdi.user_auth.v3_0.UserAuthTypes;
42import ohos.hdi.user_auth.v3_0.IMessageCallback;
43
44/**
45 * @brief Declares the APIs of the user_auth driver.
46 *
47 * @since 3.2
48 * @version 1.0
49 */
50interface IUserAuthInterface {
51    /**
52     * @brief Initializes the cache information of the user_auth driver.
53     *
54     * @param deviceUdid Indicates the device udid.
55     *
56     * @return Returns <b>0</b> if the operation is successful.
57     * @return Returns a non-zero value if the operation fails.
58     *
59     * @since 3.2
60     * @version 2.0
61     */
62    Init([in] String deviceUdid);
63    /**
64     * @brief Adds an authentication executor to obtain the authentication capability.
65     *
66     * @param info Indicates executor registration information. See {@link ExecutorRegisterInfo}.
67     * @param index Indicates the executor index under the authentication framework.
68     * @param publicKey Indicates the public key of the authentication framework.
69     * @param templateIds Indicates template IDs enrolled by the executors.
70     *
71     * @return Returns <b>0</b> if the operation is successful.
72     * @return Returns a non-zero value if the operation fails.
73     *
74     * @since 3.2
75     * @version 1.0
76     */
77    AddExecutor([in] struct ExecutorRegisterInfo info, [out] unsigned long index,
78        [out] unsigned char[] publicKey, [out] unsigned long[] templateIds);
79    /**
80     * @brief Deletes an executor.
81     *
82     * @param index Indicates the executor index under the authentication framework.
83     *
84     * @return Returns <b>0</b> if the operation is successful.
85     * @return Returns a non-zero value if the operation fails.
86     *
87     * @since 3.2
88     * @version 1.0
89     */
90    DeleteExecutor([in] unsigned long index);
91    /**
92     * @brief Opens a session for authentication credential management.
93     *
94     * @param userId Indicates the user ID.
95     * @param challenge Indicates the random number, which is used to generate an authentication token.
96     *
97     * @return Returns <b>0</b> if the operation is successful.
98     * @return Returns a non-zero value if the operation fails.
99     *
100     * @since 3.2
101     * @version 1.0
102     */
103    OpenSession([in] int userId, [out] unsigned char[] challenge);
104    /**
105     * @brief Closes the authentication credential management session.
106     *
107     * @param userId Indicates the user ID.
108     *
109     * @return Returns <b>0</b> if the operation is successful.
110     * @return Returns a non-zero value if the operation fails.
111     *
112     * @since 3.2
113     * @version 1.0
114     */
115    CloseSession([in] int userId);
116    /**
117     * @brief Updates the enrollment result and completes the enrollment.
118     *
119     * @param userId Indicates the user ID.
120     * @param scheduleResult Indicates the enrollment result issued by the executor.
121     * @param info Indicates the enrollment result. See {@link EnrollResultInfo}.
122     *
123     * @return Returns <b>0</b> if the operation is successful.
124     * @return Returns a non-zero value if the operation fails.
125     *
126     * @since 3.2
127     * @version 1.0
128     */
129    UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] struct EnrollResultInfo info);
130    /**
131     * @brief Cancels an enrollment.
132     *
133     * @param userId Indicates the user ID.
134     *
135     * @return Returns <b>0</b> if the operation is successful.
136     * @return Returns a non-zero value if the operation fails.
137     *
138     * @since 3.2
139     * @version 1.0
140     */
141    CancelEnrollment([in] int userId);
142    /**
143     * @brief Deletes credential information.
144     *
145     * @param userId Indicates the user ID.
146     * @param credentialId Indicates the credential index.
147     * @param authToken Indicates the authentication token of the user password.
148     * @param info Indicates the credential information to delete. See {@link CredentialInfo}.
149     *
150     * @return Returns <b>0</b> if the operation is successful.
151     * @return Returns a non-zero value if the operation fails.
152     *
153     * @since 3.2
154     * @version 1.0
155     */
156    DeleteCredential([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken,
157        [out] struct CredentialInfo info);
158    /**
159     * @brief Obtains credential information.
160     *
161     * @param userId Indicates the user ID.
162     * @param authType Indicates the authentication type. See {@link AuthType}.
163     * @param infos Indicates credential information. See {@link CredentialInfo}.
164     *
165     * @return Returns <b>0</b> if the operation is successful.
166     * @return Returns a non-zero value if the operation fails.
167     *
168     * @since 3.2
169     * @version 2.0
170     */
171    GetCredential([in] int userId, [in] int authType, [out] struct CredentialInfo[] infos);
172    /**
173     * @brief Obtains user information.
174     *
175     * @param userId Indicates the user ID.
176     * @param secureUid Indicates the secure user ID.
177     * @param pinSubType Indicates the sub type of PIN authentication. See {@link PinSubType}.
178     * @param infos Indicates enrolled information. See {@link EnrolledInfo}.
179     *
180     * @return Returns <b>0</b> if the operation is successful.
181     * @return Returns a non-zero value if the operation fails.
182     *
183     * @since 3.2
184     * @version 2.0
185     */
186    GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] int pinSubType,
187        [out] struct EnrolledInfo[] infos);
188    /**
189     * @brief Deletes a pin and a user from the IAM subsystem.
190     *
191     * @param userId Indicates the user ID.
192     * @param authToken Indicates the authentication token of the user password.
193     * @param deletedInfos Indicates the credential information to delete. See {@link CredentialInfo}.
194     * @param rootSecret protection key for the user file key.
195     *
196     * @return Returns <b>0</b> if the operation is successful.
197     * @return Returns a non-zero value if the operation fails.
198     *
199     * @since 3.2
200     * @version 2.0
201     */
202    DeleteUser([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos,
203        [out] unsigned char[] rootSecret);
204    /**
205     * @brief Forcibly deletes a user.
206     *
207     * @param userId Indicates the user ID.
208     * @param deletedInfos Indicates the credential information to delete. See {@link CredentialInfo}.
209     *
210     * @return Returns <b>0</b> if the operation is successful.
211     * @return Returns a non-zero value if the operation fails.
212     *
213     * @since 3.2
214     * @version 1.0
215     */
216    EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos);
217    /**
218     * @brief Updates the authentication result, and evaluates the result of the authentication solution.
219     *
220     * @param contextId Indicates the context index.
221     * @param scheduleResult Indicates the authentication result issued by the executor.
222     * @param info Indicates authentication result information. See {@link AuthResultInfo}.
223     * @param enrolledState EnrolledID information.
224     *
225     * @return Returns <b>0</b> if the operation is successful.
226     * @return Returns a non-zero value if the operation fails.
227     *
228     * @since 3.2
229     * @version 2.0
230     */
231    UpdateAuthenticationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
232        [out] struct AuthResultInfo info, [out] EnrolledState enrolledState);
233    /**
234     * @brief Cancels authentication.
235     *
236     * @param contextId Indicates the context index.
237     *
238     * @return Returns <b>0</b> if the operation is successful.
239     * @return Returns a non-zero value if the operation fails.
240     *
241     * @since 3.2
242     * @version 1.0
243     */
244    CancelAuthentication([in] unsigned long contextId);
245    /**
246     * @brief Updates the identification result, and evaluates the result of the identification solution.
247     *
248     * @param contextId Indicates the context index.
249     * @param scheduleResult Indicates the identification result issued by the executor.
250     * @param info Indicates identification result information. See {@link IdentifyResultInfo}.
251     *
252     * @return Returns <b>0</b> if the operation is successful.
253     * @return Returns a non-zero value if the operation fails.
254     *
255     * @since 3.2
256     * @version 1.0
257     */
258    UpdateIdentificationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
259        [out] struct IdentifyResultInfo info);
260    /**
261     * @brief Cancels identification.
262     *
263     * @param contextId Indicates the context index.
264     *
265     * @return Returns <b>0</b> if the operation is successful.
266     * @return Returns a non-zero value if the operation fails.
267     *
268     * @since 3.2
269     * @version 1.0
270     */
271    CancelIdentification([in] unsigned long contextId);
272    /**
273     * @brief Check whether the authentication capability is avaliable.
274     *
275     * @param userId Indicates the user ID.
276     * @param authType Indicates the authentication type. See {@link AuthType}.
277     * @param authTrustLevel Indicates the authentication trust level.
278     * @param checkResult Indicates check result.
279     *
280     * @return Returns <b>0</b> if the operation is successful.
281     * @return Returns a non-zero value if the operation fails.
282     *
283     * @since 5.0
284     * @version 1.0
285     */
286    GetAvailableStatus([in] int userId, [in] int authType, [in] unsigned int authTrustLevel, [out] int checkResult);
287    /**
288     * @brief Obtains the valid authentication methods under the current authentication trust level.
289     *
290     * @param userId Indicates the user ID.
291     * @param authTypes Indicates the authentication types to be filtered. See {@link AuthType}.
292     * @param authTrustLevel Indicates the authentication trust level.
293     * @param validTypes Indicates the valid authentication types. See {@link AuthType}.
294     *
295     * @return Returns <b>0</b> if the operation is successful.
296     * @return Returns a non-zero value if the operation fails.
297     *
298     * @since 3.2
299     * @version 2.0
300     */
301    GetValidSolution([in] int userId, [in] int[] authTypes, [in] unsigned int authTrustLevel,
302        [out] int[] validTypes);
303    /**
304     * @brief Begins authentication, and generates the authentication solution.
305     *
306     * @param contextId Indicates the context index.
307     * @param param Indicates input parameters. See {@link AuthParam}.
308     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfo}.
309     *
310     * @return Returns <b>0</b> if the operation is successful.
311     * @return Returns a non-zero value if the operation fails.
312     *
313     * @since 3.2
314     * @version 2.0
315     */
316    BeginAuthentication([in] unsigned long contextId, [in] struct AuthParam param,
317        [out] struct ScheduleInfo[] scheduleInfos);
318    /**
319     * @brief Begins the enrollment of authentication credentials.
320     * If the authentication type is PIN, this method updates the existing PIN credential.
321     *
322     * @param userId Indicates the user ID.
323     * @param authToken Indicates the authentication token of the user password.
324     * @param param Indicates input parameters. See {@link EnrollParam}.
325     * @param info Indicates scheduling information. See {@link ScheduleInfo}.
326     *
327     * @return Returns <b>0</b> if the operation is successful.
328     * @return Returns a non-zero value if the operation fails.
329     *
330     * @since 3.2
331     * @version 2.0
332     */
333    BeginEnrollment([in] unsigned char[] authToken, [in] struct EnrollParam param,
334        [out] struct ScheduleInfo info);
335    /**
336     * @brief Begins identification, and generates the identification solution.
337     *
338     * @param contextId Indicates the context index.
339     * @param authType Indicates the identification type. See @{AuthType}.
340     * @param challenge Indicates the identification challenge.
341     * @param executorSensorHint Indicates the executor sensor hint.
342     * The value <b>0</b> indicates that no value is specified.
343     * @param scheduleInfo Indicates scheduling information. See {@link ScheduleInfo}.
344     *
345     * @return Returns <b>0</b> if the operation is successful.
346     * @return Returns a non-zero value if the operation fails.
347     *
348     * @since 3.2
349     * @version 2.0
350     */
351    BeginIdentification([in] unsigned long contextId, [in] int authType, [in] unsigned char[] challenge,
352        [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo);
353    /**
354     * @brief Get all enrolled user information.
355     *
356     * @param userInfos List of all userInfo. See @{UserInfo}.
357     *
358     * @return Returns <b>0</b> if the operation is successful.
359     * @return Returns a non-zero value if the operation fails.
360     *
361     * @since 4.0
362     * @version 1.0
363     */
364    GetAllUserInfo([out] UserInfo[] userInfos);
365    /**
366     * @brief Get all credential of enrolled users.
367     *
368     * @param userInfos List of all users. See @{ExtUserInfo}.
369     *
370     * @return Returns <b>0</b> if the operation is successful.
371     * @return Returns a non-zero value if the operation fails.
372     *
373     * @since 4.0
374     * @version 1.0
375     */
376    GetAllExtUserInfo([out] ExtUserInfo[] userInfos);
377
378    /**
379     * @brief Querying EnrolledId information.
380     *
381     * @param userId Indicates the user ID.
382     * @param authType Indicates the identification type. See @{AuthType}.
383     * @param enrolledState Enrolled state.
384     *
385     * @return Returns <b>0</b> if the operation is successful.
386     * @return Returns a non-zero value if the operation fails.
387     *
388     * @since 5.0
389     * @version 1.0
390     */
391    GetEnrolledState([in] int userId, [in] int authType, [out] struct EnrolledState enrolledState);
392
393    /**
394     * @brief Check if unlock result can be reused and return token.
395     *
396     * @param info Request information of reused unLock result. See {@link ReuseUnlockParam}.
397     * @param reuseInfo Reuse unlock info. See {@link ReuseUnlockInfo}.
398     *
399     * @return Returns <b>0</b> if the operation is successful.
400     * @return Returns a non-zero value if the operation fails.
401     *
402     * @since 5.0
403     * @version 1.0
404     */
405    CheckReuseUnlockResult([in] struct ReuseUnlockParam reuseParam, [out] ReuseUnlockInfo reuseInfo);
406    /**
407     * @brief Send message.
408     *
409     * @param scheduleId Indicates the schedule ID of the message.
410     * @param srcRole is the role of source. See {@link ExecutorRole}.
411     * @param msg is the message content.
412     *
413     * @return Returns <b>0</b> if the operation is successful.
414     * @return Returns a non-zero value if the operation fails.
415     *
416     * @since 5.0
417     * @version 1.0
418     */
419    SendMessage([in] unsigned long scheduleId, [in] int srcRole, [in] unsigned char[] msg);
420    /**
421     * @brief Register message callback.
422     *
423     * @param messageCallback Indicates the message callback. See {@link IMessageCallback}.
424     *
425     * @return Returns <b>0</b> if the operation is successful.
426     * @return Returns a non-zero value if the operation fails.
427     *
428     * @since 5.0
429     * @version 1.0
430     */
431    RegisterMessageCallback([in] IMessageCallback messageCallback);
432    /**
433     * @brief Prepare remote auth.
434     *
435     * @param remoteUdid Indicates the remote device udid.
436     *
437     * @return Returns <b>0</b> if the operation is successful.
438     * @return Returns a non-zero value if the operation fails.
439     *
440     * @since 5.0
441     * @version 1.0
442     */
443    PrepareRemoteAuth([in] String remoteUdid);
444    /**
445     * @brief Get local schedule from message.
446     *
447     * @param remoteUdid Indicates the remote device udid.
448     * @param message is message received.
449     * @param scheduleInfo is schedule info. See {@link ScheduleInfo}.
450     *
451     * @return Returns <b>0</b> if the operation is successful.
452     * @return Returns a non-zero value if the operation fails.
453     *
454     * @since 5.0
455     * @version 1.0
456     */
457    GetLocalScheduleFromMessage([in] String remoteUdid, [in] unsigned char[] message, [out] ScheduleInfo scheduleInfo);
458    /**
459     * @brief Get signed executor info.
460     *
461     * @param authTypes Indicates the auth types. See @{AuthType}.
462     * @param executorRole Indicates the role of executor. See {@link ExecutorRole}.
463     * @param remoteUdid Indicates the remote device udid.
464     * @param signedExecutorInfo Indicates the signed executor info.
465     *
466     * @return Returns <b>0</b> if the operation is successful.
467     * @return Returns a non-zero value if the operation fails.
468     *
469     * @since 5.0
470     * @version 1.0
471     */
472    GetSignedExecutorInfo([in] int[] authTypes, [in] int executorRole, [in] String remoteUdid,
473        [out] unsigned char[] signedExecutorInfo);
474    /**
475     * @brief Get auth result from message.
476     *
477     * @param remoteUdid Indicates the remote device udid.
478     * @param message is message received.
479     * @param authResultInfo Indicates authentication result information. See {@link AuthResultInfo}.
480     *
481     * @return Returns <b>0</b> if the operation is successful.
482     * @return Returns a non-zero value if the operation fails.
483     *
484     * @since 5.0
485     * @version 1.0
486     */
487     GetAuthResultFromMessage([in] String remoteUdid, [in] unsigned char[] message, [out] struct AuthResultInfo authResultInfo);
488    /**
489     * @brief Set global config param.
490     *
491     * @param param The value of global config parameter. See @{GlobalConfigParam}.
492     * @return Return set result(0:success; other:failed).
493     *
494     * @since 5.0
495     * @version 1.0
496     */
497    SetGlobalConfigParam([in] GlobalConfigParam param);
498    /**
499     * @brief Obtains credential information.
500     *
501     * @param credentialId Indicates the credential ID.
502     * @param infos Indicates credential information. See {@link CredentialInfo}.
503     *
504     * @return Returns <b>0</b> if the operation is successful.
505     * @return Returns a non-zero value if the operation fails.
506     *
507     * @since 5.0
508     * @version 1.0
509     */
510    GetCredentialById([in] unsigned long credentialId, [out] struct CredentialInfo info);
511}
512/** @} */
513