file_engine.h

Go to the documentation of this file.

/*
 *
 * Copyright (c) Microsoft Corporation.
 * All rights reserved.
 *
 * This code is licensed under the MIT License.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files(the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions :
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 *
 */
 
#ifndef API_MIP_FILE_FILE_ENGINE_H_
#define API_MIP_FILE_FILE_ENGINE_H_
 
#include <memory>
#include <string>
#include <utility>
#include <vector>
 
#include "mip/common_types.h"
#include "mip/error.h"
#include "mip/file/file_execution_state.h"
#include "mip/file/file_handler.h"
#include "mip/mip_namespace.h"
#include "mip/upe/execution_state.h"
#include "mip/upe/label.h"
#include "mip/upe/sensitivity_types_rule_package.h"
 
MIP_NAMESPACE_BEGIN
 
/**
 * @brief This class provides an interface for all  engine functions.
 */
class FileEngine {
public:
 
  class Settings {
  public:
    /**
     * @brief FileEngine::Settings constructor for loading an existing engine.
     * 
     * @param engineId Set it to the unique engine ID generated by AddEngineAsync.
     * @param authDelegate The authentication delegate used by the SDK to acquire authentication tokens, will override the 
     * PolicyProfile::Settings::authDelegate if both provided
     * @param clientData customizable client data that can be stored with the engine when unloaded, can be retrieved from
     * a loaded engine.
     * @param locale engine localizable output will be provided in this locale.
     * @param loadSensitivityTypes Optional flag indicating when the engine is loaded should load also custom sensitivity types, 
     * if true OnPolicyChange Observer on the profile will be invoked on updates to custom sensitivity types as well as policy changes.
     * if false ListSensitivityTypes call will always return an empty list.
     */
    Settings(
        const std::string& engineId,
        const std::shared_ptr<AuthDelegate>& authDelegate,
        const std::string& clientData,
        const std::string& locale = "",
        bool loadSensitivityTypes = false)
        : mEngineId(engineId),
          mAuthDelegate(authDelegate),
          mClientData(clientData),
          mLocale(locale),
          mIsLoadSensitivityTypesEnabled(loadSensitivityTypes) {
      if (mLocale.compare("") == 0) {
        mLocale = "en-US";
      }
    }
 
    /**
     * @brief FileProfile::Settings constructor for creating a new engine.
     * 
     * @param identity Identity info of the user associated with the new engine.
     * @param authDelegate The authentication delegate used by the SDK to acquire authentication tokens, will override the 
     * PolicyProfile::Settings::authDelegate if both provided
     * @param clientData customizable client data that can be stored with the engine when unloaded, can be retrieved from
     * a loaded engine.
     * @param locale engine localizable output will be provided in this locale.
     * @param loadSensitivityTypes Optional flag indicating when the engine is loaded should load also custom sensitivity types, 
     * if true OnPolicyChange Observer on the profile will be invoked on updates to custom sensitivity types as well as policy changes.
     * if false ListSensitivityTypes call will always return an empty list.
     */
    Settings(
        const Identity& identity,
        const std::shared_ptr<AuthDelegate>& authDelegate,
        const std::string& clientData,
        const std::string& locale = "",
        bool loadSensitivityTypes = false)
        : mIdentity(identity),
          mAuthDelegate(authDelegate),
          mClientData(clientData),
          mLocale(locale) ,
          mIsLoadSensitivityTypesEnabled(loadSensitivityTypes) {
      if (mLocale.compare("") == 0) {
        mLocale = "en-US";
      }
    }
 
    /**
     * @brief Returns the engine ID.
     */
    const std::string& GetEngineId() const { return mEngineId; }
 
    /**
     * @brief Set the engine ID.
     * 
     * @param id engine ID.
     */
    void SetEngineId(const std::string& id) { mEngineId = id; }
 
    /**
     * @brief Returns the engine Identity.
     */
    const Identity& GetIdentity() const { return mIdentity; }
 
    /**
     * @brief Sets the engine identity.
     */
    void SetIdentity(const Identity& identity) { mIdentity = identity; }
 
    /**
     * @brief Returns the engine client data.
     */
    const std::string& GetClientData() const { return mClientData; }
 
    /**
     * @brief Return the engine locale.
     */
    const std::string& GetLocale() const { return mLocale; }
 
    /**
     * @brief Sets a list of name/value pairs used for testing and experimentation.
     */
    void SetCustomSettings(const std::vector<std::pair<std::string, std::string>>& value) { mCustomSettings = value; }
 
    /**
     * @brief Gets a list of name/value pairs used for testing and experimentation.
     */
    const std::vector<std::pair<std::string, std::string>>& GetCustomSettings() const { return mCustomSettings; }
 
