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