1/* 2 * Copyright (c) 2022 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 executor, 24 * manage credentials, and complete password and biometric authentication. 25 * @since 3.2 26 */ 27 28/** 29 * @file IUserAuthInterface.idl 30 * 31 * @brief Declare the APIs of userauth driver. These APIs can be used to register executor, 32 * manage credentials, and complete password and biometric authentication. 33 * 34 * @since 3.2 35 */ 36 37package ohos.hdi.user_auth.v1_0; 38 39import ohos.hdi.user_auth.v1_0.UserAuthTypes; 40 41/** 42 * @brief Declare the APIs of userauth driver. 43 * 44 * @since 3.2 45 * @version 1.0 46 */ 47interface IUserAuthInterface { 48 /** 49 * @brief Initialize cache information of 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 Add an authentication executor to obtain this authentication capability. 57 * 58 * @param info Indicates executor registration information, see {@link ExecutorRegisterInfo}. 59 * @param index Indicates executor index under the authentication frameworks. 60 * @param publicKey Indicates public key of authentication frameworks. 61 * @param templateIds Indicates templateIds enrolled by executor. 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 Delete executor. 70 * 71 * @param index Indicates executor index under the authentication frameworks. 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 Open authentication credential management session. 79 * 80 * @param userId Indicates user id. 81 * @param challenge Indicates random number, used to generate 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 Close authentication credential management session. 89 * 90 * @param userId Indicates 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 Begin the enrollment of authentication credential. 98 * When the authentication type is pin and the current user has enrolled PIN credential, 99 * the pin credential will be updated. 100 * 101 * @param userId Indicates user id. 102 * @param authToken Indicates user password authentication token. 103 * @param param Indicates input parameters, see {@link EnrollParam}. 104 * @param info Indicates scheduling information, see {@link ScheduleInfo}. 105 * 106 * @return Returns <b>0</b> if the operation is successful. 107 * @return Returns a non-zero value if the operation fails. 108 */ 109 BeginEnrollment([in] int userId, [in] unsigned char[] authToken, [in] struct EnrollParam param, 110 [out] struct ScheduleInfo info); 111 /** 112 * @brief Update the enrollment result and complete this enrollment. 113 * 114 * @param userId Indicates user id. 115 * @param scheduleResult Indicates enrollment result issued by executor. 116 * @param info Indicates enrollment result, see {@link EnrollResultInfo}. 117 * 118 * @return Returns <b>0</b> if the operation is successful. 119 * @return Returns a non-zero value if the operation fails. 120 */ 121 UpdateEnrollmentResult([in] int userId, [in] unsigned char[] scheduleResult, [out] struct EnrollResultInfo info); 122 /** 123 * @brief Cancel enrollment. 124 * 125 * @param userId Indicates user id. 126 * 127 * @return Returns <b>0</b> if the operation is successful. 128 * @return Returns a non-zero value if the operation fails. 129 */ 130 CancelEnrollment([in] int userId); 131 /** 132 * @brief Delete credential information. 133 * 134 * @param userId Indicates user id. 135 * @param credentialId Indicates credential id. 136 * @param authToken Indicates user password authentication token. 137 * @param info Indicates deleted credential information, see {@link CredentialInfo}. 138 * 139 * @return Returns <b>0</b> if the operation is successful. 140 * @return Returns a non-zero value if the operation fails. 141 */ 142 DeleteCredential([in] int userId, [in] unsigned long credentialId, [in] unsigned char[] authToken, 143 [out] struct CredentialInfo info); 144 /** 145 * @brief Query credential information. 146 * 147 * @param userId Indicates user id. 148 * @param authType Indicates authentication type, see {@link AuthType}. 149 * @param infos Indicates credential information, see {@link CredentialInfo}. 150 * 151 * @return Returns <b>0</b> if the operation is successful. 152 * @return Returns a non-zero value if the operation fails. 153 */ 154 GetCredential([in] int userId, [in] enum AuthType authType, [out] struct CredentialInfo[] infos); 155 /** 156 * @brief Query user information. 157 * 158 * @param userId Indicates user id. 159 * @param secureUid Indicates secure user id. 160 * @param pinSubType Indicates pin auth's subtype, see {@link PinSubType}. 161 * @param infos Indicates enrolled Info, see {@link EnrolledInfo}. 162 * 163 * @return Returns <b>0</b> if the operation is successful. 164 * @return Returns a non-zero value if the operation fails. 165 */ 166 GetUserInfo([in] int userId, [out] unsigned long secureUid, [out] enum PinSubType pinSubType, 167 [out] struct EnrolledInfo[] infos); 168 /** 169 * @brief Delete pin, delete user in Iam subsystem. 170 * 171 * @param userId Indicates user id. 172 * @param authToken Indicates user password authentication token. 173 * @param deletedInfos Indicates deleted credential information, see {@link CredentialInfo}. 174 * 175 * @return Returns <b>0</b> if the operation is successful. 176 * @return Returns a non-zero value if the operation fails. 177 */ 178 DeleteUser([in] int userId, [in] unsigned char[] authToken, [out] struct CredentialInfo[] deletedInfos); 179 /** 180 * @brief Forcibly delete user. 181 * 182 * @param userId Indicates user id. 183 * @param deletedInfos Indicates deleted credential information, see {@link CredentialInfo}. 184 * 185 * @return Returns <b>0</b> if the operation is successful. 186 * @return Returns a non-zero value if the operation fails. 187 */ 188 EnforceDeleteUser([in] int userId, [out] struct CredentialInfo[] deletedInfos); 189 /** 190 * @brief Begin authentication, and generate authentication scheme. 191 * 192 * @param contextId Indicates context id. 193 * @param param Indicates input parameters, see {@link AuthSolution}. 194 * @param scheduleInfos Indicates scheduling information, see {@link ScheduleInfo}. 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 BeginAuthentication([in] unsigned long contextId, [in] struct AuthSolution param, 200 [out] struct ScheduleInfo[] scheduleInfos); 201 /** 202 * @brief Update authentication result, and evaluate the results of this authentication scheme. 203 * 204 * @param contextId Indicates context id. 205 * @param scheduleResult Indicates authentication result issued by executor. 206 * @param info Indicates authentication result information, see {@link AuthResultInfo}. 207 * 208 * @return Returns <b>0</b> if the operation is successful. 209 * @return Returns a non-zero value if the operation fails. 210 */ 211 UpdateAuthenticationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult, 212 [out] struct AuthResultInfo info); 213 /** 214 * @brief Cancel authentication. 215 * 216 * @param contextId Indicates context id. 217 * 218 * @return Returns <b>0</b> if the operation is successful. 219 * @return Returns a non-zero value if the operation fails. 220 */ 221 CancelAuthentication([in] unsigned long contextId); 222 /** 223 * @brief Begin identification, and generate identification scheme. 224 * 225 * @param contextId Indicates context id. 226 * @param authType Indicates identification type, see @{AuthType}. 227 * @param executorSensorHint Indicates executor sensor hint, 0 indicates that no value is specified. 228 * @param scheduleInfo Indicates scheduling information, see {@link ScheduleInfo}. 229 * 230 * @return Returns <b>0</b> if the operation is successful. 231 * @return Returns a non-zero value if the operation fails. 232 */ 233 BeginIdentification([in] unsigned long contextId, [in] enum AuthType authType, [in] unsigned char[] challenge, 234 [in] unsigned int executorSensorHint, [out] struct ScheduleInfo scheduleInfo); 235 /** 236 * @brief Update identification result, and evaluate the results of this identification scheme. 237 * 238 * @param contextId Indicates context id. 239 * @param scheduleResult Indicates identification result issued by executor. 240 * @param info Indicates identification result information, see {@link IdentifyResultInfo}. 241 * 242 * @return Returns <b>0</b> if the operation is successful. 243 * @return Returns a non-zero value if the operation fails. 244 */ 245 UpdateIdentificationResult([in] unsigned long contextId, [in] unsigned char[] scheduleResult, 246 [out] struct IdentifyResultInfo info); 247 /** 248 * @brief Cancel identification. 249 * 250 * @param contextId Indicates context id. 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 CancelIdentification([in] unsigned long contextId); 256 /** 257 * @brief Get the authentication trust level of the current authentication type. 258 * 259 * @param userId Indicates user id. 260 * @param authType Indicates authentication type, see {@link AuthType}. 261 * @param authTrustLevel Indicates authentication trust level. 262 * 263 * @return Returns <b>0</b> if the operation is successful. 264 * @return Returns a non-zero value if the operation fails. 265 */ 266 GetAuthTrustLevel([in] int userId, [in] enum AuthType authType, [out] unsigned int authTrustLevel); 267 /** 268 * @brief Get the valid authentication methods under the current authentication trust level. 269 * 270 * @param userId Indicates user id. 271 * @param authTypes Indicates authentication type of the to be filtered, see {@link AuthType}. 272 * @param authTrustLevel Indicates authentication trust level. 273 * @param validTypes Indicates valid authentication type, see {@link AuthType}. 274 * 275 * @return Returns <b>0</b> if the operation is successful. 276 * @return Returns a non-zero value if the operation fails. 277 */ 278 GetValidSolution([in] int userId, [in] enum AuthType[] authTypes, [in] unsigned int authTrustLevel, 279 [out] enum AuthType[] validTypes); 280} 281