Microsoft Information Protection SDK - Concepten van bestandshandler

  • Artikel

In de MIP-bestands-SDK mip::FileHandler worden alle verschillende bewerkingen weergegeven die kunnen worden gebruikt voor het lezen en schrijven van labels of beveiliging voor een set bestandstypen waarvoor ondersteuning is ingebouwd.

Ondersteunde bestandstypen

  • Office-bestandsindelingen op basis van OPC (Office 2010 en hoger)
  • Verouderde Office-bestandsindelingen (Office 2007)
  • PDF
  • Algemene PFILE-ondersteuning
  • Bestanden die Adobe XMP ondersteunen

Bestandshandlerfuncties

mip::FileHandler biedt methoden voor het lezen, schrijven en verwijderen van zowel labels als beveiligingsinformatie. Raadpleeg de API-verwijzing voor de volledige lijst.

In dit artikel worden de volgende methoden behandeld:

  • GetLabelAsync()
  • SetLabel()
  • DeleteLabel()
  • RemoveProtection()
  • CommitAsync()

Vereisten

Voor het maken van een FileHandler bestand om te kunnen werken met een specifiek bestand is het volgende vereist:

  • A FileProfile
  • Een FileEngine toegevoegd aan de FileProfile
  • Een klasse die wordt overgenomen mip::FileHandler::Observer

Een bestandshandler maken

De eerste stap die nodig is bij het beheren van bestanden in de File SDK, is het maken van een FileHandler object. Deze klasse implementeert alle functionaliteit die nodig is voor het ophalen, instellen, bijwerken, verwijderen en doorvoeren van labelwijzigingen in bestanden.

Het maken van de FileHandler functie is net zo eenvoudig als het aanroepen van de FileEngineCreateFileHandlerAsync functie met behulp van het promise/future-patroon.

CreateFileHandlerAsync accepteert drie parameters: het pad naar het bestand dat moet worden gelezen of gewijzigd, de mip::FileHandler::Observer voor asynchrone gebeurtenismeldingen en de belofte voor de FileHandler.

Opmerking: De mip::FileHandler::Observer klasse moet worden geïmplementeerd in een afgeleide klasse, zoals CreateFileHandler vereist voor het Observer object.

auto createFileHandlerPromise = std::make_shared<std::promise<std::shared_ptr<mip::FileHandler>>>();
auto createFileHandlerFuture = createFileHandlerPromise->get_future();
fileEngine->CreateFileHandlerAsync(filePath, std::make_shared<FileHandlerObserver>(), createFileHandlerPromise);
auto fileHandler = createFileHandlerFuture.get();

Nadat het FileHandler object is gemaakt, kunnen bestandsbewerkingen (get/set/delete/commit) worden uitgevoerd.

Een label lezen

Vereisten voor metagegevens

Er zijn enkele vereisten voor het lezen van metagegevens uit een bestand en het vertalen naar iets dat kan worden gebruikt in toepassingen.

  • Het label dat wordt gelezen, moet nog steeds bestaan in de Microsoft 365-service. Als deze volledig is verwijderd, kan de SDK geen informatie over dat label ophalen en wordt er een fout geretourneerd.
  • De metagegevens van het bestand moeten intact zijn. Deze metagegevens omvatten:
    • Kenmerk1
    • Kenmerk2

GetLabelAsync()

Nadat u de handler hebt gemaakt om naar een specifiek bestand te verwijzen, keren we terug naar het promise/future-patroon om het label asynchroon te lezen. De belofte is voor een mip::ContentLabel object dat alle informatie over het toegepaste label bevat.

Na het instantiëren van de promise en future objecten, lezen we het label door het aanroepen fileHandler->GetLabelAsync() en opgegeven promise als de enige parameter. Ten slotte kan het label worden opgeslagen in een mip::ContentLabel object dat we van de future.

