Microsoft Information Protection (MIP) SDK for C++: Reference 1.15
Doxygen-generated documentation for MIP SDK written in C++
Loading...
Searching...
No Matches
file_engine.h
Go to the documentation of this file.
1/*
2 *
3 * Copyright (c) Microsoft Corporation.
4 * All rights reserved.
5 *
6 * This code is licensed under the MIT License.
7 *
8 * Permission is hereby granted, free of charge, to any person obtaining a copy
9 * of this software and associated documentation files(the "Software"), to deal
10 * in the Software without restriction, including without limitation the rights
11 * to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
12 * copies of the Software, and to permit persons to whom the Software is
13 * furnished to do so, subject to the following conditions :
14 *
15 * The above copyright notice and this permission notice shall be included in
16 * all copies or substantial portions of the Software.
17 *
18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 * THE SOFTWARE.
25 *
26 */
27
28#ifndef API_MIP_FILE_FILE_ENGINE_H_
29#define API_MIP_FILE_FILE_ENGINE_H_
30
31#include <memory>
32#include <string>
33#include <utility>
34#include <vector>
35
36#include "mip/common_types.h"
37#include "mip/error.h"
40#include "mip/mip_namespace.h"
42#include "mip/upe/label.h"
44
45MIP_NAMESPACE_BEGIN
46
47/**
48 * @brief This class provides an interface for all engine functions.
49 */
50class FileEngine {
51public:
52
53 class Settings {
54 public:
55 /**
56 * @brief FileEngine::Settings constructor for loading an existing engine.
57 *
58 * @param engineId Set it to the unique engine ID generated by AddEngineAsync.
59 * @param authDelegate The authentication delegate used by the SDK to acquire authentication tokens, will override the
60 * PolicyProfile::Settings::authDelegate if both provided
61 * @param clientData customizable client data that can be stored with the engine when unloaded, can be retrieved from
62 * a loaded engine.
63 * @param locale engine localizable output will be provided in this locale.
64 * @param loadSensitivityTypes Optional flag indicating when the engine is loaded should load also custom sensitivity types,
65 * if true OnPolicyChange Observer on the profile will be invoked on updates to custom sensitivity types as well as policy changes.
66 * if false ListSensitivityTypes call will always return an empty list.
67 */
68 Settings(
69 const std::string& engineId,
70 const std::shared_ptr<AuthDelegate>& authDelegate,
71 const std::string& clientData,
72 const std::string& locale = "",
73 bool loadSensitivityTypes = false)
74 : mEngineId(engineId),
75 mAuthDelegate(authDelegate),
76 mClientData(clientData),
77 mLocale(locale),
78 mIsLoadSensitivityTypesEnabled(loadSensitivityTypes) {
79 if (mLocale.compare("") == 0) {
80 mLocale = "en-US";
81 }
82 }
83
84 /**
85 * @brief FileProfile::Settings constructor for creating a new engine.
86 *
87 * @param identity Identity info of the user associated with the new engine.
88 * @param authDelegate The authentication delegate used by the SDK to acquire authentication tokens, will override the
89 * PolicyProfile::Settings::authDelegate if both provided
90 * @param clientData customizable client data that can be stored with the engine when unloaded, can be retrieved from
91 * a loaded engine.
92 * @param locale engine localizable output will be provided in this locale.
93 * @param loadSensitivityTypes Optional flag indicating when the engine is loaded should load also custom sensitivity types,
94 * if true OnPolicyChange Observer on the profile will be invoked on updates to custom sensitivity types as well as policy changes.
95 * if false ListSensitivityTypes call will always return an empty list.
96 */
97 Settings(
98 const Identity& identity,
99 const std::shared_ptr<AuthDelegate>& authDelegate,
100 const std::string& clientData,
101 const std::string& locale = "",
102 bool loadSensitivityTypes = false)
103 : mIdentity(identity),
104 mAuthDelegate(authDelegate),
105 mClientData(clientData),
106 mLocale(locale) ,
107 mIsLoadSensitivityTypesEnabled(loadSensitivityTypes) {
108 if (mLocale.compare("") == 0) {
109 mLocale = "en-US";
110 }
111 }
112
113 /**
114 * @brief Returns the engine ID.
115 */
116 const std::string& GetEngineId() const { return mEngineId; }
117
118 /**
119 * @brief Set the engine ID.
120 *
121 * @param id engine ID.
122 */
123 void SetEngineId(const std::string& id) { mEngineId = id; }
124
125 /**
126 * @brief Returns the engine Identity.
127 */
128 const Identity& GetIdentity() const { return mIdentity; }
129
130 /**
131 * @brief Sets the engine identity.
132 */
133 void SetIdentity(const Identity& identity) { mIdentity = identity; }
134
135 /**
136 * @brief Returns the engine client data.
137 */
138 const std::string& GetClientData() const { return mClientData; }
139
140 /**
141 * @brief Return the engine locale.
142 */
143 const std::string& GetLocale() const { return mLocale; }
144
145 /**
146 * @brief Sets a list of name/value pairs used for testing and experimentation.
147 */
148 void SetCustomSettings(const std::vector<std::pair<std::string, std::string>>& value) { mCustomSettings = value; }
149
150 /**
151 * @brief Gets a list of name/value pairs used for testing and experimentation.
152 */
153 const std::vector<std::pair<std::string, std::string>>& GetCustomSettings() const { return mCustomSettings; }
154
155 /**
156 * @brief Sets the engine session ID.
157 */
158 void SetSessionId(const std::string& sessionId) {
159 mSessionId = sessionId;
160 }
161
162 /**
163 * @brief Return the engine session ID.
164 */
165 const std::string& GetSessionId() const {
166 return mSessionId;
167 }
168
169 /**
170 * @brief Optionally sets the target cloud
171 *
172 * @param cloud Cloud
173 *
174 * @note If cloud is not specified, then it will default to global cloud.
175 */
176 void SetCloud(Cloud cloud) {
177 mCloud = cloud;
178 }
179
180 /**
181 * @brief Gets the target cloud used by all service requests
182 *
183 * @return cloud
184 */
185 Cloud GetCloud() const {
186 return mCloud;
187 }
188
189 /**
190 * @brief Optionally sets the target diagnostic region
191 *
192 * @param dataBoundary Data boundary region
193 *
194 * @note If dataBoundary is not specified, then it will default to global diagnostic region.
195 */
196 void SetDataBoundary(DataBoundary dataBoundary) {
197 mDataBoundary = dataBoundary;
198 }
199
200 /**
201 * @brief Gets the data boundary region
202 *
203 * @return DataBoundary
204 */
205 DataBoundary GetDataBoundary() const {
206 return mDataBoundary;
207 }
208
209 /**
210 * @brief Sets the protection cloud endpoint base URL for custom cloud
211 *
212 * @param protectionCloudEndpointBaseUrl Base url associated with protection endpoints
213 *
214 * @note This value will only be read and must be set for Cloud = Custom
215 */
216 void SetProtectionCloudEndpointBaseUrl(const std::string& protectionCloudEndpointBaseUrl) {
217 mProtectionCloudEndpointBaseUrl = protectionCloudEndpointBaseUrl;
218 }
219
220 /**
221 * @brief Gets the protection cloud endpoint base url
222 *
223 * @return Base url associated with protection endpoints
224 *
225 * @note This value will only be read and must be set for Cloud = Custom
226 */
227 const std::string& GetProtectionCloudEndpointBaseUrl() const {
228 return mProtectionCloudEndpointBaseUrl;
229 }
230
231 /**
232 * @brief Sets the policy cloud endpoint base URL for custom cloud
233 *
234 * @param policyCloudEndpointBaseUrl Base url associated with policy endpoints
235 */
236 void SetPolicyCloudEndpointBaseUrl(const std::string& policyCloudEndpointBaseUrl) {
237 mPolicyCloudEndpointBaseUrl = policyCloudEndpointBaseUrl;
238 }
239
240 /**
241 * @brief Gets the policy cloud endpoint base url
242 *
243 * @return Base url associated with policy endpoints
244 */
245 const std::string& GetPolicyCloudEndpointBaseUrl() const {
246 return mPolicyCloudEndpointBaseUrl;
247 }
248
249 /**
250 * @brief Sets protection only engine indicator - no policy/label.
251 */
252 void SetProtectionOnlyEngine(bool protectionOnly) {
253 mProtectionOnlyEngine = protectionOnly;
254 }
255
256 /**
257 * @brief Return protection only engine indicator - no policy/label.
258 */
259 const bool IsProtectionOnlyEngine() const {
260 return mProtectionOnlyEngine;
261 }
262
263 /**
264 * @brief Get the the flag indicating if load sensitivity labels is enabled
265 *
266 * @return true if enabled else false.
267 */
268 bool IsLoadSensitivityTypesEnabled() const {
269 return mIsLoadSensitivityTypesEnabled;
270 }
271
272 /**
273 * @brief Sets the flag indicating if produce PFiles
274 */
275 void EnablePFile(bool value) {
276 mEnablePFile = value;
277 }
278
279 /**
280 * @brief Get the flag indicating if produce PFiles
281 *
282 * @return true if enabled else false.
283 */
284 const bool IsPFileEnabled() {
285 return mEnablePFile;
286 }
287
288 /**
289 * @brief Sets the delegated user
290 *
291 * @param delegatedUserEmail the delegation email.
292 *
293 * @note A delegated user is specified when the authenticating user/application is acting on behalf of another user
294 */
295 void SetDelegatedUserEmail(const std::string& delegatedUserEmail) { mDelegatedUserEmail = delegatedUserEmail; }
296
297 /**
298 * @brief Gets the delegated user
299 *
300 * @return Delegated user
301 *
302 * @note A delegated user is specified when the authenticating user/application is acting on behalf of another user
303 */
304 const std::string& GetDelegatedUserEmail() const { return mDelegatedUserEmail; }
305
306 /**
307 * @brief Sets the label filter
308 *
309 * @param labelFilter the label filter.
310 *
311 * @note Labels are by default filter to scope, this api is to allow filtering by possible actions.
312 * @note If not set HyokProtection and DoubleKeyProtection are filtered.
313 */
314#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
315 [[deprecated("SetLabelFilter is deprecated, use ConfigureFunctionality")]]
316#endif
317 void SetLabelFilter(const std::vector<LabelFilterType>& deprecatedLabelFilters) { mDeprecatedLabelFilters = deprecatedLabelFilters; }
318
319 /**
320 * @brief Gets the label filters set through deprecated function SetLabelFilter
321 *
322 * @return the label filter.
323 *
324 * @note Labels are by default filter to scope, this api is to allow filtering by possible actions.
325 */
326 const std::vector<LabelFilterType>& GetLabelFilter() const { return mDeprecatedLabelFilters; }
327
328 /**
329 * @brief Enables or disables functionality
330 *
331 * @param functionalityFilterType the type of functionality.
332 * @param enabled True to enable, false to disable
333 *
334 * @note HyokProtection, DoubleKeyProtection, DoubleKeyUserDefinedProtection are disabled by default and must be enabled
335 */
336 void ConfigureFunctionality(FunctionalityFilterType functionalityFilterType, bool enabled) {
337 if(functionalityFilterType == FunctionalityFilterType::None) {
338 throw BadInputError(
339 "FunctionalityFilterType::None is not supported");
340 }
341
342 mConfiguredFunctionality[functionalityFilterType] = enabled;
343 }
344
345 /**
346 * @brief Gets the configured functionality
347 *
348 * @return A map of the types to a boolean value indicating whether or not it is enabled
349 */
350 const std::map<FunctionalityFilterType, bool>& GetConfiguredFunctionality() const {
351 return mConfiguredFunctionality;
352 }
353
354 /**
355 * @brief Set the Engine Auth Delegate.
356 *
357 * @param authDelegate the Auth delegate
358 */
359 void SetAuthDelegate(const std::shared_ptr<AuthDelegate>& authDelegate) {
360 mAuthDelegate = authDelegate;
361 }
362
363 /**
364 * @brief Get the Engine Auth Delegate.
365 *
366 * @return the Engine Auth Delegate.
367 */
368 std::shared_ptr<AuthDelegate> GetAuthDelegate() const { return mAuthDelegate; }
369
370#if !defined(SWIG) && !defined(SWIG_DIRECTORS)
371 /**
372 * @brief Get logger context that will be opaquely passed to the logger delegate for logs associated with the created engine
373 *
374 * @return The logger context
375 */
376 const std::shared_ptr<void>& GetLoggerContext() const { return mLoggerContext; }
377#endif
378 /**
379 * @brief Sets the logger context that will be opaquely passed to the logger delegate for logs associated with the created engine
380 *
381 * @param loggerContext The logger context
382 *
383 */
384 void SetLoggerContext(const std::shared_ptr<void>& loggerContext) {
385 mLoggerContext = loggerContext;
386 }
387
388 private:
389 std::string mEngineId;
390 Identity mIdentity;
391 Cloud mCloud = Cloud::Unknown;
392 DataBoundary mDataBoundary = DataBoundary::Default;
393 std::shared_ptr<AuthDelegate> mAuthDelegate;
394 std::string mClientData;
395 std::vector<std::pair<std::string, std::string>> mCustomSettings;
396 std::vector<LabelFilterType> mDeprecatedLabelFilters; //Labels that the client does not want to view
397 std::map<FunctionalityFilterType, bool> mConfiguredFunctionality; //Functionality that has been turned on or off
398 std::string mProtectionCloudEndpointBaseUrl;
399 std::string mPolicyCloudEndpointBaseUrl;
400 std::string mLocale;
401 std::string mSessionId;
402 bool mProtectionOnlyEngine = false;
403 bool mIsLoadSensitivityTypesEnabled;
404 bool mEnablePFile = true;
405 std::string mDelegatedUserEmail;
406 std::shared_ptr<void> mLoggerContext;
407 };
408
409 /** @cond DOXYGEN_HIDE */
410 virtual ~FileEngine() {}
411 /** @endcond */
412
413 /**
414 * @brief Returns the engine settings.
415 */
416 virtual const Settings& GetSettings() const = 0;
417
418 /**
419 * @brief list the sensitivity types associated with the policy engine.
420 *
421 * @return a list of sensitivity labels. empty if LoadSensitivityTypesEnabled was false (@see FileEngine::Settings).
422 */
423 virtual const std::vector<std::shared_ptr<SensitivityTypesRulePackage>>& ListSensitivityTypes() const = 0;
424
425 /**
426 * @brief Get the default sensitivity label.
427 *
428 * @return default sensitivity label if exists, nullptr if there is no default label set.
429 */
430 virtual const std::shared_ptr<Label> GetDefaultSensitivityLabel() const = 0;
431
432 /**
433 * @brief Gets the label according to the provided id.
434 */
435 virtual std::shared_ptr<Label> GetLabelById(const std::string& id) const = 0;
436
437 /**
438 * @brief Returns a list of sensitivity labels.
439 */
440 virtual const std::vector<std::shared_ptr<Label>> ListSensitivityLabels() = 0;
441
442 /**
443 * @brief Provide a url for looking up more information about the policy/labels.
444 *
445 * @return a url in string format.
446 */
447 virtual const std::string& GetMoreInfoUrl() const = 0;
448
449 /**
450 * @brief Gets the policy file ID
451 *
452 * @return a string that represent the policy file ID
453 */
454 virtual const std::string& GetPolicyFileId() const = 0;
455
456 /**
457 * @brief Gets the sensitivity file ID
458 *
459 * @return a string that represent the policy file ID
460 */
461 virtual const std::string& GetSensitivityFileId() const = 0;
462
463 /**
464 * @brief Checks if the policy dictates that a document must be labeled.
465 *
466 * @return true if labeling is mandatory, else false.
467 */
468 virtual bool IsLabelingRequired() const = 0;
469
470 /**
471 * @brief Gets the time when the policy was last fetched
472 *
473 * @return the time when the policy was last fetched
474 */
475 virtual std::chrono::time_point<std::chrono::system_clock> GetLastPolicyFetchTime() const = 0;
476
477 /**
478 * @brief Gets policy data XML which describes the settings, labels, and rules associated with this policy.
479 *
480 * @return Policy data XML.
481 */
482 virtual const std::string& GetPolicyDataXml() const = 0;
483
484 /**
485 * @brief Starts creating a file handler for given file path.
486 *
487 * @param inputFilePath The file to open. The path must include the file name and, if one exists, the file extension.
488 * The file extension is used to determine the file format.
489 * @param filePathForAuditReporting The actual (not temporary) file path, will be used for audit.
490 * @param isAuditDiscoveryEnabled representing whether audit discovery is enabled or not.
491 * @param fileHandlerObserver A class implementing the FileHandler::Observer interface.
492 * @param context Client context that will be opaquely passed back to the observer.
493 * @param isGetSensitivityLabelAuditDiscoveryEnabled representing whether audit discovery is triggered for getSensitivityLabel or not.
494 * @return Async control object.
495 */
496 virtual std::shared_ptr<AsyncControl> CreateFileHandlerAsync(
497 const std::string& inputFilePath,
498 const std::string& filePathForAuditReporting,
499 bool isAuditDiscoveryEnabled,
500 const std::shared_ptr<FileHandler::Observer>& fileHandlerObserver,
501 const std::shared_ptr<void>& context,
502 const std::shared_ptr<FileExecutionState>& fileExecutionState = nullptr,
503 bool isGetSensitivityLabelAuditDiscoveryEnabled = true) = 0;
504
505 /**
506 * @brief Starts creating a file handler for given file stream.
507 *
508 * @param inputStream A stream containing the file data.
509 * @param actualFilePath The path to the file. The path must include the file name and,
510 * if one exists, the file extension. The file extension will be used to determine the file format.
511 * Passing in the wrong file extension will cause unexpected behavior and possibly file corruption.
512 * The path will also use to identify the file in audit.
513 * @param isAuditDiscoveryEnabled representing whether audit discovery is enabled or not.
514 * @param fileHandlerObserver A class implementing the FileHandler::Observer interface.
515 * @param context Client context that will be opaquely passed back to the observer.
516 * @param isGetSensitivityLabelAuditDiscoveryEnabled representing whether audit discovery is triggered for getSensitivityLabel or not.
517 * @return Async control object.
518 */
519 virtual std::shared_ptr<AsyncControl> CreateFileHandlerAsync(
520 const std::shared_ptr<Stream>& inputStream,
521 const std::string& actualFilePath,
522 bool isAuditDiscoveryEnabled,
523 const std::shared_ptr<FileHandler::Observer>& fileHandlerObserver,
524 const std::shared_ptr<void>& context,
525 const std::shared_ptr<FileExecutionState>& fileExecutionState = nullptr,
526 bool isGetSensitivityLabelAuditDiscoveryEnabled = true) = 0;
527
528 /**
529 * @brief Logs an application specific event to the audit pipeline
530 *
531 * @param level a description of the log level : Info/Error/Warning
532 * @param eventType a description of the type of event
533 * @param eventData the data associated with the event
534 */
535 virtual void SendApplicationAuditEvent(
536 const std::string& level,
537 const std::string& eventType,
538 const std::string& eventData) = 0;
539
540 /**
541 * @brief Gets a list of custom settings.
542 *
543 * @return a vector of custom settings
544 */
545 virtual const std::vector<std::pair<std::string, std::string>>& GetCustomSettings() const = 0;
546
547 /**
548 * @brief Gets if the policy has automatic or recommendation rules
549 *
550 * @return a bool that will tell if there any automatic or recommendation rules in
551 * the policy
552 */
553 virtual bool HasClassificationRules() const = 0;
554
555 /**
556 * @brief Checks if user has consented to specific workload,
557 *
558 * @return bool indicating consent.
559 */
560 virtual bool HasWorkloadConsent(Workload workload) const = 0;
561
562protected:
563/** @cond DOXYGEN_HIDE */
564 FileEngine() {}
565 /** @endcond */
566};
567
568MIP_NAMESPACE_END
569
570#endif // API_MIP_FILE_FILE_ENGINE_H_
Bad input error, thrown when the input to an SDK API is invalid.
Definition error.h:247
Abstraction for identity.
A file Containing the common types used by the upe, file and protection modules.
Cloud
Azure cloud identifier.
@ Unknown
Cloud not specified or URL not recognized as an Azure cloud.
Workload
The workload the application is working on, used primary to check for consent.
LabelFilterType
Label filter types, optional set of properties that can be used to filter labels or label behavior wh...
@ None
Disable default labeling filtration.
DataBoundary
Diagnostic region identifier.
@ Default
Region is not specified.
A file containing the MIP SDK error types.
This file contains the ExecutionState class.
This file contains the Label class.
MIP namespace macros.