    /**
    * @brief Sets the engine session ID.
    */
    void SetSessionId(const std::string& sessionId) {
      mSessionId = sessionId;
    }
 
    /**
    * @brief Return the engine session ID.
    */
    const std::string& GetSessionId() const {
      return mSessionId;
    }
 
    /**
    * @brief Optionally sets the target cloud
    * 
    * @param cloud Cloud
    * 
    * @note If cloud is not specified, then it will default to global cloud.
    */
    void SetCloud(Cloud cloud) {
      mCloud = cloud;
    }
 
    /**
    * @brief Gets the target cloud used by all service requests
    * 
    * @return cloud
    */
    Cloud GetCloud() const {
      return mCloud;
    }
 
    /**
    * @brief Optionally sets the target diagnostic region
    * 
    * @param dataBoundary Data boundary region
    * 
    * @note If dataBoundary is not specified, then it will default to global diagnostic region.
    */
    void SetDataBoundary(DataBoundary dataBoundary) {
      mDataBoundary = dataBoundary;
    }
 
    /**
    * @brief Gets the data boundary region
    * 
    * @return DataBoundary
    */
    DataBoundary GetDataBoundary() const {
      return mDataBoundary;
    }
  
    /**
    * @brief Sets the protection cloud endpoint base URL for custom cloud
    *
    * @param protectionCloudEndpointBaseUrl Base url associated with protection endpoints
    * 
    * @note This value will only be read and must be set for Cloud = Custom
    */
    void SetProtectionCloudEndpointBaseUrl(const std::string& protectionCloudEndpointBaseUrl) {
      mProtectionCloudEndpointBaseUrl = protectionCloudEndpointBaseUrl;
    }
 
    /**
    * @brief Gets the protection cloud endpoint base url
    *
    * @return Base url associated with protection endpoints
    * 
    * @note This value will only be read and must be set for Cloud = Custom
    */
    const std::string& GetProtectionCloudEndpointBaseUrl() const {
      return mProtectionCloudEndpointBaseUrl;
    }
 
    /**
    * @brief Sets the policy cloud endpoint base URL for custom cloud
    *
    * @param policyCloudEndpointBaseUrl Base url associated with policy endpoints
    */
    void SetPolicyCloudEndpointBaseUrl(const std::string& policyCloudEndpointBaseUrl) {
      mPolicyCloudEndpointBaseUrl = policyCloudEndpointBaseUrl;
    }
 
    /**
    * @brief Gets the policy cloud endpoint base url
    *
    * @return Base url associated with policy endpoints
    */
    const std::string& GetPolicyCloudEndpointBaseUrl() const {
      return mPolicyCloudEndpointBaseUrl;
    }
 
    /**
    * @brief Sets protection only engine indicator - no policy/label.
    */
    void SetProtectionOnlyEngine(bool protectionOnly) {
      mProtectionOnlyEngine = protectionOnly;
    }
 
    /**
    * @brief Return protection only engine indicator - no policy/label.
    */
    const bool IsProtectionOnlyEngine() const {
      return mProtectionOnlyEngine;
    }
 
    /**
     * @brief Get the the flag indicating if load sensitivity labels is enabled
     *
     * @return true if enabled else false.
     */
    bool IsLoadSensitivityTypesEnabled() const {
      return mIsLoadSensitivityTypesEnabled;
    }
 
     /**
     * @brief Sets the flag indicating if produce PFiles
     */
    void EnablePFile(bool value) {
      mEnablePFile = value;
    }
 
    /**
     * @brief Get the flag indicating if produce PFiles
     *
     * @return true if enabled else false.
     */
    const bool IsPFileEnabled() {
      return mEnablePFile;
    }
 
    /**
     * @brief Sets the delegated user
     *
     * @param delegatedUserEmail the delegation email.
     * 
     * @note A delegated user is specified when the authenticating user/application is acting on behalf of another user
     */
    void SetDelegatedUserEmail(const std::string& delegatedUserEmail) { mDelegatedUserEmail = delegatedUserEmail; }
 
    /**
     * @brief Gets the delegated user
     * 
     * @return Delegated user
     * 
     * @note A delegated user is specified when the authenticating user/application is acting on behalf of another user
     */
    const std::string& GetDelegatedUserEmail() const { return mDelegatedUserEmail; }
    
    /**
     * @brief Sets the label filter
     *
     * @param labelFilter the label filter.
     * 
     * @note Labels are by default filter to scope, this api is to allow filtering by possible actions.
     * @note If not set HyokProtection and DoubleKeyProtection are filtered.
     */
#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
    [[deprecated("SetLabelFilter is deprecated, use ConfigureFunctionality")]]
#endif
    void SetLabelFilter(const std::vector<LabelFilterType>& deprecatedLabelFilters) { mDeprecatedLabelFilters = deprecatedLabelFilters; }
 
