Kit de développement logiciel (SDK) Microsoft Information Protection - Concepts du gestionnaire de fichiers

Dans le kit de développement logiciel (SDK) File MIP, le mip::FileHandler expose toutes les opérations différentes qui peuvent être utilisées pour lire et écrire des étiquettes ou une protection sur un ensemble de types de fichiers pour lesquels la prise en charge est intégrée.

Types de fichiers pris en charge

• Formats de fichiers Office basés sur OPC (Office 2010 et versions ultérieures)
• Formats de fichiers Office hérités (Office 2007)
• PDF
• Prise en charge de PFILE générique
• Fichiers qui prennent en charge Adobe XMP

Fonctions du gestionnaire de fichiers

mip::FileHandler expose les méthodes de lecture, écriture et suppression des étiquettes et des informations de protection. Pour obtenir la liste complète, consultez la référence de l’API.

Dans cet article, nous allons aborder les méthodes suivantes :

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

Spécifications

La création d’un FileHandler pour travailler avec un fichier spécifique nécessite :

• Un FileProfile
• Un FileEngine ajouté à l’élément FileProfile
• Classe qui hérite mip::FileHandler::Observer

Créer un descripteur de fichier

La première étape requise pour gérer les fichiers dans le kit de développement logiciel (SDK) File consiste à créer un objet FileHandler. Cette classe implémente toutes les fonctionnalités requises pour obtenir, définir, mettre à jour, supprimer et commiter les modifications apportées aux fichiers.

La création du FileHandler est aussi simple que l’appel de la fonction CreateFileHandlerAsync de FileEngine à l’aide du modèle promesse/avenir.

CreateFileHandlerAsync accepte trois paramètres : le chemin d’accès au fichier qui doit être lu ou modifié, le mip::FileHandler::Observer pour les notifications d’événements asynchrones et la promesse pour le FileHandler.

Remarque : La classe mip::FileHandler::Observer doit être implémentée dans une classe dérivée, car CreateFileHandler requiert l’objet Observer.

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();

Une fois l’objet FileHandler créé, les opérations de fichier (obtenir/définir/supprimer/commiter) peuvent être effectuées.

Lire une étiquette

Exigences de métadonnées

Il existe quelques exigences pour lire correctement les métadonnées à partir d’un fichier et les traduire en quelque chose qui peut être utilisé dans les applications.

• L’étiquette en cours de lecture doit toujours exister dans le service Microsoft 365. S’il a été entièrement supprimé, le kit de développement logiciel (SDK) ne parvient pas à obtenir des informations sur cette étiquette et retourne une erreur.
• Les métadonnées du fichier doivent être intactes. Ces métadonnées incluent :
  • Attribut1
  • Attribut2

GetLabelAsync()

Après avoir créé le gestionnaire pour pointer vers un fichier spécifique, nous revenons au modèle promesse/avenir pour lire l’étiquette de manière asynchrone. La promesse concerne un objet mip::ContentLabel qui contient toutes les informations relatives à l’étiquette appliquée.

Après avoir instancié les objets promise et future, nous lisons l’étiquette en appelant fileHandler->GetLabelAsync() et en fournissant la promise comme seul paramètre. Enfin, l’étiquette peut être stockée dans un objet mip::ContentLabel qui sera obtenu à partir du 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();

Les données d’étiquette peuvent être lues à partir de l’objet label et passées à tout autre composant ou fonctionnalité de l’application.

Définissez une étiquette

La définition d’une étiquette est un processus en deux parties. Tout d’abord, après avoir créé un gestionnaire qui pointe vers le fichier en question, l’étiquette peut être définie en appelant FileHandler->SetLabel() avec certains paramètres : mip::Label, mip::LabelingOptions et mip::ProtectionOptions. Tout d’abord, nous devons résoudre l’ID d’étiquette en étiquette, puis définir les options d’étiquetage.

Résoudre l’ID d’étiquette en mip::Label

Le premier paramètre de la fonction SetLabel est une mip::Label. Souvent, l’application fonctionne avec des identificateurs d’étiquette plutôt que des étiquettes. L’identificateur d’étiquette peut être résolu en mip::Label en appelant GetLabelById sur le moteur de fichier ou de stratégie :

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

