1/*
2 * Copyright (c) 2023 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 4.1
26 */
27
28/**
29 * @file IUserAuthInterface.idl
30 *
31 * @brief Declares the user_auth driver APIs, which can be used to register executors,
32 * manage credentials, and complete password and biometric authentication.
33 *
34 * @since 4.1
35 */
36
37package ohos.hdi.user_auth.v1_2;
38
39import ohos.hdi.user_auth.v1_2.UserAuthTypes;
40
41/**
42 * @brief Declares the APIs of the user_auth driver.
43 *
44 * @since 4.1
45 * @version 1.2
46 */
47interface IUserAuthInterface {
48    /**
49     * @brief Initializes the cache information of the user_auth driver.
50     *
51     * @return Returns <b>0</b> if the operation is successful.
52     * @return Returns a non-zero value if the operation fails.
53     */
54    Init();
55    /**
56     * @brief Adds an authentication executor to obtain the authentication capability.
57     *
58     * @param info Indicates executor registration information. See {@link ExecutorRegisterInfo}.
59     * @param index Indicates the executor index under the authentication framework.
60     * @param publicKey Indicates the public key of the authentication framework.
61     * @param templateIds Indicates template IDs enrolled by the executors.
62     *
63     * @return Returns <b>0</b> if the operation is successful.
64     * @return Returns a non-zero value if the operation fails.
65     */
66    AddExecutor([in] struct ExecutorRegisterInfo info, [out] unsigned long index,
67        [out] unsigned char[] publicKey, [out] unsigned long[] templateIds);
68    /**
69     * @brief Deletes an executor.
70     *
71     * @param index Indicates the executor index under the authentication framework.
72     *
73     * @return Returns <b>0</b> if the operation is successful.
74     * @return Returns a non-zero value if the operation fails.
75     */
76    DeleteExecutor([in] unsigned long index);
77    /**
78     * @brief Opens a session for authentication credential management.
79     *
80     * @param userId Indicates the user ID.
81     * @param challenge Indicates the random number, which is used to generate an authentication token.
82     *
83     * @return Returns <b>0</b> if the operation is successful.
84     * @return Returns a non-zero value if the operation fails.
85     */
86    OpenSession([in] int userId, [out] unsigned char[] challenge);
87    /**
88     * @brief Closes the authentication credential management session.
89     *
90     * @param userId Indicates the user ID.
91     *
92     * @return Returns <b>0</b> if the operation is successful.
93     * @return Returns a non-zero value if the operation fails.
94     */
95    CloseSession([in] int userId);
96    /**
97     * @brief Begins the enrollment of authentication credentials.
98     * If the authentication type is PIN, this method updates the existing PIN credential.
99     *
100     * @param userId Indicates the user ID.
101     * @param authToken Indicates the authentication token of the user password.
102     * @param param Indicates input parameters. See {@link EnrollParam}.
103     * @param info Indicates scheduling information. See {@link ScheduleInfo}.
104     *
105     * @return Returns <b>0</b> if the operation is successful.
106     * @return Returns a non-zero value if the operation fails.
107     *
108     * @deprecated
109     */
110    BeginEnrollment([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param,
111        [out] struct ScheduleInfo info);
112    /**
113     * @brief Updates the enrollment result and completes the enrollment.
114     *
115     * @param userId Indicates the user ID.
116     * @param scheduleResult Indicates the enrollment result issued by the executor.
117     * @param info Indicates the enrollment result. See {@link EnrollResultInfo}.
118     *
119     * @return Returns <b>0</b> if the operation is successful.
120     * @return Returns a non-zero value if the operation fails.
121     */
122    UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] struct EnrollResultInfo info);
123    /**
124     * @brief Cancels an enrollment.
125     *
126     * @param userId Indicates the user ID.
127     *
128     * @return Returns <b>0</b> if the operation is successful.
129     * @return Returns a non-zero value if the operation fails.
130     */
131    CancelEnrollment([in] int userId);
132    /**
133     * @brief Deletes credential information.
134     *
135     * @param userId Indicates the user ID.
136     * @param credentialId Indicates the credential index.
137     * @param authToken Indicates the authentication token of the user password.
138     * @param info Indicates the credential information to delete. See {@link CredentialInfo}.
139     *
140     * @return Returns <b>0</b> if the operation is successful.
141     * @return Returns a non-zero value if the operation fails.
142     */
143    DeleteCredential([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken,
144        [out] struct CredentialInfo info);
145    /**
146     * @brief Obtains credential information.
147     *
148     * @param userId Indicates the user ID.
149     * @param authType Indicates the authentication type. See {@link AuthType}.
150     * @param infos Indicates credential information. See {@link CredentialInfo}.
151     *
152     * @return Returns <b>0</b> if the operation is successful.
153     * @return Returns a non-zero value if the operation fails.
154     */
155    GetCredential([in] int userId, [in] enum AuthType authType, [out] struct CredentialInfo[] infos);
156    /**
157     * @brief Obtains user information.
158     *
159     * @param userId Indicates the user ID.
160     * @param secureUid Indicates the secure user ID.
161     * @param pinSubType Indicates the sub type of PIN authentication. See {@link PinSubType}.
162     * @param infos Indicates enrolled information. See {@link EnrolledInfo}.
163     *
164     * @return Returns <b>0</b> if the operation is successful.
165     * @return Returns a non-zero value if the operation fails.
166     */
167    GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] enum PinSubType pinSubType,
168        [out] struct EnrolledInfo[] infos);
169    /**
170     * @brief Deletes a pin and a user from the IAM subsystem.
171     *
172     * @param userId Indicates the user ID.
173     * @param authToken Indicates the authentication token of the user password.
174     * @param deletedInfos Indicates the credential information to delete. See {@link CredentialInfo}.
175     *
176     * @return Returns <b>0</b> if the operation is successful.
177     * @return Returns a non-zero value if the operation fails.
178     */
179    DeleteUser([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos);
180    /**
181     * @brief Forcibly deletes a user.
182     *
183     * @param userId Indicates the user ID.
184     * @param deletedInfos Indicates the credential information to delete. See {@link CredentialInfo}.
185     *
186     * @return Returns <b>0</b> if the operation is successful.
187     * @return Returns a non-zero value if the operation fails.
188     */
189    EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos);
190    /**
191     * @brief Begins authentication, and generates the authentication solution.
192     *
193     * @param contextId Indicates the context index.
194     * @param param Indicates input parameters. See {@link AuthSolution}.
195     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfo}.
196     *
197     * @return Returns <b>0</b> if the operation is successful.
198     * @return Returns a non-zero value if the operation fails.
199     *
200     * @deprecated
201     */
202    BeginAuthentication([in] unsigned long contextId, [in] struct AuthSolution param,
203        [out] struct ScheduleInfo[] scheduleInfos);
204    /**
205     * @brief Updates the authentication result, and evaluates the result of the authentication solution.
206     *
207     * @param contextId Indicates the context index.
208     * @param scheduleResult Indicates the authentication result issued by the executor.
209     * @param info Indicates authentication result information. See {@link AuthResultInfo}.
210     *
211     * @return Returns <b>0</b> if the operation is successful.
212     * @return Returns a non-zero value if the operation fails.
213     */
214    UpdateAuthenticationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
215        [out] struct AuthResultInfo info);
216    /**
217     * @brief Cancels authentication.
218     *
219     * @param contextId Indicates the context index.
220     *
221     * @return Returns <b>0</b> if the operation is successful.
222     * @return Returns a non-zero value if the operation fails.
223     */
224    CancelAuthentication([in] unsigned long contextId);
225    /**
226     * @brief Begins identification, and generates the identification solution.
227     *
228     * @param contextId Indicates the context index.
229     * @param authType Indicates the identification type. See @{AuthType}.
230     * @param challenge Indicates the identification challenge.
231     * @param executorSensorHint Indicates the executor sensor hint.
232     * The value <b>0</b> indicates that no value is specified.
233     * @param scheduleInfo Indicates scheduling information. See {@link ScheduleInfo}.
234     *
235     * @return Returns <b>0</b> if the operation is successful.
236     * @return Returns a non-zero value if the operation fails.
237     *
238     * @deprecated
239     */
240    BeginIdentification([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge,
241        [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo);
242    /**
243     * @brief Updates the identification result, and evaluates the result of the identification solution.
244     *
245     * @param contextId Indicates the context index.
246     * @param scheduleResult Indicates the identification result issued by the executor.
247     * @param info Indicates identification result information. See {@link IdentifyResultInfo}.
248     *
249     * @return Returns <b>0</b> if the operation is successful.
250     * @return Returns a non-zero value if the operation fails.
251     */
252    UpdateIdentificationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult,
253        [out] struct IdentifyResultInfo info);
254    /**
255     * @brief Cancels identification.
256     *
257     * @param contextId Indicates the context index.
258     *
259     * @return Returns <b>0</b> if the operation is successful.
260     * @return Returns a non-zero value if the operation fails.
261     */
262    CancelIdentification([in] unsigned long contextId);
263    /**
264     * @brief Obtains the trust level of the current authentication type.
265     *
266     * @param userId Indicates the user ID.
267     * @param authType Indicates the authentication type. See {@link AuthType}.
268     * @param authTrustLevel Indicates the authentication trust level.
269     *
270     * @return Returns <b>0</b> if the operation is successful.
271     * @return Returns a non-zero value if the operation fails.
272     */
273    GetAuthTrustLevel([in] int userId, [in] enum AuthType authType, [out] unsigned int authTrustLevel);
274    /**
275     * @brief Obtains the valid authentication methods under the current authentication trust level.
276     *
277     * @param userId Indicates the user ID.
278     * @param authTypes Indicates the authentication types to be filtered. See {@link AuthType}.
279     * @param authTrustLevel Indicates the authentication trust level.
280     * @param validTypes Indicates the valid authentication types. See {@link AuthType}.
281     *
282     * @return Returns <b>0</b> if the operation is successful.
283     * @return Returns a non-zero value if the operation fails.
284     */
285    GetValidSolution([in] int userId, [in] enum AuthType[] authTypes, [in] unsigned int authTrustLevel,
286        [out] enum AuthType[] validTypes);
287    /**
288     * @brief Begins the enrollment of authentication credentials.
289     * If the authentication type is PIN, this method updates the existing PIN credential.
290     *
291     * @param userId Indicates the user ID.
292     * @param authToken Indicates the authentication token of the user password.
293     * @param param Indicates input parameters. See {@link EnrollParam}.
294     * @param info Indicates scheduling information. See {@link ScheduleInfoV1_1}.
295     *
296     * @return Returns <b>0</b> if the operation is successful.
297     * @return Returns a non-zero value if the operation fails.
298     *
299     * @deprecated
300     */
301    BeginEnrollmentV1_1([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param,
302        [out] struct ScheduleInfoV1_1 info);
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 AuthSolution}.
308     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfoV1_1}.
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     * @deprecated
314     */
315    BeginAuthenticationV1_1([in] unsigned long contextId, [in] struct AuthSolution param,
316        [out] struct ScheduleInfoV1_1[] scheduleInfos);
317    /**
318     * @brief Begins identification, and generates the identification solution.
319     *
320     * @param contextId Indicates the context index.
321     * @param authType Indicates the identification type. See @{AuthType}.
322     * @param challenge Indicates the identification challenge.
323     * @param executorSensorHint Indicates the executor sensor hint.
324     * The value <b>0</b> indicates that no value is specified.
325     * @param scheduleInfo Indicates scheduling information. See {@link ScheduleInfoV1_1}.
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    BeginIdentificationV1_1([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge,
331        [in] unsigned int executorSensorHint, [out] struct ScheduleInfoV1_1 scheduleInfo);
332    /**
333     * @brief Get all enrolled user information.
334     *
335     * @param userInfos List of all userInfo. See @{UserInfo}.
336     *
337     * @return Returns <b>0</b> if the operation is successful.
338     * @return Returns a non-zero value if the operation fails.
339     */
340    GetAllUserInfo([out] UserInfo[] userInfos);
341    /**
342     * @brief Get all credential of enrolled users.
343     *
344     * @param userInfos List of all users. See @{ExtUserInfo}.
345     *
346     * @return Returns <b>0</b> if the operation is successful.
347     * @return Returns a non-zero value if the operation fails.
348     */
349    GetAllExtUserInfo([out] ExtUserInfo[] userInfos);
350    /**
351     * @brief Begins authentication, and generates the authentication solution.
352     *
353     * @param contextId Indicates the context index.
354     * @param param Indicates input parameters. See {@link AuthSolutionV1_2}.
355     * @param scheduleInfos Indicates scheduling information. See {@link ScheduleInfoV1_1}.
356     *
357     * @return Returns <b>0</b> if the operation is successful.
358     * @return Returns a non-zero value if the operation fails.
359     */
360    BeginAuthenticationV1_2([in] unsigned long contextId, [in] struct AuthSolutionV1_2 param,
361        [out] struct ScheduleInfoV1_1[] scheduleInfos);
362    /**
363     * @brief Begins the enrollment of authentication credentials.
364     * If the authentication type is PIN, this method updates the existing PIN credential.
365     *
366     * @param userId Indicates the user ID.
367     * @param authToken Indicates the authentication token of the user password.
368     * @param param Indicates input parameters. See {@link EnrollParamV1_2}.
369     * @param info Indicates scheduling information. See {@link ScheduleInfoV1_1}.
370     *
371     * @return Returns <b>0</b> if the operation is successful.
372     * @return Returns a non-zero value if the operation fails.
373     */
374    BeginEnrollmentV1_2([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParamV1_2 param,
375        [out] struct ScheduleInfoV1_1 info);
376}
377/** @} */
378