    /**
     * @brief Gets the label filters set through deprecated function SetLabelFilter
     *
     * @return the label filter.
     * 
     * @note Labels are by default filter to scope, this api is to allow filtering by possible actions.
     */
    const std::vector<LabelFilterType>& GetLabelFilter() const { return mDeprecatedLabelFilters; }
 
    /**
     * @brief Enables or disables functionality
     *
     * @param functionalityFilterType the type of functionality.
     * @param enabled True to enable, false to disable
     * 
     * @note HyokProtection, DoubleKeyProtection, DoubleKeyUserDefinedProtection are disabled by default and must be enabled
     */
    void ConfigureFunctionality(FunctionalityFilterType functionalityFilterType, bool enabled) {
      if(functionalityFilterType == FunctionalityFilterType::None) {
        throw BadInputError(
            "FunctionalityFilterType::None is not supported");
      }
      
      mConfiguredFunctionality[functionalityFilterType] = enabled;
    }
 
    /**
     * @brief Gets the configured functionality
     *
     * @return A map of the types to a boolean value indicating whether or not it is enabled
     */
    const std::map<FunctionalityFilterType, bool>& GetConfiguredFunctionality() const {
        return mConfiguredFunctionality;
    }
 
    /**
     * @brief Set the Engine Auth Delegate.
     * 
     * @param authDelegate the Auth delegate
     */
    void SetAuthDelegate(const std::shared_ptr<AuthDelegate>& authDelegate) { 
      mAuthDelegate = authDelegate; 
    }
 
    /**
     * @brief Get the Engine Auth Delegate.
     * 
     * @return the Engine Auth Delegate. 
     */
    std::shared_ptr<AuthDelegate> GetAuthDelegate() const { return mAuthDelegate; }
 
#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
    /**
     * @brief Get logger context that will be opaquely passed to the logger delegate for logs associated with the created engine
     * 
     * @return The logger context
     */
    const std::shared_ptr<void>& GetLoggerContext() const { return mLoggerContext; }
#endif
    /**
     * @brief Sets the logger context that will be opaquely passed to the logger delegate for logs associated with the created engine
     * 
     * @param loggerContext The logger context
     * 
     */
    void SetLoggerContext(const std::shared_ptr<void>& loggerContext) {
      mLoggerContext = loggerContext;
    }
 
  private:
    std::string mEngineId;
    Identity mIdentity;
    Cloud mCloud = Cloud::Unknown;
    DataBoundary mDataBoundary = DataBoundary::Default;
    std::shared_ptr<AuthDelegate> mAuthDelegate;
    std::string mClientData;
    std::vector<std::pair<std::string, std::string>> mCustomSettings;
    std::vector<LabelFilterType> mDeprecatedLabelFilters;   
    std::map<FunctionalityFilterType, bool> mConfiguredFunctionality; 
    std::string mProtectionCloudEndpointBaseUrl;
    std::string mPolicyCloudEndpointBaseUrl;
    std::string mLocale;
    std::string mSessionId;
    bool mProtectionOnlyEngine = false;
    bool mIsLoadSensitivityTypesEnabled;
    bool mEnablePFile = true;
    std::string mDelegatedUserEmail;
    std::shared_ptr<void> mLoggerContext;
  };
 
  /** @cond DOXYGEN_HIDE */
  virtual ~FileEngine() {}
  /** @endcond */
 
  /**
   * @brief Returns the engine settings.
   */
  virtual const Settings& GetSettings() const = 0;
 
    /**
   * @brief list the sensitivity types associated with the policy engine.
   *
   * @return a list of sensitivity labels. empty if LoadSensitivityTypesEnabled was false (@see FileEngine::Settings).
   */
  virtual const std::vector<std::shared_ptr<SensitivityTypesRulePackage>>& ListSensitivityTypes() const = 0;
 
  /**
   * @brief Get the default sensitivity label. 
   * 
   * @return default sensitivity label if exists, nullptr if there is no default label set.
   */
  virtual const std::shared_ptr<Label> GetDefaultSensitivityLabel() const = 0;
 
  /**
   * @brief Gets the label according to the provided id.
   */
  virtual std::shared_ptr<Label> GetLabelById(const std::string& id) const = 0;
 
  /**
   * @brief Returns a list of sensitivity labels.
   */
  virtual const std::vector<std::shared_ptr<Label>> ListSensitivityLabels() = 0;
 
  /**
   * @brief Provide a url for looking up more information about the policy/labels.
   * 
   * @return a url in string format.
   */
  virtual const std::string& GetMoreInfoUrl() const = 0;
 
