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
24 *
25 * @since 4.0
26 * @version 1.0
27 */
28
29 /**
30 * @file UserAuthTypes.idl
31 *
32 * @brief Defines the enumeration values and data structures of the user_auth driver.
33 *
34 * @since 4.0
35 * @version 1.0
36 */
37
38package ohos.hdi.user_auth.v3_0;
39
40 /**
41 * @brief Enumerates the credential types for authentication.
42 *
43 * @since 3.2
44 * @version 3.0
45 */
46enum AuthType : int {
47    /**< All types. */
48    ALL = 0,
49    /**< PIN authentication. */
50    PIN = 1,
51    /**< Facial authentication. */
52    FACE = 2,
53    /**< Fingerprint authentication. */
54    FINGERPRINT = 4,
55    /**< Recovery key. */
56    RECOVERY_KEY = 8,
57    /** Private pin authentication. */
58    PRIVATE_PIN = 16,
59};
60
61/**
62 * @brief Enumerates executor roles.
63 *
64 * @since 3.2
65 * @version 1.0
66 */
67enum ExecutorRole : int {
68    /**< The executor acts as a collector. */
69    COLLECTOR = 1,
70    /**< The executor acts as a verifier. */
71    VERIFIER = 2,
72    /**< The executor acts as a collector and verifier. */
73    ALL_IN_ONE = 3,
74};
75
76/**
77 * @brief Enumerates executor security levels.
78 *
79 * @since 4.0
80 * @version 1.0
81 */
82enum ExecutorSecureLevel : int {
83    /**< ESL0. */
84    ESL0 = 0,
85    /**< ESL1. */
86    ESL1 = 1,
87    /**< ESL2. */
88    ESL2 = 2,
89    /**< ESL3. */
90    ESL3 = 3,
91};
92
93/**
94 * @brief Defines pin auth's subtype.
95 *
96 * @since 3.2
97 * @version 3.0
98 */
99enum PinSubType : int {
100    /**< Six digit pin. */
101    PIN_SIX = 10000,
102    /**< Digit pin. */
103    PIN_NUMBER = 10001,
104    /**< Mixing pin. */
105    PIN_MIX = 10002,
106    /**< Four digit pin. */
107    PIN_FOUR = 10003,
108    /**< Pattern. */
109    PATTERN = 10004,
110    /** Password protection question */
111    PIN_QUESTION = 10005,
112};
113
114/**
115 * Schedule mode.
116 *
117 * @since 3.2
118 * @version 1.0
119 */
120enum ScheduleMode : int {
121    /**< The schedule mode is enrollment. */
122    ENROLL = 0,
123    /**< The schedule mode is authentication. */
124    AUTH = 1,
125    /**< The schedule mode is identification. */
126    IDENTIFY = 2,
127};
128
129/**
130 * Auth intent.
131 *
132 * @since 5.0
133 * @version 2.0
134 */
135enum AuthIntent : int {
136    /**< The auth intent is default. */
137    DEFUALT = 0,
138    /**< The auth intent is unlock. */
139    UNLOCK = 1,
140    /**< The auth intent silent auth. */
141    SILENT_AUTH = 2,
142    /**< The auth intention is question auth. */
143    QUESTION_AUTH = 3,
144};
145
146/**
147 * @brief User type.
148 *
149 * @since 5.0
150 * @version 1.0
151 */
152enum UserType : int {
153    /**< main user. */
154    MAIN = 0,
155    /**< sub user. */
156    SUB = 1,
157    /**< private user. */
158    PRIVATE = 2,
159};
160
161/**
162 * @brief Reuse mode.
163 *
164 * @since 5.0
165 * @version 1.0
166 */
167enum ReuseMode : int {
168    /**< sub user. */
169    AUTH_TYPE_RELEVANT = 1,
170    /**< private user. */
171    AUTH_TYPE_IRRELEVANT = 2,
172};
173
174/**
175 * @brief Defines executor registration information.
176 *
177 * @since 4.0
178 * @version 2.0
179 */
180struct ExecutorRegisterInfo {
181    /**< Authentication type. See @{AuthType}. */
182    int authType;
183    /**< Executor role. See @{ExecutorRole}. */
184    int executorRole;
185    /**< Executor sensor hint under the same authentication type, 0 is not allowed. */
186    unsigned int executorSensorHint;
187    /**< Executor matcher. */
188    unsigned int executorMatcher;
189    /**< Executor secure level. See @{ExecutorSecureLevel}. */
190    int esl;
191    /**< Indicates the max acl of template.*/
192    unsigned int maxTemplateAcl;
193    /**< Public key of the executor. */
194    unsigned char[] publicKey;
195    /**< Device udid. */
196    String deviceUdid;
197    /**< signed remote executor info. */
198    unsigned char[] signedRemoteExecutorInfo;
199};
200
201/**
202 * @brief Defines executor information.
203 *
204 * @since 4.0
205 * @version 1.0
206 */
207struct ExecutorInfo {
208    /**< Executor index under the authentication framework. */
209    unsigned long executorIndex;
210    /**< Executor registration information. See @{ExecutorRegisterInfo}. */
211    struct ExecutorRegisterInfo info;
212};
213
214/**
215 * @brief Defines executor messages.
216 *
217 * @since 4.0
218 * @version 1.0
219 */
220struct ExecutorSendMsg {
221    /**< Executor index under the authentication framework. */
222    unsigned long executorIndex;
223    /**< Indicates command ID. */
224    int commandId;
225    /**< Executor message to send. */
226    unsigned char[] msg;
227};
228
229/**
230 * @brief Defines authentication result information.
231 *
232 * @since 4.0
233 * @version 2.0
234 */
235struct AuthResultInfo {
236    /**< Authentication result. */
237    int result;
238    /**< Lockout duration, in millisecond. */
239    int lockoutDuration;
240    /**< Remaining authentication attempts before a lockout. */
241    int remainAttempts;
242    /**< Executor messages. See @{ExecutorSendMsg}. */
243    struct ExecutorSendMsg[] msgs;
244    /**< Authentication token. */
245    unsigned char[] token;
246    /**< Protection key for the user file key. */
247    unsigned char[] rootSecret;
248    /**< User ID. */
249    int userId;
250    /**< Credential ID. */
251    unsigned long credentialId;
252    /**< Pin expired info. */
253    long pinExpiredInfo;
254    /**< Remote auth result message. */
255    unsigned char[] remoteAuthResultMsg;
256    /**< Re-enroll flag. */
257    boolean reEnrollFlag;
258};
259
260/**
261 * @brief Defines identification result information.
262 *
263 * @since 4.0
264 * @version 1.0
265 */
266struct IdentifyResultInfo {
267    /**< iIdentification result. */
268    int result;
269    /**< User ID. */
270    int userId;
271    /**< Identification token. */
272    unsigned char[] token;
273};
274
275/**
276 * @brief Defines credential information.
277 *
278 * @since 4.0
279 * @version 2.0
280 */
281struct CredentialInfo {
282    /**< Credential ID. */
283    unsigned long credentialId;
284    /**< Executor index under the authentication framework. */
285    unsigned long executorIndex;
286    /**< Template ID. */
287    unsigned long templateId;
288    /**< Authentication type. See @{AuthType}. */
289    int authType;
290    /**< Executor matcher. */
291    unsigned int executorMatcher;
292    /**< Executor sensor hint under the same authentication type. 0 is not allowed. */
293    unsigned int executorSensorHint;
294    /**< Auth sub type. */
295    int authSubType;
296};
297
298/**
299 * @brief Defines credential enrollment information.
300 *
301 * @since 4.0
302 * @version 1.0
303 */
304struct EnrolledInfo {
305    /**< Enrollment ID. */
306    unsigned long enrolledId;
307    /**< Authentication type. See @{AuthType}. */
308    int authType;
309};
310
311/**
312 * @brief Defines enrollment result information.
313 *
314 * @since 4.0
315 * @version 1.0
316 */
317struct EnrollResultInfo {
318    /**< Credential ID. */
319    unsigned long credentialId;
320    /**< Old credential information. See {@link CredentialInfo}. */
321    struct CredentialInfo oldInfo;
322    /**< Protection key for the user file key. */
323    unsigned char[] rootSecret;
324    /**< Old protection key for the user file key. */
325    unsigned char[] oldRootSecret;
326    /**< Indicates the authentication token of the user password. */
327    unsigned char[] authToken;
328};
329
330/**
331 * @brief Defines scheduling information.
332 *
333 * @since 3.2
334 * @version 2.0
335 */
336struct ScheduleInfo {
337    /**< Schedule index of authentication. */
338    unsigned long scheduleId;
339    /**< Templates to authenticate. */
340    unsigned long[] templateIds;
341    /**< Authentication type. See @{AuthType}. */
342    int authType;
343    /**< Executor matcher. */
344    unsigned int executorMatcher;
345    /**< Operation to perform. See @{scheduleMode}*/
346    int scheduleMode;
347    /**< Executor indexes. */
348    unsigned long [] executorIndexes;
349    /**< Executor messages. */
350    unsigned char[][] executorMessages;
351};
352
353/**
354 * @brief Defines enrolled users information.
355 *
356 * @since 4.0
357 * @version 1.1
358 */
359struct UserInfo {
360    /**< SecureUid of this user. */
361    unsigned long secureUid;
362    /**< PinSubType of this user. See @{@PinSubType}. */
363    int pinSubType;
364    /**< Related enrolled information list. See @{EnrolledInfo}. */
365    struct EnrolledInfo[] enrolledInfos;
366};
367
368/**
369 * @brief Defines enrolled users information.
370 *
371 * @since 4.1
372 * @version 1.2
373 */
374struct ExtUserInfo {
375    /**< User ID. */
376    int userId;
377    /**< info of this user. */
378    struct UserInfo userInfo;
379};
380
381/**
382 * @brief Defines the authentication param.
383 *
384 * @since 5.0
385 * @version 1.0
386 */
387struct AuthParamBase {
388    /**< User ID. */
389    int userId;
390    /**< Authentication trust level. */
391    unsigned int authTrustLevel;
392    /**< Executor sensor hint under the same authentication type, 0 is not allowed. */
393    unsigned int executorSensorHint;
394    /**< Challenge of the authentication. */
395    unsigned char[] challenge;
396    /**< Caller name. */
397    String callerName;
398    /**< Caller Type. */
399    int callerType;
400    /**< Calling napi or innerkit api version. */
401    int apiVersion;
402};
403
404/**
405 * @brief Defines the authentication parameter.
406 *
407 * @since 5.0
408 * @version 1.0
409 */
410struct AuthParam {
411    /**< Authentication parameter. See @{AuthParamBase}. */
412    AuthParamBase baseParam;
413    /**< Authentication type. See @{AuthType}. */
414    int authType;
415    /**< Authentication intent. See @{AuthIntent}. */
416    int authIntent;
417    /**< Is os account verified. */
418    boolean isOsAccountVerified;
419    /**< Collector udid. */
420    String collectorUdid;
421};
422
423/**
424 * @brief Request information of reused unlock result.
425 *
426 * @since 5.0
427 * @version 1.0
428 */
429struct ReuseUnlockParam {
430    /**< Authentication parameter. See @{AuthParam}. */
431    AuthParamBase baseParam;
432    /** Authentication type. See @{AuthType}. */
433    int[] authTypes;
434    /** The allowable reuse duration. */
435    unsigned long reuseUnlockResultDuration;
436    /** Reuse unlock result mode. See @{ReuseMode}. */
437    int reuseUnlockResultMode;
438};
439
440/**
441 * @brief Defines credential enrollment parameters.
442 *
443 * @since 3.2
444 * @version 3.0
445 */
446struct EnrollParam {
447    /**< Authentication type. See @{AuthType}. */
448    int authType;
449    /**< Executor sensor hint under the same authentication type. 0 is not allowed. */
450    unsigned int executorSensorHint;
451    /**< Caller name. */
452    String callerName;
453    /** Caller Type. */
454    int callerType;
455    /**< Calling napi or innerkit api version. */
456    int apiVersion;
457    /**< User ID. */
458    int userId;
459    /**< User Type. */
460    int userType;
461    /**< Auth sub type. */
462    int authSubType;
463};
464
465/**
466* @brief Define credential enrollment ID information.
467*
468 * @since 5.0
469 * @version 1.0
470*/
471struct EnrolledState {
472    /** Desensitization Enrolled ID. */
473    unsigned long credentialDigest;
474    /** Number of Credential. */
475    unsigned short credentialCount;
476};
477
478/**
479 * @brief The reuse result of unlock device.
480 *
481 * @since 5.0
482 * @version 1.0
483 */
484struct ReuseUnlockInfo {
485    /**< Authentication type. See @{AuthType}. */
486    int authType;
487    /**< Authentication token. */
488    unsigned char[] token;
489    /**< Enrolled state. See @{EnrolledState}. */
490    EnrolledState enrolledState;
491};
492
493/**
494 * @brief Global config type.
495 *
496 * @since 5.0
497 * @version 1.0
498 */
499enum GlobalConfigType : int {
500    /** Pin expired period */
501    PIN_EXPIRED_PERIOD = 1,
502    /** Enable specified authType capability. */
503    ENABLE_STATUS = 2,
504};
505
506/**
507 * @brief Global config value.
508 *
509 * @since 5.0
510 * @version 1.0
511 */
512union GlobalConfigValue {
513    /** Pin expired period value. When pinExpiredPeriod equals to 0, userAuth won't check pin expired period. */
514    long pinExpiredPeriod;
515    /** Enable specified authType capability.*/
516    boolean enableStatus;
517};
518
519/**
520 * @brief Global config param.
521 *
522 * @since 5.0
523 * @version 1.0
524 */
525struct GlobalConfigParam {
526    /** Global config type. See @{GlobalConfigType}*/
527    int type;
528    /** Global config value. See @{GlobalConfigValue}*/
529    GlobalConfigValue value;
530    /** Specified userIds. GlobalConfigParam will be effect for all userspaces when the array is empty. */
531    int[] userIds;
532    /** Specified authTypes, shouldn't empty. See @{AuthType}.*/
533    int[] authTypes;
534};
535/** @} */