Options d’étiquetage

Le deuxième paramètre requis pour définir l’étiquette est mip::LabelingOptions.

LabelingOptions spécifie des informations supplémentaires sur l’étiquette, telles que la AssignmentMethod et la justification d’une action.

• mip::AssignmentMethod est un énumérateur qui a trois valeurs : STANDARD, PRIVILEGED ou AUTO. Pour plus d’informations, consultez la référence mip::AssignmentMethod.
• La justification n’est requise que si la stratégie de service l’exige et lorsque vous réduisez la sensibilité existante d’un fichier.

Cet extrait illustre la création de l’objet mip::LabelingOptions et la définition d’une justification et d’un message de rétrogradation.

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

Paramètres de protection

Certaines applications peuvent avoir besoin d’effectuer des opérations pour le compte d’une identité d’utilisateur déléguée. La classe mip::ProtectionSettings permet à l’application de définir l’identité déléguée par gestionnaire. Auparavant, la délégation était effectuée par les classes de moteur. Cela a eu des inconvénients importants dans le traitement des applications et les allers-retours de service. En déplaçant les paramètres de l’utilisateur délégué vers mip::ProtectionSettings et en effectuant cette partie de la classe de gestionnaire, nous supprimons ce traitement, ce qui entraîne de meilleures performances pour les applications qui effectuent de nombreuses opérations pour le compte de divers ensembles d’identités utilisateur.

Si la délégation n’est pas requise, passez mip::ProtectionSettings() à la fonction SetLabel. Si la délégation est requise, elle peut être obtenue en créant un objet mip::ProtectionSettings et en définissant l’adresse e-mail déléguée :

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

Définissez l’étiquette

Après avoir récupéré la mip::Label à l’aide de l’ID, définissez les options d’étiquetage et, si vous le souhaitez, définissez les paramètres de protection ; l’étiquette peut maintenant être définie sur le gestionnaire.

Si vous n’avez pas défini les paramètres de protection, définissez l’étiquette en appelant SetLabel sur le gestionnaire :

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

Si vous avez exigé des paramètres de protection pour effectuer une opération déléguée, procédez comme suit :

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

Après avoir défini l’étiquette sur le fichier référencé par le gestionnaire, il reste une étape supplémentaire pour commiter la modification et écrire un fichier sur le disque ou créer un flux de sortie.

Valider les modifications

La dernière étape de la validation de toute modification apportée à un fichier dans le kit de développement logiciel (SDK) MIP consiste à commiter la modification. Vous faites cela en utilisant la fonction FileHandler->CommitAsync().

Pour mettre en œuvre la fonction de commit, nous revenons à la promesse/avenir, en créant une promesse pour un bool. La fonction CommitAsync() retourne vrai si l’opération a réussi ou faux si elle a échoué pour une raison quelconque.

Après avoir créé la promise et le future, CommitAsync() est appelé et deux paramètres sont fournis : le chemin du fichier de sortie (std::string) et la promesse. Enfin, le résultat est obtenu en récupérant la valeur de l’objet future.

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

Important : les FileHandler ne mettront pas à jour ni ne remplaceront les fichiers existants. Il incombe au développeur d’implémenter le remplacement du fichier étiqueté.

Si vous écrivez une étiquette dans FileA.docx, une copie du fichier, FileB.docx, est créée avec l’étiquette appliquée. Le code doit être écrit pour supprimer/renommer FileA.docx et renommer FileB.docx.

Supprimer une étiquette

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);

Supprimer la protection

Votre application SDK File MIP doit vérifier que l’utilisateur dispose des droits nécessaires pour supprimer la protection du fichier accessible. Pour ce faire, vous pouvez effectuer un contrôle d’accès avant de supprimer la protection.

La fonction RemoveProtection() se comporte d’une manière similaire à SetLabel() ou DeleteLabel(). La méthode est appelée sur l’objet FileHandler existant, puis la modification doit être commitée.

Exemple en code C++ :

// 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.");
    }
}

Exemple .NET :

if(handler.Protection != null)
{                
    // Validate that user has rights to remove protection from the file.                    
    if(handler.Protection.AccessCheck(Rights.Export) || 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.");
    }
}