auto loadPromise = std::make_shared<std::promise<std::shared_ptr<mip::ContentLabel>>>();
auto loadFuture = loadPromise->get_future();
fileHandler->GetLabelAsync(loadPromise);
auto label = loadFuture.get();

Labelgegevens kunnen worden gelezen uit het label object en worden doorgegeven aan elk ander onderdeel of elke andere functionaliteit in de toepassing.

Een label instellen

Het instellen van een label is een proces van twee delen. Als u eerst een handler hebt gemaakt die verwijst naar het betreffende bestand, kan het label worden ingesteld door een aantal parameters aan te roepen FileHandler->SetLabel() : mip::Label, mip::LabelingOptionsen mip::ProtectionOptions. Eerst moeten we de label-id naar een label oplossen en vervolgens de labelopties definiëren.

Label-id oplossen om te mip::Label

De eerste parameter van de functie SetLabel is een mip::Label. Vaak werkt de toepassing met label-id's in plaats van labels. De label-id kan worden omgezet naar de mip::Label id door GetLabelById aan te roepen op de bestands- of beleidsengine:

mip::Label label = mEngine->GetLabelById(labelId);

Labelopties

De tweede parameter die is vereist om het label in te stellen, is mip::LabelingOptions.

LabelingOptions geeft aanvullende informatie op over het label, zoals de AssignmentMethod en reden voor een actie.

  • mip::AssignmentMethod is een enumerator met drie waarden: STANDARD, PRIVILEGEDof AUTO. Bekijk de mip::AssignmentMethod verwijzing voor meer informatie.
  • De reden is alleen vereist als het servicebeleid dit vereist en wanneer u de bestaande gevoeligheid van een bestand verlaagt.

Dit knipsel laat zien hoe u het mip::LabelingOptions object maakt en de reden voor downgraden en het bericht instelt.

auto labelingOptions = mip::LabelingOptions(mip::AssignmentMethod::STANDARD);
labelingOptions.SetDowngradeJustification(true, "Because I made an educated decision based upon the contents of this file.");

Beveiligingsinstellingen

Sommige toepassingen moeten mogelijk bewerkingen uitvoeren namens een gedelegeerde gebruikersidentiteit. Met mip::ProtectionSettings de klasse kan de toepassing de gedelegeerde identiteit per handler definiëren. Voorheen werd de delegatie uitgevoerd door de engineklassen. Dit had aanzienlijke nadelen in de overhead van toepassingen en retouren van services. Door de gedelegeerde gebruikersinstellingen te verplaatsen naar mip::ProtectionSettings en dit onderdeel van de handlerklasse te maken, elimineren we deze overhead, wat resulteert in betere prestaties voor toepassingen die veel bewerkingen uitvoeren namens diverse sets gebruikersidentiteiten.

Als delegering niet vereist is, geeft mip::ProtectionSettings() u deze door aan de functie SetLabel . Als delegatie is vereist, kan dit worden bereikt door een mip::ProtectionSettings object te maken en het gedelegeerde e-mailadres in te stellen:

mip::ProtectionSettings protectionSettings; 
protectionSettings.SetDelegatedUserEmail("alice@contoso.com");

Het label instellen

Nadat u de mip::Label id hebt opgehaald, stelt u de labelopties in en kunt u desgewenst de beveiligingsinstellingen instellen. Het label kan nu op de handler worden ingesteld.

Als u geen beveiligingsinstellingen hebt ingesteld, stelt u het label in door de handler aan te roepen SetLabel :

fileHandler->SetLabel(label, labelingOptions, mip::ProtectionSettings());

Als u wel beveiligingsinstellingen nodig hebt om een gedelegeerde bewerking uit te voeren, gaat u als volgt te werk:

fileHandler->SetLabel(label, labelingOptions, protectionSettings);

Nadat u nu het label hebt ingesteld op het bestand waarnaar wordt verwezen door de handler, is er nog één stap om de wijziging door te voeren en een bestand naar de schijf te schrijven of een uitvoerstroom te maken.

