protection_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_PROTECTION_PROTECTION_ENGINE_H_
#define API_MIP_PROTECTION_PROTECTION_ENGINE_H_
 
#include <chrono>
#include <climits>
#include <memory>
#include <string>
#include <vector>
 
#include "mip/common_types.h"
#include "mip/error.h"
#include "mip/mip_export.h"
#include "mip/mip_namespace.h"
#include "mip/protection_descriptor.h"
#include "mip/protection/delegation_license.h"
#include "mip/protection/delegation_license_settings.h"
#include "mip/protection/get_template_settings.h"
#include "mip/protection/license_info.h"
#include "mip/protection/license_rights_data.h"
#include "mip/protection/protection_common_types.h"
#include "mip/protection/protection_handler.h"
#include "mip/protection/template_descriptor.h"
#include "mip/protection/tenant_information.h"
 
namespace {
 
const int kMinTemplateBatchNum = 1; // 1 template per request (many operations in parallel, small packets)
const int kMaxTemplateBatchNum = 25; // 25 templates per request (fewer operations in parallel, larger packets)
 
} //namespace
 
MIP_NAMESPACE_BEGIN
 
class ProtectionEngine {
public:
  class Observer {
  public:
    virtual void OnGetTemplatesSuccess(
        const std::vector<std::shared_ptr<TemplateDescriptor>>& templateDescriptors,
        const std::shared_ptr<void>& context) { UNUSED(templateDescriptors); UNUSED(context); }
 
    virtual void OnGetTemplatesFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
 
    virtual void OnGetRightsForLabelIdSuccess(
        const std::shared_ptr<std::vector<std::string>>& rights,
        const std::shared_ptr<void>& context) { UNUSED(rights); UNUSED(context); }
 
    virtual void OnGetRightsForLabelIdFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
    
    virtual void OnLoadUserCertSuccess(
        const std::shared_ptr<void>& context) { UNUSED(context); }
 
    virtual void OnLoadUserCertFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
 
    virtual void OnRegisterContentForTrackingAndRevocationSuccess(
        const std::shared_ptr<void>& context) { UNUSED(context); }
 
    virtual void OnRegisterContentForTrackingAndRevocationFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
 
    virtual void OnRevokeContentSuccess(
        const std::shared_ptr<void>& context) { UNUSED(context); }
 
    virtual void OnRevokeContentFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
 
    virtual void OnCreateDelegatedLicensesSuccess(
        std::vector<std::shared_ptr<DelegationLicense>> delegatedLicenses,
        const std::shared_ptr<void>& context) { UNUSED(delegatedLicenses); UNUSED(context); }
 
    virtual void OnCreateDelegatedLicensesFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
 
    virtual void OnGetTenantInformationAsyncSuccess(
        const std::shared_ptr<TenantInformation>& tenantInformation,
        const std::shared_ptr<void>& context) { UNUSED(tenantInformation); UNUSED(context); }
 
    virtual void OnGetTenantInformationAsyncFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
 
    virtual void OnGetLicenseRightsDataSuccess(
        const std::shared_ptr<LicenseRightsData>& licenseRightsData,
        const std::shared_ptr<void>& context) { UNUSED(licenseRightsData); UNUSED(context); }
 
    virtual void OnGetLicenseRightsDataFailure(
        const std::exception_ptr& error,
        const std::shared_ptr<void>& context) { UNUSED(error); UNUSED(context); }
    
    virtual ~Observer() { }
  protected:
    Observer() { }
  };
  
  class Settings {
  public:
    Settings(
        const Identity& identity,
        const std::shared_ptr<AuthDelegate>& authDelegate,
        const std::string& clientData,
        const std::string& locale = "")
        : mIdentity(identity),
          mAuthDelegate(authDelegate),
          mClientData(clientData),
          mLocale(locale),
          mAllowCloudServiceOnly(false),
          mTemplateRefreshRate(std::chrono::hours::zero()),
          mTemplateBatchSize(kMaxTemplateBatchNum) {
      if (mLocale.compare("") == 0) {
        mLocale = "en-US";
      }
    }
 
    Settings(
        const std::string& engineId,
        const std::shared_ptr<AuthDelegate>& authDelegate,
        const std::string& clientData,
        const std::string& locale = "")
        : mEngineId(engineId),
          mAuthDelegate(authDelegate),
          mClientData(clientData),
          mLocale(locale),
          mAllowCloudServiceOnly(false),
          mTemplateRefreshRate(std::chrono::hours::zero()),
          mTemplateBatchSize(kMaxTemplateBatchNum) {
      if (mLocale.compare("") == 0) {
        mLocale = "en-US";
      }
    }
 
    const std::string& GetEngineId() const { return mEngineId; }
 
