Microsoft Information Protection SDK - Konzepte der File SDK-Engine

Artikel
01/30/2024

Der mip::FileEngine im MIP File SDK bietet eine Schnittstelle zu allen Vorgänge, die im Namen einer bestimmten Identität durchgeführt werden. Eine Engine wird für jeden Benutzer hinzugefügt, der sich bei der Anwendung anmeldet, und alle Vorgänge, die die Engine ausführt, werden im Kontext dieser Identität ausgeführt.

Das FileEngine hat zwei hauptverantwortliche Aufgaben: Auflisten von Bezeichnungen für einen authentifizierten Benutzer und Erstellen von Dateihandlern zum Ausführen von Dateivorgängen im Namen des Benutzers.

mip::FileEngine
ListSensitivityLabels(): Ruft die Liste der Bezeichnungen für die geladene Engine ab.
CreateFileHandler(): Erstellt eine mip::FileHandler für eine bestimmte Datei oder einen bestimmten Datenstrom.

Hinzufügen einer Datei-Engine

Wie in Profile- und Engine-Objekte behandelt, kann eine Engine zwei Zustände aufweisen – CREATED oder LOADED. Wenn es sich nicht um einen dieser beiden Zustände handelt, ist sie nicht vorhanden. Um sowohl einen Zustand zu erstellen als auch zu laden, ist es nur erforderlich, einen einzelnen Aufruf an FileProfile::LoadAsync durchzuführen. Wenn die Engine bereits im zwischengespeicherten Zustand vorhanden ist, lautet sie LOADED. Wenn diese Komponente nicht vorhanden ist, lautet sie CREATED und LOADED. CREATED bedeutet, dass die Anwendung über alle Informationen des Diensts verfügt, die zum Laden der Engine erforderlich sind. LOADED bedeutet, dass alle zum Nutzen der Engine erforderlichen Datenstrukturen im Arbeitsspeicher erstellt wurden.

Erstellen von Einstellungen der Datei-Engine

Ähnlich wie bei einem Profil erfordert die Engine auch ein Einstellungsobjekt, mip::FileEngine::Settings. Dieses Objekt speichert den eindeutigen Enginebezeichner, die mip::AuthDelegate-Implementierung, anpassbare Client-Daten, die für Debugging oder Telemetrie verwendet werden können, und optional das Gebietsschema.

Hier erstellen wir ein FileEngine::Settings Objekt namens engineSettings unter Verwendung der Identität des Anwendungsbenutzers.

FileEngine::Settings engineSettings(
  mip::Identity(mUsername), // mip::Identity.
  authDelegateImpl,         // auth delegate object
  "",                       // Client data. Customizable by developer, stored with engine.
  "en-US",                  // Locale.
  false);                   // Load sensitive information types for driving classification.

Beim Erstellen von EngineSettings auf diese Weise ist es wichtig, auch explizit eine eindeutige EngineId über folgendes festzulegen:

engineSettings.SetEngineId(engineId);

Die Verwendung des Benutzernamens oder der E-Mail trägt dazu bei, dass jedes Mal, wenn der Benutzer den Dienst oder die Anwendung nutzt, dieselbe Engine geladen wird.

Auch gültig ist die Bereitstellung einer benutzerdefinierten Modul-ID:

FileEngine::Settings engineSettings(
  "myEngineId",     // string
  authDelegateImpl, // auth delegate object
  "",               // Client data in string format. Customizable by developer, stored with engine.
  "en-US",          // Locale. Default is en-US
  false);           // Load sensitive information types for driving classification. Default is false.

Als bewährte Methode sollte der erste Parameter, id, etwas sein, mit dem die Engine problemlos mit dem zugehörigen Benutzer verbunden werden kann. Etwas wie E-Mail-Adresse, UPN oder AAD-Objekt-GUID stellt sicher, dass die ID sowohl eindeutig ist als auch aus dem lokalen Zustand geladen werden kann, ohne den Dienst aufzurufen.

Hinzufügen der Datei-Engine

Um die Engine hinzuzufügen, kehren wir zum Zusage-/zukünftigen Muster zurück, das zum Laden des Profils verwendet wird. Anstatt die Zusage für mip::FileProfile zu erstellen, wird sie mithilfe von mip::FileEngine erstellt.

  //auto profile will be std::shared_ptr<mip::FileProfile>
  auto profile = profileFuture.get();

  // Instantiate the AuthDelegate implementation.
  auto authDelegateImpl = std::make_shared<sample::auth::AuthDelegateImpl>(appInfo, userName, password);

  //Create the FileEngine::Settings object
  FileEngine::Settings engineSettings("UniqueID", authDelegateImpl, "");

  //Create a promise for std::shared_ptr<mip::FileEngine>
  auto enginePromise = std::make_shared<std::promise<std::shared_ptr<mip::FileEngine>>>();

  //Instantiate the future from the promise
  auto engineFuture = enginePromise->get_future();

  //Add the engine using AddEngineAsync, passing in the engine settings and the promise
  profile->AddEngineAsync(engineSettings, enginePromise);

  //get the future value and store in std::shared_ptr<mip::FileEngine>
  auto engine = engineFuture.get();

Das Endergebnis des obigen Codes ist, dass die Engine für den authentifizierten Benutzer dem Profil hinzugefügt wird.

Auflisten von Vertraulichkeitsbezeichnungen

Mithilfe der hinzugefügten Engine können jetzt alle Vertraulichkeitsbezeichnungen aufgeführt werden, die für den authentifizierten Benutzer verfügbar sind, indem sie engine->ListSensitivityLabels() aufrufen.

ListSensitivityLabels() ruft die Liste der Bezeichnungen und Attribute dieser Bezeichnungen für einen bestimmten Benutzer aus dem Dienst ab. Das Ergebnis wird in einem Vektor von std::shared_ptr<mip::Label> gespeichert.

Hier finden Sie weitere Informationen über mip::Label.

ListSensitivityLabels()

std::vector<shared_ptr<mip::Label>> labels = engine->ListSensitivityLabels();

Oder, vereinfacht:

auto labels = engine->ListSensitivityLabels();

Drucken der Bezeichnungen und IDs

Das Drucken der Namen ist eine einfache Möglichkeit, zu zeigen, dass wir die Richtlinie erfolgreich aus dem Dienst abgerufen und die Bezeichnungen erhalten konnten. Um die Bezeichnung anzuwenden, ist der Bezeichnungsbezeichner erforderlich. Der folgende Code durchläuft alle Beschriftungen, zeigt die name und die id für jede übergeordnete und untergeordnete Bezeichnung an.

//Iterate through all labels in the vector
for (const auto& label : labels) {
  //Print label name and GUID
  cout << label->GetName() << " : " << label->GetId() << endl;

  //Print child label name and GUID
  for (const auto& child : label->GetChildren()) {
    cout << "->  " << child->GetName() <<  " : " << child->GetId() << endl;
  }
}

Die Sammlung der mip::Label, zurückgegeben von GetSensitivityLabels(), kann verwendet werden, um alle Bezeichnungen anzuzeigen, die dem Benutzer zur Verfügung stehen, und dann, wenn ausgewählt, die ID verwenden, um Bezeichnungen auf eine Datei anzuwenden.

Nächste Schritte

Nachdem das Profil geladen wurde, die Engine hinzugefügt wurde, und wir über Bezeichnungen verfügen, können wir einen Handler hinzufügen, um mit dem Lesen, Schreiben oder Entfernen von Bezeichnungen aus Dateien zu beginnen. Siehe Dateihandler im MIP SDK.

Freigeben über