xref: /interface/sdk-js/api/@ohos.security.securityGuard.d.ts

/*
 * Copyright (c) 2023 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file This module provides the capabilities to security guard.
 * @kit SecurityGuardKit
 */

import type { Callback } from '@ohos.base';

/**
 * Provides security event management and security model management.
 * Based on event information, you will be able to analyze the running status of devices.
 *
 * @namespace securityGuard
 * @syscap SystemCapability.Security.SecurityGuard
 * @systemapi Hide this for inner system use.
 * @since 12
 */
declare namespace securityGuard {

  /**
   * Provides the SecurityEvent type, including the event id, version info, report content.
   *
   * @typedef SecurityEvent
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface SecurityEvent {
    /**
     * The event id
     *
     * @type { number }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    eventId: number;

    /**
     * The version of a security event. Different versions indicate different data formats.
     *
     * @type { string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    version: string;

    /**
     * The report content
     *
     * @type { string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    content: string;

    /**
     * The event timestamp, format is YYYYMMDDHHMMSS.
     *
     * @type { ?string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    timestamp?: string;
  }

  /**
   * Report security information to the security guard.
   *
   * @permission ohos.permission.REPORT_SECURITY_EVENT
   * @param { SecurityEvent } securityEvent - indicates the information to be reported.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function reportSecurityEvent(securityEvent: SecurityEvent): void;

  /**
   * Provides the conditions of querySecurityEvent.
   *
   * @interface SecurityEventRule
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface SecurityEventRule {
    /**
     * The security event ids.
     *
     * @type { number }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    eventId: number;
    
    /**
     * The begin time, format is YYYYMMDDHHMMSS.
     *
     * @type { ?string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    beginTime?: string;

    /**
     * The end time, format is YYYYMMDDHHMMSS.
     *
     * @type { ?string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    endTime?: string;

    /**
     * The query condition.
     *
     * @type { ?string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    param?: string;
  }

  /**
   * Definition callback of receiving the query data.
   *
   * @interface Querier
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface Querier {
    /**
     * Triggered when data is returned.
     *
     * @type { function }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    onQuery: (events: Array<SecurityEvent>) => void;

    /**
     * Triggered when data is complete.
     *
     * @type { function }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    onComplete: () => void;

    /**
     * Triggered when error.
     *
     * @type { function }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    onError: (message: string) => void;
  }

  /**
   * Query security event information from security guard.
   *
   * @permission ohos.permission.QUERY_SECURITY_EVENT
   * @param { Array<SecurityEventRule> } rules - rule of get security event information.
   * @param { Querier } querier - callback of receiving the query data.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function querySecurityEvent(rules: Array<SecurityEventRule>, querier: Querier): void;

  /**
   * Provides the conditions of Collector.
   *
   * @typedef CollectorRule
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface CollectorRule {
    /**
     * The event id
     *
     * @type { number }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    eventId: number;

    /**
     * The query condition.
     *
     * @type { ?string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    param?: string;
  }

  /**
   * start the collector to collect data
   *
   * @permission ohos.permission.QUERY_SECURITY_EVENT
   * @param { CollectorRule } rule - rule of collect security event information.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function startSecurityEventCollector(rule: CollectorRule): void;

  /**
   * stop the collector.
   *
   * @permission ohos.permission.QUERY_SECURITY_EVENT
   * @param { CollectorRule } rule - rule of collect security event information.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function stopSecurityEventCollector(rule: CollectorRule): void;

  /**
   * Provides the ModelRule type.
   *
   * @typedef ModelRule
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface ModelRule {
    /**
     * The security model rule
     *
     * @type { string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    modelName: string;

    /**
     * The model param.
     *
     * @type { ?string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    param?: string
  }

  /**
   * Provides the ModelResult type.
   *
   * @typedef ModelResult
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface ModelResult {
    /**
     * The result of security model.
     *
     * @type { string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    result: string;
  }

  /**
   * Request security model result from security guard.
   *
   * @permission ohos.permission.QUERY_SECURITY_MODEL_RESULT
   * @param { ModelRule } rule -  indicates the security model rule.
   * @returns { Promise<ModelResult> } model Results with Promises.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function getModelResult(rule: ModelRule): Promise<ModelResult>;

  /**
   * Provides the conditions of on/off.
   *
   * @interface SecurityEventInfo
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface SecurityEventInfo {
    /**
     * The security event id.
     *
     * @type { number }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    eventId: number;
  }

  /**
   * Subscribe the security event.
   *
   * @permission ohos.permission.QUERY_SECURITY_EVENT
   * @param {'securityEventOccur'} type
   * @param { SecurityEventInfo } securityEventInfo - Indicates the subscribed event information.
   * @param { Callback<SecurityEvent> } callback - Indicates the listener when the security event occurs.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function on(type: 'securityEventOccur', securityEventInfo: SecurityEventInfo, callback: Callback<SecurityEvent>): void;

  /**
   * Unsubscribe the security event.
   *
   * @permission ohos.permission.QUERY_SECURITY_EVENT
   * @param {'securityEventOccur'} type
   * @param { SecurityEventInfo } securityEventInfo - Indicates the subscribed event information.
   * @param { Callback<SecurityEvent> } callback - Indicates the listener when the security event occurs.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function off(type: 'securityEventOccur', securityEventInfo: SecurityEventInfo, callback?: Callback<SecurityEvent>): void;

  /**
   * Provides policy file information.
   *
   * @interface PolicyFile
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  interface PolicyFile {
    /**
     * The policy file name.
     *
     * @type { string }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    name: string;

    /**
     * The policy file descriptor.
     *
     * @type { number }
     * @syscap SystemCapability.Security.SecurityGuard
     * @systemapi Hide this for inner system use.
     * @since 12
     */
    fd: number;
  }

  /**
   * Update the policy file.
   *
   * @permission ohos.permission.MANAGE_SECURITY_GUARD_CONFIG
   * @param { PolicyFile } policyFile - Indicates the policy file information.
   * @returns { Promise<void> } the promise returned by the function.
   * @throws { BusinessError } 201 - check permission fail.
   * @throws { BusinessError } 202 - non-system application uses the system API.
   * @throws { BusinessError } 401 - invalid parameters. 
   * Possible causes: 
   *   1. Mandatory parameters are left unspecified. 
   *   2. Incorrect parameter types. 
   *   3. Parameter verification failed.
   * @syscap SystemCapability.Security.SecurityGuard
   * @systemapi Hide this for inner system use.
   * @since 12
   */
  function updatePolicyFile(policyFile: PolicyFile): Promise<void>;
}

export default securityGuard;