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 #ifndef APPSPAWN_H 17 #define APPSPAWN_H 18 19 #include <stdint.h> 20 #include <stdio.h> 21 #include <stdlib.h> 22 #include <stdbool.h> 23 #include <unistd.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * @brief appspawn请求消息构造句柄，不支持多线程消息构建 31 * 32 * 根据业务使用AppSpawnReqMsgCreate/AppSpawnTerminateMsgCreate 构建消息 33 * 如果调用AppSpawnClientSendMsg后，消息句柄不需要处理 34 * 否则需要调用 AppSpawnReqMsgFree 释放句柄 35 * 36 * 所有字符串输入的接口，只能接受合法的字符串，输入null、""、和大于合法长度的字符串都返回错误 37 * 38 */ 39 typedef void *AppSpawnReqMsgHandle; 40 41 /** 42 * @brief 支持多线程获取句柄，这个是线程安全的。使用时，全局创建一个句柄，支持多线程发送对应线程的消息请求 43 * 44 */ 45 typedef void *AppSpawnClientHandle; 46 47 #define INVALID_PERMISSION_INDEX (-1) 48 #define INVALID_REQ_HANDLE NULL 49 #define NWEBSPAWN_SERVER_NAME "nwebspawn" 50 #define APPSPAWN_SERVER_NAME "appspawn" 51 #define CJAPPSPAWN_SERVER_NAME "cjappspawn" 52 #define NWEBSPAWN_RESTART "nwebRestart" 53 #define NATIVESPAWN_SERVER_NAME "nativespawn" 54 55 #pragma pack(4) 56 #define APP_MAX_GIDS 64 57 #define APP_USER_NAME 64 58 #define APP_MAX_FD_COUNT 16 59 #define APP_FDENV_PREFIX "APPSPAWN_FD_" 60 #define APP_FDNAME_MAXLEN 20 61 typedef struct { 62 uint32_t uid; // the UNIX uid that the child process setuid() to after fork() 63 uint32_t gid; // the UNIX gid that the child process setgid() to after fork() 64 uint32_t gidCount; // the size of gidTable 65 uint32_t gidTable[APP_MAX_GIDS]; 66 char userName[APP_USER_NAME]; 67 } AppDacInfo; 68 69 typedef struct { 70 int result; 71 pid_t pid; 72 } AppSpawnResult; 73 #pragma pack() 74 75 /** 76 * @brief init spawn client, eg: nwebspawn、appspawn 77 * 78 * @param serviceName service name, eg: nwebspawn、appspawn 79 * @param handle handle for client 80 * @return if succeed return 0,else return other value 81 */ 82 int AppSpawnClientInit(const char *serviceName, AppSpawnClientHandle *handle); 83 /** 84 * @brief destroy client 85 * 86 * @param handle handle for client 87 * @return if succeed return 0,else return other value 88 */ 89 int AppSpawnClientDestroy(AppSpawnClientHandle handle); 90 91 /** 92 * @brief send client request 93 * 94 * @param handle handle for client 95 * @param reqHandle handle for request 96 * @param result result from appspawn service 97 * @return if succeed return 0,else return other value 98 */ 99 int AppSpawnClientSendMsg(AppSpawnClientHandle handle, AppSpawnReqMsgHandle reqHandle, AppSpawnResult *result); 100 101 /** 102 * @brief send client user lock status request 103 * 104 * @param userId user id 105 * @param isLocked lock status 106 * @return if succeed return 0,else return other value 107 */ 108 int AppSpawnClientSendUserLockStatus(uint32_t userId, bool isLocked); 109 110 typedef enum { 111 MSG_APP_SPAWN = 0, 112 MSG_GET_RENDER_TERMINATION_STATUS, 113 MSG_SPAWN_NATIVE_PROCESS, 114 MSG_DUMP, 115 MSG_BEGET_CMD, 116 MSG_BEGET_SPAWNTIME, 117 MSG_UPDATE_MOUNT_POINTS, 118 MSG_RESTART_SPAWNER, 119 MSG_DEVICE_DEBUG, 120 MSG_UNINSTALL_DEBUG_HAP, 121 MSG_LOCK_STATUS, 122 MSG_OBSERVE_PROCESS_SIGNAL_STATUS, 123 MAX_TYPE_INVALID 124 } AppSpawnMsgType; 125 126 /** 127 * @brief create spawn request 128 * 129 * @param msgType msg type. eg: MSG_APP_SPAWN,MSG_SPAWN_NATIVE_PROCESS 130 * @param processName process name, max length is 255 131 * @param reqHandle handle for request message 132 * @return if succeed return 0,else return other value 133 */ 134 int AppSpawnReqMsgCreate(AppSpawnMsgType msgType, const char *processName, AppSpawnReqMsgHandle *reqHandle); 135 136 /** 137 * @brief create request 138 * 139 * @param pid process pid 140 * @param reqHandle handle for request message 141 * @return if succeed return 0,else return other value 142 */ 143 int AppSpawnTerminateMsgCreate(pid_t pid, AppSpawnReqMsgHandle *reqHandle); 144 145 /** 146 * @brief destroy request 147 * 148 * @param reqHandle handle for request 149 */ 150 void AppSpawnReqMsgFree(AppSpawnReqMsgHandle reqHandle); 151 152 /** 153 * @brief set bundle info 154 * 155 * @param reqHandle handle for request message 156 * @param bundleIndex bundle index 157 * @param bundleName bundle name, max length is 255 158 * @return if succeed return 0,else return other value 159 */ 160 int AppSpawnReqMsgSetBundleInfo(AppSpawnReqMsgHandle reqHandle, uint32_t bundleIndex, const char *bundleName); 161 162 /** 163 * @brief set app flags info 164 * 165 * @param reqHandle handle for request message 166 * @param flagIndex flags index from AppFlagsIndex 167 * @return if succeed return 0,else return other value 168 */ 169 typedef enum { 170 APP_FLAGS_COLD_BOOT = 0, 171 APP_FLAGS_BACKUP_EXTENSION = 1, 172 APP_FLAGS_DLP_MANAGER = 2, 173 APP_FLAGS_DEBUGGABLE = 3, 174 APP_FLAGS_ASANENABLED = 4, 175 APP_FLAGS_ACCESS_BUNDLE_DIR = 5, 176 APP_FLAGS_NATIVEDEBUG = 6, 177 APP_FLAGS_NO_SANDBOX = 7, 178 APP_FLAGS_OVERLAY = 8, 179 APP_FLAGS_BUNDLE_RESOURCES = 9, 180 APP_FLAGS_GWP_ENABLED_FORCE, // APP_GWP_ENABLED_FORCE 0x400 181 APP_FLAGS_GWP_ENABLED_NORMAL, // APP_GWP_ENABLED_NORMAL 0x800 182 APP_FLAGS_TSAN_ENABLED, // APP_TSANENABLED 0x1000 183 APP_FLAGS_IGNORE_SANDBOX = 13, // ignore sandbox result 184 APP_FLAGS_ISOLATED_SANDBOX, 185 APP_FLAGS_EXTENSION_SANDBOX, 186 APP_FLAGS_CLONE_ENABLE, 187 APP_FLAGS_DEVELOPER_MODE = 17, 188 APP_FLAGS_BEGETCTL_BOOT, // Start an app from begetctl. 189 APP_FLAGS_ATOMIC_SERVICE, 190 APP_FLAGS_CHILDPROCESS, 191 APP_FLAGS_HWASAN_ENABLED = 21, 192 APP_FLAGS_UBSAN_ENABLED = 22, 193 APP_FLAGS_ISOLATED_SANDBOX_TYPE, 194 APP_FLAGS_ISOLATED_SELINUX_LABEL, 195 APP_FLAGS_ISOLATED_SECCOMP_TYPE, 196 APP_FLAGS_ISOLATED_NETWORK, 197 APP_FLAGS_ISOLATED_DATAGROUP, 198 APP_FLAGS_TEMP_JIT = 28, 199 APP_FLAGS_PRE_INSTALLED_HAP = 29, 200 APP_FLAGS_GET_ALL_PROCESSES = 30, 201 APP_FLAGS_CUSTOM_SANDBOX = 31, 202 MAX_FLAGS_INDEX = 63, 203 } AppFlagsIndex; 204 205 int AppSpawnReqMsgSetAppFlag(AppSpawnReqMsgHandle reqHandle, AppFlagsIndex flagIndex); 206 207 /** 208 * @brief set dac info 209 * 210 * @param reqHandle handle for request message 211 * @param dacInfo dac info from AppDacInfo 212 * @return if succeed return 0,else return other value 213 */ 214 int AppSpawnReqMsgSetAppDacInfo(AppSpawnReqMsgHandle reqHandle, const AppDacInfo *dacInfo); 215 216 /** 217 * @brief set domain info 218 * 219 * @param reqHandle handle for request message 220 * @param hapFlags hap of flags 221 * @param apl apl value, max length is 31 222 * @return if succeed return 0,else return other value 223 */ 224 int AppSpawnReqMsgSetAppDomainInfo(AppSpawnReqMsgHandle reqHandle, uint32_t hapFlags, const char *apl); 225 226 /** 227 * @brief set internet permission info 228 * 229 * @param reqHandle handle for request message 230 * @param allowInternet 231 * @param setAllowInternet 232 * @return if succeed return 0,else return other value 233 */ 234 int AppSpawnReqMsgSetAppInternetPermissionInfo(AppSpawnReqMsgHandle reqHandle, uint8_t allow, uint8_t setAllow); 235 236 /** 237 * @brief set access token info 238 * 239 * @param reqHandle handle for request message 240 * @param accessTokenIdEx access tokenId 241 * @return if succeed return 0,else return other value 242 */ 243 int AppSpawnReqMsgSetAppAccessToken(AppSpawnReqMsgHandle reqHandle, uint64_t accessTokenIdEx); 244 245 /** 246 * @brief set owner info 247 * 248 * @param reqHandle handle for request message 249 * @param ownerId owner id, max length is 63 250 * @return if succeed return 0,else return other value 251 */ 252 int AppSpawnReqMsgSetAppOwnerId(AppSpawnReqMsgHandle reqHandle, const char *ownerId); 253 254 /** 255 * @brief add permission to message 256 * 257 * @param reqHandle handle for request message 258 * @param permission permission name 259 * @return if succeed return 0,else return other value 260 */ 261 int AppSpawnReqMsgAddPermission(AppSpawnReqMsgHandle reqHandle, const char *permission); 262 263 /** 264 * @brief add permission to message 265 * 266 * @param handle handle for client 267 * @param reqHandle handle for request message 268 * @param permission permission name 269 * @return if succeed return 0,else return other value 270 */ 271 int AppSpawnClientAddPermission(AppSpawnClientHandle handle, AppSpawnReqMsgHandle reqHandle, const char *permission); 272 273 /** 274 * @brief add extend info to message 275 * 276 * @param reqHandle handle for request message 277 * @param name extend name, max length is 31 278 * @param value extend value, max length is 32768 279 * @param valueLen extend value length 280 * @return if succeed return 0,else return other value 281 */ 282 #define MSG_EXT_NAME_RENDER_CMD "render-cmd" 283 #define MSG_EXT_NAME_HSP_LIST "HspList" 284 #define MSG_EXT_NAME_OVERLAY "Overlay" 285 #define MSG_EXT_NAME_DATA_GROUP "DataGroup" 286 #define MSG_EXT_NAME_APP_ENV "AppEnv" 287 #define MSG_EXT_NAME_APP_EXTENSION "AppExtension" 288 #define MSG_EXT_NAME_BEGET_PID "AppPid" 289 #define MSG_EXT_NAME_BEGET_PTY_NAME "ptyName" 290 #define MSG_EXT_NAME_ACCOUNT_ID "AccountId" 291 #define MSG_EXT_NAME_PROVISION_TYPE "ProvisionType" 292 #define MSG_EXT_NAME_PROCESS_TYPE "ProcessType" 293 #define MSG_EXT_NAME_MAX_CHILD_PROCCESS_MAX "MaxChildProcess" 294 #define MSG_EXT_NAME_APP_FD "AppFd" 295 #define MSG_EXT_NAME_JIT_PERMISSIONS "Permissions" 296 #define MSG_EXT_NAME_USERID "uid" 297 #define MSG_EXT_NAME_EXTENSION_TYPE "ExtensionType" 298 299 int AppSpawnReqMsgAddExtInfo(AppSpawnReqMsgHandle reqHandle, const char *name, const uint8_t *value, uint32_t valueLen); 300 301 /** 302 * @brief add extend info to message 303 * 304 * @param reqHandle handle for request message 305 * @param name extend name, max length is 31 306 * @param value extend value, max length is 32767 307 * @return if succeed return 0,else return other value 308 */ 309 int AppSpawnReqMsgAddStringInfo(AppSpawnReqMsgHandle reqHandle, const char *name, const char *value); 310 311 /** 312 * @brief add fd info to message 313 * 314 * @param reqHandle handle for request message 315 * @param name fd name 316 * @param value fd value 317 * @return if succeed return 0,else return other value 318 */ 319 int AppSpawnReqMsgAddFd(AppSpawnReqMsgHandle reqHandle, const char* fdName, int fd); 320 321 /** 322 * @brief Get the permission index by permission name 323 * 324 * @param handle handle for client 325 * @param permission permission name 326 * @return int32_t permission index, if not exit, return INVALID_PERMISSION_INDEX 327 */ 328 int32_t GetPermissionIndex(AppSpawnClientHandle handle, const char *permission); 329 330 /** 331 * @brief Get the max permission Index 332 * 333 * @param handle handle for client 334 * @return int32_t max permission Index 335 */ 336 int32_t GetMaxPermissionIndex(AppSpawnClientHandle handle); 337 338 /** 339 * @brief Get the permission name by index 340 * 341 * @param handle handle for client 342 * @param index permission index 343 * @return const char* permission name 344 */ 345 const char *GetPermissionByIndex(AppSpawnClientHandle handle, int32_t index); 346 347 /** 348 * @brief set up a pipe fd to capture the exit reason of a child process 349 * 350 * @param fd fd for write signal info 351 * @return if succeed return 0,else return other value 352 */ 353 int SpawnListenFdSet(int fd); 354 355 /** 356 * @brief close the listener for child process exit 357 * 358 * @return if succeed return 0,else return other value 359 */ 360 int SpawnListenCloseSet(void); 361 362 #ifdef __cplusplus 363 } 364 #endif 365 366 #endif 367