1 /* 2 * Copyright (C) 2021-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 #ifndef DEVICE_AUTH_H 17 #define DEVICE_AUTH_H 18 19 #include <stdint.h> 20 #include <stdbool.h> 21 22 #if defined(__LINUX__) || defined(_UNIX) 23 #define DEVICE_AUTH_API_PUBLIC __attribute__ ((visibility("default"))) 24 #else 25 #define DEVICE_AUTH_API_PUBLIC 26 #endif 27 28 #define FIELD_GROUP_ID "groupId" 29 #define FIELD_GROUP_TYPE "groupType" 30 #define FIELD_GROUP_NAME "groupName" 31 #define FIELD_PEER_DEVICE_ID "peerDeviceId" 32 #define FIELD_IS_ADMIN "isAdmin" 33 #define FIELD_CREDENTIAL_TYPE "credentialType" 34 #define FIELD_IS_FORCE_DELETE "isForceDelete" 35 #define FIELD_IS_IGNORE_CHANNEL "isIgnoreChannel" 36 #define FIELD_CONNECT_PARAMS "connectParams" 37 #define FIELD_ADD_ID "addId" 38 #define FIELD_DELETE_ID "deleteId" 39 #define FIELD_APP_ID "appId" 40 #define FIELD_SERVICE_TYPE "serviceType" 41 #define FIELD_IS_DEVICE_LEVEL "isDeviceLevel" 42 #define FIELD_ALTERNATIVE "alternative" 43 #define FIELD_PEER_UDID "peerUdid" 44 #define FIELD_PEER_CONN_DEVICE_ID "peerConnDeviceId" 45 #define FIELD_KEY_LENGTH "keyLength" 46 #define FIELD_IS_CLIENT "isClient" 47 #define FIELD_SESSION_KEY "sessionKey" 48 #define FIELD_AUTH_FORM "authForm" 49 #define FIELD_CONFIRMATION "confirmation" 50 #define FIELD_GROUP_OWNER "groupOwner" 51 #define FIELD_PEER_AUTH_ID "peerAuthId" 52 #define FIELD_PEER_USER_TYPE "peerUserType" 53 #define FIELD_PEER_USER_ID "peerUserId" 54 #define FIELD_SERVICE_PKG_NAME "servicePkgName" 55 #define FIELD_USER_TYPE "userType" 56 #define FIELD_USER_ID "userId" 57 #define FIELD_SHARED_USER_ID "sharedUserId" 58 #define FIELD_OWNER_USER_ID "ownerUserId" 59 #define FIELD_DEVICE_ID "deviceId" 60 #define FIELD_PIN_CODE "pinCode" 61 #define FIELD_AUTH_ID "authId" 62 #define FIELD_UDID "udid" 63 #define FIELD_IS_SELF_PK "isSelfPk" 64 #define FIELD_GROUP_VISIBILITY "groupVisibility" 65 #define FIELD_EXPIRE_TIME "expireTime" 66 #define FIELD_IS_DELETE_ALL "isDeleteAll" 67 #define FIELD_OS_ACCOUNT_ID "osAccountId" 68 #define FIELD_ACQURIED_TYPE "acquireType" 69 #define FIELD_CRED_OP_FLAG "flag" 70 #define FIELD_CRED_OP_RESULT "result" 71 #define FIELD_AUTH_CODE "authCode" 72 #define FIELD_DEVICE_LIST "deviceList" 73 #define FIELD_IS_UDID_HASH "isUdidHash" 74 #define FIELD_PROTOCOL_EXPAND "protocolExpand" 75 76 /** 77 * @brief protocol expand value for bind 78 */ 79 typedef enum { 80 /** use this flag to support bind base on symmetric credential when interact with lite device */ 81 LITE_PROTOCOL_STANDARD_MODE = 1, 82 /** use this flag when interact with lite device which used iso with short pin */ 83 LITE_PROTOCOL_COMPATIBILITY_MODE = 2, 84 } ProtocolExpandValue; 85 86 /** 87 * @brief type of local system account 88 */ 89 typedef enum { 90 /** default local system account */ 91 DEFAULT_OS_ACCOUNT = 0, 92 /** the local system account of foreground user */ 93 ANY_OS_ACCOUNT = -2, 94 } OsAccountEnum; 95 96 /** 97 * @brief describes all group types 98 */ 99 typedef enum { 100 /** refers to all group types and is used to query group information */ 101 ALL_GROUP = 0, 102 /** group type of the same clound account */ 103 IDENTICAL_ACCOUNT_GROUP = 1, 104 /** group type of the p2p binding */ 105 PEER_TO_PEER_GROUP = 256, 106 /** group type shared to other cloud accounts */ 107 ACROSS_ACCOUNT_AUTHORIZE_GROUP = 1282 108 } GroupType; 109 110 /** 111 * @brief describes all group visibility types 112 */ 113 typedef enum { 114 /** visibility type of private group */ 115 GROUP_VISIBILITY_PRIVATE = 0, 116 /** visibility type of public group */ 117 GROUP_VISIBILITY_PUBLIC = -1 118 } GroupVisibility; 119 120 /** 121 * @brief describes all group operation codes 122 */ 123 typedef enum { 124 /** opeation code for group creation */ 125 GROUP_CREATE = 0, 126 /** opeation code for group destruction */ 127 GROUP_DISBAND = 1, 128 /** opeation code for inviting the peer device to join the local trusted group */ 129 MEMBER_INVITE = 2, 130 /** opeation code for joining the peer trusted group */ 131 MEMBER_JOIN = 3, 132 /** opeation code for unbinding with peer device */ 133 MEMBER_DELETE = 4, 134 } GroupOperationCode; 135 136 /** 137 * @brief describes all group authentication types 138 */ 139 typedef enum { 140 /** invalid group authentication type */ 141 AUTH_FORM_INVALID_TYPE = -1, 142 /** p2p group authentication type */ 143 AUTH_FORM_ACCOUNT_UNRELATED = 0, 144 /** group authentication type of the same cloud account */ 145 AUTH_FORM_IDENTICAL_ACCOUNT = 1, 146 /** group authentication type shared to other cloud accounts */ 147 AUTH_FORM_ACROSS_ACCOUNT = 2, 148 } GroupAuthForm; 149 150 /** 151 * @brief describes all credential types 152 */ 153 typedef enum { 154 /** symmetrical credential type */ 155 SYMMETRIC_CRED = 1, 156 /** asymmetric credential type */ 157 ASYMMETRIC_CRED = 2, 158 } CredType; 159 160 /** 161 * @brief describes all device types 162 */ 163 typedef enum { 164 /** device type is accessory */ 165 DEVICE_TYPE_ACCESSORY = 0, 166 /** device type is controller */ 167 DEVICE_TYPE_CONTROLLER = 1, 168 /** device type is proxy */ 169 DEVICE_TYPE_PROXY = 2 170 } UserType; 171 172 /** 173 * @brief describes request response results 174 */ 175 typedef enum { 176 /** reject the request from the peer device */ 177 REQUEST_REJECTED = 0x80000005, 178 /** accept the request from the peer device */ 179 REQUEST_ACCEPTED = 0x80000006, 180 } RequestResponse; 181 182 /** 183 * @brief This structure provides the ability to monitor changes in trusted groups and devices. 184 */ 185 typedef struct { 186 /** Call it when a new group is created. */ 187 void (*onGroupCreated)(const char *groupInfo); 188 /** Call it when a group is destroyed. */ 189 void (*onGroupDeleted)(const char *groupInfo); 190 /** Call it when a group adds a trusted device. */ 191 void (*onDeviceBound)(const char *peerUdid, const char *groupInfo); 192 /** Call it when a group deletes a trusted device. */ 193 void (*onDeviceUnBound)(const char *peerUdid, const char *groupInfo); 194 /** Call it when a device has no trust relationship in all groups. */ 195 void (*onDeviceNotTrusted)(const char *peerUdid); 196 /** Call it when a device has no trust relationship in all groups of a certain type. */ 197 void (*onLastGroupDeleted)(const char *peerUdid, int groupType); 198 void (*onTrustedDeviceNumChanged)(int curTrustedDeviceNum); 199 } DataChangeListener; 200 201 /** 202 * @brief This structure describes the callbacks that need to be provided by the business. 203 */ 204 typedef struct { 205 /** Call it when there is data to be sent. */ 206 bool (*onTransmit)(int64_t requestId, const uint8_t *data, uint32_t dataLen); 207 /** Call it when the session key is returned. */ 208 void (*onSessionKeyReturned)(int64_t requestId, const uint8_t *sessionKey, uint32_t sessionKeyLen); 209 /** Call it when the asynchronous operation is successful. */ 210 void (*onFinish)(int64_t requestId, int operationCode, const char *returnData); 211 /** Call it when the asynchronous operation fails. */ 212 void (*onError)(int64_t requestId, int operationCode, int errorCode, const char *errorReturn); 213 /** Call it when receiving requests from other devices. */ 214 char *(*onRequest)(int64_t requestId, int operationCode, const char *reqParams); 215 } DeviceAuthCallback; 216 217 /** 218 * @brief This structure provides all the capabilities of group authentication. 219 */ 220 typedef struct { 221 /** This interface is used to process authentication data. */ 222 int32_t (*processData)(int64_t authReqId, const uint8_t *data, uint32_t dataLen, 223 const DeviceAuthCallback *gaCallback); 224 /** This interface is used to initiate authentication between devices. */ 225 int32_t (*authDevice)(int32_t osAccountId, int64_t authReqId, const char *authParams, 226 const DeviceAuthCallback *gaCallback); 227 /** This interface is used to cancel an authentication process. */ 228 void (*cancelRequest)(int64_t requestId, const char *appId); 229 /** This interface is used to get real info by pseudonym id. */ 230 int32_t (*getRealInfo)(int32_t osAccountId, const char *pseudonymId, char **realInfo); 231 /** This interface is used to get pseudonym id by an index. */ 232 int32_t (*getPseudonymId)(int32_t osAccountId, const char *indexKey, char **pseudonymId); 233 } GroupAuthManager; 234 235 typedef struct { 236 /** This interface is used to register business callbacks. */ 237 int32_t (*regCallback)(const char *appId, const DeviceAuthCallback *callback); 238 /** This interface is used to unregister business callbacks. */ 239 int32_t (*unRegCallback)(const char *appId); 240 /** This interface is used to register callback for data change monitoring. */ 241 int32_t (*regDataChangeListener)(const char *appId, const DataChangeListener *listener); 242 /** This interface is used to unregister callback for data change monitoring. */ 243 int32_t (*unRegDataChangeListener)(const char *appId); 244 /** This interface is used to create a trusted group. */ 245 int32_t (*createGroup)(int32_t osAccountId, int64_t requestId, const char *appId, const char *createParams); 246 /** This interface is used to delete a trusted group. */ 247 int32_t (*deleteGroup)(int32_t osAccountId, int64_t requestId, const char *appId, const char *disbandParams); 248 /** This interface is used to add a trusted device to a trusted group. */ 249 int32_t (*addMemberToGroup)(int32_t osAccountId, int64_t requestId, const char *appId, const char *addParams); 250 /** This interface is used to delete a trusted device from a trusted group. */ 251 int32_t (*deleteMemberFromGroup)(int32_t osAccountId, int64_t requestId, const char *appId, 252 const char *deleteParams); 253 /** This interface is used to process data of binding or unbinding devices. */ 254 int32_t (*processData)(int64_t requestId, const uint8_t *data, uint32_t dataLen); 255 /** This interface is used to batch add trusted devices with account relationships. */ 256 int32_t (*addMultiMembersToGroup)(int32_t osAccountId, const char *appId, const char *addParams); 257 /** This interface is used to batch delete trusted devices with account relationships. */ 258 int32_t (*delMultiMembersFromGroup)(int32_t osAccountId, const char *appId, const char *deleteParams); 259 /** This interface is used to obtain the registration information of the local device. */ 260 int32_t (*getRegisterInfo)(const char *reqJsonStr, char **returnRegisterInfo); 261 /** This interface is used to check whether the specified application has access rights to the group. */ 262 int32_t (*checkAccessToGroup)(int32_t osAccountId, const char *appId, const char *groupId); 263 /** This interface is used to obtain all public key information related to a device. */ 264 int32_t (*getPkInfoList)(int32_t osAccountId, const char *appId, const char *queryParams, char **returnInfoList, 265 uint32_t *returnInfoNum); 266 /** This interface is used to obtain group information of a group. */ 267 int32_t (*getGroupInfoById)(int32_t osAccountId, const char *appId, const char *groupId, char **returnGroupInfo); 268 /** This interface is used to obtain the group information of groups that meet the query parameters. */ 269 int32_t (*getGroupInfo)(int32_t osAccountId, const char *appId, const char *queryParams, 270 char **returnGroupVec, uint32_t *groupNum); 271 /** This interface is used to obtain all group information of a specific group type. */ 272 int32_t (*getJoinedGroups)(int32_t osAccountId, const char *appId, int groupType, 273 char **returnGroupVec, uint32_t *groupNum); 274 /** This interface is used to obtain all group information related to a certain device. */ 275 int32_t (*getRelatedGroups)(int32_t osAccountId, const char *appId, const char *peerDeviceId, 276 char **returnGroupVec, uint32_t *groupNum); 277 /** This interface is used to obtain the information of a trusted device. */ 278 int32_t (*getDeviceInfoById)(int32_t osAccountId, const char *appId, const char *deviceId, const char *groupId, 279 char **returnDeviceInfo); 280 /** This interface is used to obtain all trusted device information in a group. */ 281 int32_t (*getTrustedDevices)(int32_t osAccountId, const char *appId, const char *groupId, 282 char **returnDevInfoVec, uint32_t *deviceNum); 283 /** This interface is used to query whether a specified device exists in the group. */ 284 bool (*isDeviceInGroup)(int32_t osAccountId, const char *appId, const char *groupId, const char *deviceId); 285 /** This interface is used to cancel a binding or unbinding process. */ 286 void (*cancelRequest)(int64_t requestId, const char *appId); 287 /** This interface is used to destroy the information returned by the internal allocated memory. */ 288 void (*destroyInfo)(char **returnInfo); 289 } DeviceGroupManager; 290 291 /** 292 * @brief This enum provides all the operationCode of interface ProcessCredential. 293 */ 294 enum { 295 /** invalid operationCode for initialize */ 296 CRED_OP_INVALID = -1, 297 /** operationCode for ProcessCredential to query credential */ 298 CRED_OP_QUERY, 299 /** operationCode for ProcessCredential to create credential */ 300 CRED_OP_CREATE, 301 /** operationCode for ProcessCredential to import credential */ 302 CRED_OP_IMPORT, 303 /** operationCode for ProcessCredential to delete credential */ 304 CRED_OP_DELETE, 305 }; 306 307 /** 308 * @brief This enum provides all the flag of reqJsion for interface ProcessCredential. 309 */ 310 enum { 311 /** invalid flag for initialize */ 312 RETURN_FLAG_INVALID = -1, 313 /** flag for only return result */ 314 RETURN_FLAG_DEFAULT, 315 /** flag for return result and publicKey */ 316 RETURN_FLAG_PUBLIC_KEY, 317 }; 318 319 /** 320 * @brief This enum provides all the acquireType of interface StartAuthDevice & ProcessAuthDevice. 321 */ 322 typedef enum { 323 /** invalid acquireType for initialize */ 324 ACQUIRE_TYPE_INVALID = -1, 325 /** acquireType for p2p bind */ 326 P2P_BIND, 327 } AcquireType; 328 329 #ifdef __cplusplus 330 extern "C" { 331 #endif 332 333 /** 334 * @brief Process Credential data. 335 * 336 * This API is used to process Credential data. 337 * 338 * @param operationCode: use one of CRED_OP_QUERY|CRED_OP_CREATE|CRED_OP_IMPORT|CRED_OP_DELETE 339 * @param requestParams: json string contains group of osAccountId|deviceId|serviceType|acquireType|flag 340 * @param returnData: json string contains group of result|publicKey 341 * 342 * @return When the ipc call is successful, it returns HC_SUCCESS. 343 * Otherwise, it returns other values. 344 */ 345 DEVICE_AUTH_API_PUBLIC int32_t ProcessCredential( 346 int32_t operationCode, const char *requestParams, char **returnData); 347 348 /** 349 * @brief Start to auth device. 350 * 351 * This API is used to start to auth device. 352 * 353 * @param requestId: id of a request 354 * @param authParams: json string contains group of osAccountId|deviceId|serviceType|acquireType|pinCode 355 * @param callbak: callback object 356 * 357 * @return When the ipc call is successful, it returns HC_SUCCESS. 358 * Otherwise, it returns other values. 359 */ 360 DEVICE_AUTH_API_PUBLIC int32_t StartAuthDevice( 361 int64_t requestId, const char *authParams, const DeviceAuthCallback *callbak); 362 363 /** 364 * @brief Process auth device data. 365 * 366 * This API is used to process auth device data. 367 * 368 * @param requestId: id of a request 369 * @param authParams: json string contains group of osAccountId|data 370 * @param callbak: callback object 371 * 372 * @return When the ipc call is successful, it returns HC_SUCCESS. 373 * Otherwise, it returns other values. 374 */ 375 DEVICE_AUTH_API_PUBLIC int32_t ProcessAuthDevice( 376 int64_t requestId, const char *authParams, const DeviceAuthCallback *callbak); 377 378 /** 379 * @brief Cancle auth device request. 380 * 381 * This API is used to cancle auth device request. 382 * 383 * @param requestId: id of a request 384 * @param authParams: json string contains osAccountId or NULL 385 * 386 * @return When the ipc call is successful, it returns HC_SUCCESS. 387 * Otherwise, it returns other values. 388 */ 389 DEVICE_AUTH_API_PUBLIC int32_t CancelAuthRequest(int64_t requestId, const char *authParams); 390 391 /** 392 * @brief Initialize device auth service. 393 * 394 * This API is used to initialize device auth service. 395 * 396 * @return When the service initialization is successful, it returns HC_SUCCESS. 397 * Otherwise, it returns other values. 398 * @see DestroyDeviceAuthService 399 */ 400 DEVICE_AUTH_API_PUBLIC int InitDeviceAuthService(void); 401 402 /** 403 * @brief Destroy device auth service. 404 * 405 * This API is used to destroy device auth service. 406 * 407 * @see InitDeviceAuthService 408 */ 409 DEVICE_AUTH_API_PUBLIC void DestroyDeviceAuthService(void); 410 411 /** 412 * @brief Get group authentication instance. 413 * 414 * This API is used to get group authentication instance. 415 * The InitDeviceAuthService function must be called before using this method. 416 * 417 * @return When the method call result is successful, it returns GroupAuthManager instance. 418 * Otherwise, it returns NULL. 419 */ 420 DEVICE_AUTH_API_PUBLIC const GroupAuthManager *GetGaInstance(void); 421 422 /** 423 * @brief Get group management instance. 424 * 425 * This API is used to get group management instance. 426 * The InitDeviceAuthService function must be called before using this method. 427 * 428 * @return When the method call result is successful, it returns DeviceGroupManager instance. 429 * Otherwise, it returns NULL. 430 */ 431 DEVICE_AUTH_API_PUBLIC const DeviceGroupManager *GetGmInstance(void); 432 433 #ifdef __cplusplus 434 } 435 #endif 436 #endif 437