    void SetEngineId(const std::string& engineId) { mEngineId = engineId; }
 
    const Identity& GetIdentity() const { return mIdentity; }
 
    void SetIdentity(const Identity& identity) { mIdentity = identity; }
 
    const std::string& GetClientData() const { return mClientData; }
 
    void SetClientData(const std::string& clientData) { mClientData = clientData; }
 
    const std::string& GetLocale() const { return mLocale; }
 
    void SetCustomSettings(const std::vector<std::pair<std::string, std::string>>& value) { mCustomSettings = value; }
 
    const std::vector<std::pair<std::string, std::string>>& GetCustomSettings() const { return mCustomSettings; }
 
    void SetSessionId(const std::string& sessionId) {
      mSessionId = sessionId;
    }
 
    const std::string& GetSessionId() const {
      return mSessionId;
    }
 
    void SetCloud(Cloud cloud) {
      mCloud = cloud;
    }
 
    Cloud GetCloud() const {
      return mCloud;
    }
 
    void SetDataBoundary(DataBoundary dataBoundary) {
      mDataBoundary = dataBoundary;
    }
 
    DataBoundary GetDataBoundary() const {
      return mDataBoundary;
    }
 
    void SetCloudEndpointBaseUrl(const std::string& cloudEndpointBaseUrl) {
      mCloudEndpointBaseUrl = cloudEndpointBaseUrl;
    }
 
    const std::string& GetCloudEndpointBaseUrl() const {
      return mCloudEndpointBaseUrl;
    }
 
    void SetAuthDelegate(const std::shared_ptr<AuthDelegate>& authDelegate) { 
      mAuthDelegate = authDelegate; 
    }
 
    std::shared_ptr<AuthDelegate> GetAuthDelegate() const { return mAuthDelegate; }
 
    const std::string& GetUnderlyingApplicationId() const { return mUnderlyingApplicationId; }
 
    void SetUnderlyingApplicationId(const std::string& underlyingApplicationId) { mUnderlyingApplicationId = underlyingApplicationId; }
 
    bool GetAllowCloudServiceOnly() const { return mAllowCloudServiceOnly; }
 
    void SetAllowCloudServiceOnly(bool allowCloudServiceOnly) { mAllowCloudServiceOnly = allowCloudServiceOnly; }
 
    std::chrono::hours GetTemplateRefreshInterval() const { return mTemplateRefreshRate; }
 
    int GetTemplateBatchSize() const { return mTemplateBatchSize; }
 
    void SetTemplateRefreshArgs(std::chrono::hours templateRefreshRateHours, int templateBatchSize = kMaxTemplateBatchNum) {
      if (templateRefreshRateHours < std::chrono::hours::zero()) {
        throw BadInputError("Template refresh interval is outside acceptable range.");
      }
      mTemplateRefreshRate = templateRefreshRateHours;
 
      if (templateBatchSize < kMinTemplateBatchNum || templateBatchSize > kMaxTemplateBatchNum) {
        throw BadInputError("Template batch size is outside acceptable range.");
      }
      mTemplateBatchSize = templateBatchSize;
    }
 
    MIP_API void AddRmsCapability(const std::string& capability);
 
    MIP_API bool RemoveRmsCapability(const std::string& capability);
 
    std::vector<std::string> GetRmsCapabilities() const { return mCapabilities; }
 
#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
    const std::shared_ptr<void>& GetLoggerContext() const { return mLoggerContext; }
#endif
 
    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<std::string> mCapabilities;
    std::string mCloudEndpointBaseUrl;
    std::string mLocale;
    std::string mSessionId;
    std::string mUnderlyingApplicationId;
    bool mAllowCloudServiceOnly;
    std::chrono::hours mTemplateRefreshRate;
    int mTemplateBatchSize;
    std::shared_ptr<void> mLoggerContext;
  };
 
  virtual const Settings& GetSettings() const = 0;
 
  virtual std::shared_ptr<AsyncControl> GetTemplatesAsync(
      const std::shared_ptr<ProtectionEngine::Observer>& observer,
      const std::shared_ptr<void>& context,
      const std::shared_ptr<const GetTemplatesSettings>& templateSettings) = 0;
 
