1/* 2 * Copyright (c) 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/** 17 * @file This module provides the capabilities to security guard. 18 * @kit SecurityGuardKit 19 */ 20 21import type { Callback } from '@ohos.base'; 22 23/** 24 * Provides security event management and security model management. 25 * Based on event information, you will be able to analyze the running status of devices. 26 * 27 * @namespace securityGuard 28 * @syscap SystemCapability.Security.SecurityGuard 29 * @systemapi Hide this for inner system use. 30 * @since 12 31 */ 32declare namespace securityGuard { 33 34 /** 35 * Provides the SecurityEvent type, including the event id, version info, report content. 36 * 37 * @typedef SecurityEvent 38 * @syscap SystemCapability.Security.SecurityGuard 39 * @systemapi Hide this for inner system use. 40 * @since 12 41 */ 42 interface SecurityEvent { 43 /** 44 * The event id 45 * 46 * @type { number } 47 * @syscap SystemCapability.Security.SecurityGuard 48 * @systemapi Hide this for inner system use. 49 * @since 12 50 */ 51 eventId: number; 52 53 /** 54 * The version of a security event. Different versions indicate different data formats. 55 * 56 * @type { string } 57 * @syscap SystemCapability.Security.SecurityGuard 58 * @systemapi Hide this for inner system use. 59 * @since 12 60 */ 61 version: string; 62 63 /** 64 * The report content 65 * 66 * @type { string } 67 * @syscap SystemCapability.Security.SecurityGuard 68 * @systemapi Hide this for inner system use. 69 * @since 12 70 */ 71 content: string; 72 73 /** 74 * The event timestamp, format is YYYYMMDDHHMMSS. 75 * 76 * @type { ?string } 77 * @syscap SystemCapability.Security.SecurityGuard 78 * @systemapi Hide this for inner system use. 79 * @since 12 80 */ 81 timestamp?: string; 82 } 83 84 /** 85 * Report security information to the security guard. 86 * 87 * @permission ohos.permission.REPORT_SECURITY_EVENT 88 * @param { SecurityEvent } securityEvent - indicates the information to be reported. 89 * @throws { BusinessError } 201 - check permission fail. 90 * @throws { BusinessError } 202 - non-system application uses the system API. 91 * @throws { BusinessError } 401 - invalid parameters. 92 * Possible causes: 93 * 1. Mandatory parameters are left unspecified. 94 * 2. Incorrect parameter types. 95 * 3. Parameter verification failed. 96 * @syscap SystemCapability.Security.SecurityGuard 97 * @systemapi Hide this for inner system use. 98 * @since 12 99 */ 100 function reportSecurityEvent(securityEvent: SecurityEvent): void; 101 102 /** 103 * Provides the conditions of querySecurityEvent. 104 * 105 * @interface SecurityEventRule 106 * @syscap SystemCapability.Security.SecurityGuard 107 * @systemapi Hide this for inner system use. 108 * @since 12 109 */ 110 interface SecurityEventRule { 111 /** 112 * The security event ids. 113 * 114 * @type { number } 115 * @syscap SystemCapability.Security.SecurityGuard 116 * @systemapi Hide this for inner system use. 117 * @since 12 118 */ 119 eventId: number; 120 121 /** 122 * The begin time, format is YYYYMMDDHHMMSS. 123 * 124 * @type { ?string } 125 * @syscap SystemCapability.Security.SecurityGuard 126 * @systemapi Hide this for inner system use. 127 * @since 12 128 */ 129 beginTime?: string; 130 131 /** 132 * The end time, format is YYYYMMDDHHMMSS. 133 * 134 * @type { ?string } 135 * @syscap SystemCapability.Security.SecurityGuard 136 * @systemapi Hide this for inner system use. 137 * @since 12 138 */ 139 endTime?: string; 140 141 /** 142 * The query condition. 143 * 144 * @type { ?string } 145 * @syscap SystemCapability.Security.SecurityGuard 146 * @systemapi Hide this for inner system use. 147 * @since 12 148 */ 149 param?: string; 150 } 151 152 /** 153 * Definition callback of receiving the query data. 154 * 155 * @interface Querier 156 * @syscap SystemCapability.Security.SecurityGuard 157 * @systemapi Hide this for inner system use. 158 * @since 12 159 */ 160 interface Querier { 161 /** 162 * Triggered when data is returned. 163 * 164 * @type { function } 165 * @syscap SystemCapability.Security.SecurityGuard 166 * @systemapi Hide this for inner system use. 167 * @since 12 168 */ 169 onQuery: (events: Array<SecurityEvent>) => void; 170 171 /** 172 * Triggered when data is complete. 173 * 174 * @type { function } 175 * @syscap SystemCapability.Security.SecurityGuard 176 * @systemapi Hide this for inner system use. 177 * @since 12 178 */ 179 onComplete: () => void; 180 181 /** 182 * Triggered when error. 183 * 184 * @type { function } 185 * @syscap SystemCapability.Security.SecurityGuard 186 * @systemapi Hide this for inner system use. 187 * @since 12 188 */ 189 onError: (message: string) => void; 190 } 191 192 /** 193 * Query security event information from security guard. 194 * 195 * @permission ohos.permission.QUERY_SECURITY_EVENT 196 * @param { Array<SecurityEventRule> } rules - rule of get security event information. 197 * @param { Querier } querier - callback of receiving the query data. 198 * @throws { BusinessError } 201 - check permission fail. 199 * @throws { BusinessError } 202 - non-system application uses the system API. 200 * @throws { BusinessError } 401 - invalid parameters. 201 * Possible causes: 202 * 1. Mandatory parameters are left unspecified. 203 * 2. Incorrect parameter types. 204 * 3. Parameter verification failed. 205 * @syscap SystemCapability.Security.SecurityGuard 206 * @systemapi Hide this for inner system use. 207 * @since 12 208 */ 209 function querySecurityEvent(rules: Array<SecurityEventRule>, querier: Querier): void; 210 211 /** 212 * Provides the conditions of Collector. 213 * 214 * @typedef CollectorRule 215 * @syscap SystemCapability.Security.SecurityGuard 216 * @systemapi Hide this for inner system use. 217 * @since 12 218 */ 219 interface CollectorRule { 220 /** 221 * The event id 222 * 223 * @type { number } 224 * @syscap SystemCapability.Security.SecurityGuard 225 * @systemapi Hide this for inner system use. 226 * @since 12 227 */ 228 eventId: number; 229 230 /** 231 * The query condition. 232 * 233 * @type { ?string } 234 * @syscap SystemCapability.Security.SecurityGuard 235 * @systemapi Hide this for inner system use. 236 * @since 12 237 */ 238 param?: string; 239 } 240 241 /** 242 * start the collector to collect data 243 * 244 * @permission ohos.permission.QUERY_SECURITY_EVENT 245 * @param { CollectorRule } rule - rule of collect security event information. 246 * @throws { BusinessError } 201 - check permission fail. 247 * @throws { BusinessError } 202 - non-system application uses the system API. 248 * @throws { BusinessError } 401 - invalid parameters. 249 * Possible causes: 250 * 1. Mandatory parameters are left unspecified. 251 * 2. Incorrect parameter types. 252 * 3. Parameter verification failed. 253 * @syscap SystemCapability.Security.SecurityGuard 254 * @systemapi Hide this for inner system use. 255 * @since 12 256 */ 257 function startSecurityEventCollector(rule: CollectorRule): void; 258 259 /** 260 * stop the collector. 261 * 262 * @permission ohos.permission.QUERY_SECURITY_EVENT 263 * @param { CollectorRule } rule - rule of collect security event information. 264 * @throws { BusinessError } 201 - check permission fail. 265 * @throws { BusinessError } 202 - non-system application uses the system API. 266 * @throws { BusinessError } 401 - invalid parameters. 267 * Possible causes: 268 * 1. Mandatory parameters are left unspecified. 269 * 2. Incorrect parameter types. 270 * 3. Parameter verification failed. 271 * @syscap SystemCapability.Security.SecurityGuard 272 * @systemapi Hide this for inner system use. 273 * @since 12 274 */ 275 function stopSecurityEventCollector(rule: CollectorRule): void; 276 277 /** 278 * Provides the ModelRule type. 279 * 280 * @typedef ModelRule 281 * @syscap SystemCapability.Security.SecurityGuard 282 * @systemapi Hide this for inner system use. 283 * @since 12 284 */ 285 interface ModelRule { 286 /** 287 * The security model rule 288 * 289 * @type { string } 290 * @syscap SystemCapability.Security.SecurityGuard 291 * @systemapi Hide this for inner system use. 292 * @since 12 293 */ 294 modelName: string; 295 296 /** 297 * The model param. 298 * 299 * @type { ?string } 300 * @syscap SystemCapability.Security.SecurityGuard 301 * @systemapi Hide this for inner system use. 302 * @since 12 303 */ 304 param?: string 305 } 306 307 /** 308 * Provides the ModelResult type. 309 * 310 * @typedef ModelResult 311 * @syscap SystemCapability.Security.SecurityGuard 312 * @systemapi Hide this for inner system use. 313 * @since 12 314 */ 315 interface ModelResult { 316 /** 317 * The result of security model. 318 * 319 * @type { string } 320 * @syscap SystemCapability.Security.SecurityGuard 321 * @systemapi Hide this for inner system use. 322 * @since 12 323 */ 324 result: string; 325 } 326 327 /** 328 * Request security model result from security guard. 329 * 330 * @permission ohos.permission.QUERY_SECURITY_MODEL_RESULT 331 * @param { ModelRule } rule - indicates the security model rule. 332 * @returns { Promise<ModelResult> } model Results with Promises. 333 * @throws { BusinessError } 201 - check permission fail. 334 * @throws { BusinessError } 202 - non-system application uses the system API. 335 * @throws { BusinessError } 401 - invalid parameters. 336 * Possible causes: 337 * 1. Mandatory parameters are left unspecified. 338 * 2. Incorrect parameter types. 339 * 3. Parameter verification failed. 340 * @syscap SystemCapability.Security.SecurityGuard 341 * @systemapi Hide this for inner system use. 342 * @since 12 343 */ 344 function getModelResult(rule: ModelRule): Promise<ModelResult>; 345 346 /** 347 * Provides the conditions of on/off. 348 * 349 * @interface SecurityEventInfo 350 * @syscap SystemCapability.Security.SecurityGuard 351 * @systemapi Hide this for inner system use. 352 * @since 12 353 */ 354 interface SecurityEventInfo { 355 /** 356 * The security event id. 357 * 358 * @type { number } 359 * @syscap SystemCapability.Security.SecurityGuard 360 * @systemapi Hide this for inner system use. 361 * @since 12 362 */ 363 eventId: number; 364 } 365 366 /** 367 * Subscribe the security event. 368 * 369 * @permission ohos.permission.QUERY_SECURITY_EVENT 370 * @param {'securityEventOccur'} type 371 * @param { SecurityEventInfo } securityEventInfo - Indicates the subscribed event information. 372 * @param { Callback<SecurityEvent> } callback - Indicates the listener when the security event occurs. 373 * @throws { BusinessError } 201 - check permission fail. 374 * @throws { BusinessError } 202 - non-system application uses the system API. 375 * @throws { BusinessError } 401 - invalid parameters. 376 * Possible causes: 377 * 1. Mandatory parameters are left unspecified. 378 * 2. Incorrect parameter types. 379 * 3. Parameter verification failed. 380 * @syscap SystemCapability.Security.SecurityGuard 381 * @systemapi Hide this for inner system use. 382 * @since 12 383 */ 384 function on(type: 'securityEventOccur', securityEventInfo: SecurityEventInfo, callback: Callback<SecurityEvent>): void; 385 386 /** 387 * Unsubscribe the security event. 388 * 389 * @permission ohos.permission.QUERY_SECURITY_EVENT 390 * @param {'securityEventOccur'} type 391 * @param { SecurityEventInfo } securityEventInfo - Indicates the subscribed event information. 392 * @param { Callback<SecurityEvent> } callback - Indicates the listener when the security event occurs. 393 * @throws { BusinessError } 201 - check permission fail. 394 * @throws { BusinessError } 202 - non-system application uses the system API. 395 * @throws { BusinessError } 401 - invalid parameters. 396 * Possible causes: 397 * 1. Mandatory parameters are left unspecified. 398 * 2. Incorrect parameter types. 399 * 3. Parameter verification failed. 400 * @syscap SystemCapability.Security.SecurityGuard 401 * @systemapi Hide this for inner system use. 402 * @since 12 403 */ 404 function off(type: 'securityEventOccur', securityEventInfo: SecurityEventInfo, callback?: Callback<SecurityEvent>): void; 405 406 /** 407 * Provides policy file information. 408 * 409 * @interface PolicyFile 410 * @syscap SystemCapability.Security.SecurityGuard 411 * @systemapi Hide this for inner system use. 412 * @since 12 413 */ 414 interface PolicyFile { 415 /** 416 * The policy file name. 417 * 418 * @type { string } 419 * @syscap SystemCapability.Security.SecurityGuard 420 * @systemapi Hide this for inner system use. 421 * @since 12 422 */ 423 name: string; 424 425 /** 426 * The policy file descriptor. 427 * 428 * @type { number } 429 * @syscap SystemCapability.Security.SecurityGuard 430 * @systemapi Hide this for inner system use. 431 * @since 12 432 */ 433 fd: number; 434 } 435 436 /** 437 * Update the policy file. 438 * 439 * @permission ohos.permission.MANAGE_SECURITY_GUARD_CONFIG 440 * @param { PolicyFile } policyFile - Indicates the policy file information. 441 * @returns { Promise<void> } the promise returned by the function. 442 * @throws { BusinessError } 201 - check permission fail. 443 * @throws { BusinessError } 202 - non-system application uses the system API. 444 * @throws { BusinessError } 401 - invalid parameters. 445 * Possible causes: 446 * 1. Mandatory parameters are left unspecified. 447 * 2. Incorrect parameter types. 448 * 3. Parameter verification failed. 449 * @syscap SystemCapability.Security.SecurityGuard 450 * @systemapi Hide this for inner system use. 451 * @since 12 452 */ 453 function updatePolicyFile(policyFile: PolicyFile): Promise<void>; 454} 455 456export default securityGuard; 457