Wijzigingen doorvoeren

De laatste stap bij het doorvoeren van wijzigingen in een bestand in de MIP SDK is het doorvoeren van de wijziging. Dit wordt bereikt met behulp van de FileHandler->CommitAsync() functie.

Om de toezeggingsfunctie te implementeren, gaan we terug naar belofte/toekomst, waardoor we een belofte voor een bool. De CommitAsync() functie retourneert waar als de bewerking is geslaagd of onwaar als deze om welke reden dan ook is mislukt.

Nadat u de promise en futurehebt gemaakt, CommitAsync() worden er twee parameters opgegeven: het pad naar het uitvoerbestand (std::string) en de belofte. Ten slotte wordt het resultaat verkregen door de waarde van het future object op te halen.

auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);
auto wasCommitted = commitFuture.get();

Belangrijk: Bestaande FileHandler bestanden worden niet bijgewerkt of overschreven. Het is aan de ontwikkelaar om het bestand te vervangen dat wordt gelabeld.

Als u een label naar FileA.docx schrijft, wordt een kopie van het bestand FileB.docx gemaakt met het toegepaste label. Code moet worden geschreven om FileA.docx te verwijderen/hernoemen en de naam van FileB.docx te wijzigen.

Een label verwijderen

auto fileHandler = mEngine->CreateFileHandler(filePath, std::make_shared<FileHandlerObserverImpl>());
fileHandler->DeleteLabel(mip::AssignmentMethod::PRIVILEGED, "Label unnecessary.");
auto commitPromise = std::make_shared<std::promise<bool>>();
auto commitFuture = commitPromise->get_future();
fileHandler->CommitAsync(outputFile, commitPromise);

Beveiliging verwijderen

Uw MIP File SDK-toepassing moet valideren dat de gebruiker rechten heeft om de beveiliging te verwijderen van het bestand dat wordt geopend. Dit kan worden bereikt door een toegangscontrole uit te voeren voordat u de beveiliging verwijdert.

De RemoveProtection() functie gedraagt zich op een manier die vergelijkbaar is met SetLabel() of DeleteLabel(). De methode wordt aangeroepen op het bestaande FileHandler object, waarna de wijziging moet worden doorgevoerd.

Belangrijk

Als ontwikkelaar van de toepassing is het de mogelijkheid om deze toegangscontrole uit te voeren. Als de toegangscontrole niet goed kan worden uitgevoerd, kan de gegevenslekken opnieuw worden gelekt.

C++-voorbeeld:

// Validate that the file referred to by the FileHandler is protected.
if (fileHandler->GetProtection() != nullptr)
{
    // Validate that user is allowed to remove protection.
    if (fileHandler->GetProtection()->AccessCheck(mip::rights::Export() || fileHandler->GetProtection()->AccessCheck(mip::rights::Owner()))
    {
        auto commitPromise = std::make_shared<std::promise<bool>>();
        auto commitFuture = commitPromise->get_future();
        // Remove protection and commit changes to file.
        fileHandler->RemoveProtection();
        fileHandler->CommitAsync(outputFile, commitPromise);
        result = commitFuture.get();
    }
    else
    {
        // Throw an exception if the user doesn't have rights to remove protection.
        throw std::runtime_error("User doesn't have EXPORT or OWNER right.");
    }
}

.NET-voorbeeld:

if(handler.Protection != null)
{                
    // Validate that user has rights to remove protection from the file.                    
    if(handler.Protection.AccessCheck(Rights.Extract) || handler.Protection.AccessCheck(Rights.Owner))
    {
        // If user has Extract right, remove protection and commit the change. Otherwise, throw exception. 
        handler.RemoveProtection();
        bool result = handler.CommitAsync(outputPath).GetAwaiter().GetResult();     
        return result;   
    }
    else
    {
        throw new Microsoft.InformationProtection.Exceptions.AccessDeniedException("User lacks EXPORT right.");
    }
}