  virtual std::shared_ptr<AsyncControl> GetTemplatesAsync(
      const std::shared_ptr<ProtectionEngine::Observer>& observer,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::vector<std::shared_ptr<TemplateDescriptor>> GetTemplates(
      const std::shared_ptr<void>& context,
      const std::shared_ptr<const GetTemplatesSettings>& templateSettings) = 0;
 
  virtual std::vector<std::shared_ptr<TemplateDescriptor>> GetTemplates(const std::shared_ptr<void>& context) = 0;
  
  virtual bool IsFeatureSupported(FeatureId featureId) = 0;
 
  virtual std::shared_ptr<AsyncControl> GetRightsForLabelIdAsync(
      const std::string& documentId,
      const std::string& labelId,
      const std::string& ownerEmail,
      const std::string& delegatedUserEmail,
      const std::shared_ptr<ProtectionEngine::Observer>& observer,
      const std::shared_ptr<void>& context,
      const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::vector<std::string> GetRightsForLabelId(
      const std::string& documentId,
      const std::string& labelId,
      const std::string& ownerEmail,
      const std::string& delegatedUserEmail,
      const std::shared_ptr<void>& context,
      const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::shared_ptr<mip::LicenseInfo> GetLicenseInfoForLabelId(
      const std::string& documentId,
      const std::string& labelId,
      const std::string& ownerEmail,
      const std::string& delegatedUserEmail,
      const std::shared_ptr<void>& context,
      const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::shared_ptr<AsyncControl> CreateProtectionHandlerForPublishingAsync(
      const ProtectionHandler::PublishingSettings& settings,
      const std::shared_ptr<ProtectionHandler::Observer>& observer,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<ProtectionHandler> CreateProtectionHandlerForPublishing(
      const ProtectionHandler::PublishingSettings& settings,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<AsyncControl> CreateProtectionHandlerForConsumptionAsync(
      const ProtectionHandler::ConsumptionSettings& settings,
      const std::shared_ptr<ProtectionHandler::Observer>& observer,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<ProtectionHandler> CreateProtectionHandlerForConsumption(
      const ProtectionHandler::ConsumptionSettings& settings,
      const std::shared_ptr<void>& context) = 0;
 
#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
  [[deprecated("ProtectionEngine::LoadUserCert is deprecated, use ProtectionEngine::LoadUserCertSync")]]
#endif
  virtual bool LoadUserCert(
      const std::shared_ptr<void>& context,
      const ProtectionCommonSettings& settings = ProtectionCommonSettings()) {
    try {
      LoadUserCertSync(context, settings);
    } catch (...) {
      return false;
    }
    return true;
  }
 
  virtual void LoadUserCertSync(
      const std::shared_ptr<void>& context,
      const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::shared_ptr<AsyncControl> LoadUserCertAsync(
      const std::shared_ptr<ProtectionEngine::Observer>& observer,
      const std::shared_ptr<void>& context,
      const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual void RegisterContentForTrackingAndRevocation(
    const std::vector<uint8_t>& serializedPublishingLicense,
    const std::string& contentName,
    bool isOwnerNotificationEnabled,
    const std::shared_ptr<void>& context,
    const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::shared_ptr<AsyncControl> RegisterContentForTrackingAndRevocationAsync(
    const std::vector<uint8_t>& serializedPublishingLicense,
    const std::string& contentName,
    bool isOwnerNotificationEnabled,
    const std::shared_ptr<ProtectionEngine::Observer>& observer,
    const std::shared_ptr<void>& context,
    const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual void RevokeContent(
    const std::vector<uint8_t>& serializedPublishingLicense,
    const std::shared_ptr<void>& context,
    const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::shared_ptr<AsyncControl> RevokeContentAsync(
    const std::vector<uint8_t>& serializedPublishingLicense,
    const std::shared_ptr<ProtectionEngine::Observer>& observer,
    const std::shared_ptr<void>& context,
    const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::vector<std::shared_ptr<DelegationLicense>> CreateDelegationLicenses(
      const DelegationLicenseSettings& settings,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<AsyncControl> CreateDelegationLicensesAsync(
      const DelegationLicenseSettings& settings,
      const std::shared_ptr<ProtectionEngine::Observer>& observer,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<TenantInformation> GetTenantInformation(
      const ProtectionCommonSettings& settings,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<AsyncControl> GetTenantInformationAsync(
      const ProtectionCommonSettings& settings,
      const std::shared_ptr<ProtectionEngine::Observer>& observer,
      const std::shared_ptr<void>& context) = 0;
 
  virtual std::shared_ptr<LicenseRightsData> GetLicenseRightsData(
    const std::vector<uint8_t>& serializedPublishingLicense,
    const std::shared_ptr<void>& context,
    const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual std::shared_ptr<AsyncControl> GetLicenseRightsDataAsync(
    const std::vector<uint8_t>& serializedPublishingLicense,
    const std::shared_ptr<ProtectionEngine::Observer>& observer,
    const std::shared_ptr<void>& context,
    const ProtectionCommonSettings& settings = ProtectionCommonSettings()) = 0;
 
  virtual ~ProtectionEngine() {}
protected:
  ProtectionEngine() {}
};
 
MIP_NAMESPACE_END
 
#endif // API_MIP_PROTECTION_PROTECTION_ENGINE_H_