    /**
   * @brief Gets the policy file ID
   *
   * @return a string that represent the policy file ID
   */
  virtual const std::string& GetPolicyFileId() const = 0;
 
   /**
   * @brief Gets the sensitivity file ID
   *
   * @return a string that represent the policy file ID
   */
  virtual const std::string& GetSensitivityFileId() const = 0;
  
  /**
   * @brief Checks if the policy dictates that a document must be labeled.
   * 
   * @return true if labeling is mandatory, else false. 
   */
  virtual bool IsLabelingRequired() const = 0; 
 
  /**
   * @brief Gets the time when the policy was last fetched
   *
   * @return the time when the policy was last fetched
   */
  virtual std::chrono::time_point<std::chrono::system_clock> GetLastPolicyFetchTime() const = 0;
 
  /**
   * @brief Gets policy data XML which describes the settings, labels, and rules associated with this policy.
   * 
   * @return Policy data XML.
   */
  virtual const std::string& GetPolicyDataXml() const = 0;
 
  /**
   * @brief Starts creating a file handler for given file path.
   * 
   * @param inputFilePath The file to open. The path must include the file name and, if one exists, the file extension. 
   *        The file extension is used to determine the file format.
   * @param filePathForAuditReporting The actual (not temporary) file path, will be used for audit.
   * @param isAuditDiscoveryEnabled representing whether audit discovery is enabled or not.
   * @param fileHandlerObserver A class implementing the FileHandler::Observer interface.
   * @param context Client context that will be opaquely passed back to the observer.
   * @param isGetSensitivityLabelAuditDiscoveryEnabled representing whether audit discovery is triggered for getSensitivityLabel or not.
   * @return Async control object.
   */
  virtual std::shared_ptr<AsyncControl> CreateFileHandlerAsync(
      const std::string& inputFilePath,
      const std::string& filePathForAuditReporting,
      bool isAuditDiscoveryEnabled,
      const std::shared_ptr<FileHandler::Observer>& fileHandlerObserver,
      const std::shared_ptr<void>& context,
      const std::shared_ptr<FileExecutionState>& fileExecutionState = nullptr,
      bool isGetSensitivityLabelAuditDiscoveryEnabled = true) = 0;
 
  /**
   * @brief Starts creating a file handler for given file stream.
   * 
   * @param inputStream A stream containing the file data.
   * @param actualFilePath The path to the file. The path must include the file name and,
   *        if one exists, the file extension. The file extension will be used to determine the file format.
   *        Passing in the wrong file extension will cause unexpected behavior and possibly file corruption.
   *        The path will also use to identify the file in audit. 
   * @param isAuditDiscoveryEnabled representing whether audit discovery is enabled or not.
   * @param fileHandlerObserver A class implementing the FileHandler::Observer interface.
   * @param context Client context that will be opaquely passed back to the observer.
   * @param isGetSensitivityLabelAuditDiscoveryEnabled representing whether audit discovery is triggered for getSensitivityLabel or not.
   * @return Async control object.
   */
  virtual std::shared_ptr<AsyncControl> CreateFileHandlerAsync(
      const std::shared_ptr<Stream>& inputStream, 
      const std::string& actualFilePath,
      bool isAuditDiscoveryEnabled,
      const std::shared_ptr<FileHandler::Observer>& fileHandlerObserver, 
      const std::shared_ptr<void>& context,
      const std::shared_ptr<FileExecutionState>& fileExecutionState = nullptr,
      bool isGetSensitivityLabelAuditDiscoveryEnabled = true) = 0;
 
  /**
   * @brief Logs an application specific event to the audit pipeline
   *
   * @param level a description of the log level : Info/Error/Warning
   * @param eventType a description of the type of event
   * @param eventData the data associated with the event
   */
  virtual void SendApplicationAuditEvent(
      const std::string& level,
      const std::string& eventType,
      const std::string& eventData) = 0;
 
  /**
   * @brief Gets a list of custom settings.
   * 
   * @return a vector of custom settings
   */
  virtual const std::vector<std::pair<std::string, std::string>>& GetCustomSettings() const = 0;
 
  /**
   * @brief Gets if the policy has automatic or recommendation rules
   *
   * @return a bool that will tell if there any automatic or recommendation rules in
   *  the policy
   */
  virtual bool HasClassificationRules() const = 0;
  
  /**
   * @brief Checks if user has consented to specific workload, 
   *
   * @return bool indicating consent.
   */
  virtual bool HasWorkloadConsent(Workload workload) const = 0;
  
protected:
/** @cond DOXYGEN_HIDE */
  FileEngine() {}
  /** @endcond */
};
 
MIP_NAMESPACE_END
 
#endif  // API_MIP_FILE_FILE_ENGINE_H_