SDK de Microsoft Information Protection: Conceptos del motor del SDK de archivos

  • Artículo

mip::FileEngine, en el SDK de archivos de MIP, proporciona una interfaz para todas las operaciones que se realizan en nombre de una identidad especificada. Se agregará un motor para cada usuario que inicie sesión en la aplicación y todas las operaciones que realice el motor se realizarán en el contexto de esa identidad.

FileEngine tiene dos responsabilidades principales: enumerar etiquetas para un usuario autenticado y crear controladores de archivos para realizar operaciones de archivo en nombre del usuario.

  • mip::FileEngine
  • ListSensitivityLabels(): obtiene la lista de etiquetas para el motor cargado.
  • CreateFileHandler(): crea un mip::FileHandler para un archivo o una secuencia específicos.

Adición de un motor de archivos

Como se describe en los objetos de perfil y motor, un motor puede tener dos estados: CREATED o LOADED. Si no es uno de esos dos estados, no existe. Para crear y cargar un estado, lo único que tiene que hacer es realizar una sola llamada a FileProfile::LoadAsync. Si el motor ya existe en el estado almacenado en caché, será LOADED. Si no existe, será CREATED y LOADED. CREATED implica que la aplicación tenga toda la información del servicio necesario para cargar el motor. LOADED implica que todas las estructuras de datos necesarias para aprovechar el motor se hayan creado en memoria.

Creación de la configuración del motor de archivos

De forma similar a un perfil, el motor también requiere un objeto de configuración: mip::FileEngine::Settings. Este objeto almacena el identificador único del motor, la implementación mip::AuthDelegate, los datos de cliente personalizables que se pueden usar para la depuración o telemetría, y, de manera opcional, la configuración regional.

Aquí se crea un objeto FileEngine::Settings denominado engineSettings mediante la identidad del usuario de la aplicación.

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.

Al crear engineSettings de esta manera, también es importante establecer de manera explícita un engineId único a través de:

engineSettings.SetEngineId(engineId);

El uso del nombre de usuario o correo electrónico ayuda a asegurarse de que se cargue el mismo motor cada vez que el usuario use el servicio o la aplicación.

También es válido proporcionar un id. de motor personalizado:

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.

Como procedimiento recomendado, el primer parámetro, id, debe ser un elemento que permita que el motor se conecte fácilmente al usuario asociado. Algo parecido a la dirección de correo electrónico, el UPN o el GUID de objeto de AAD garantizarían que el identificador sea único y se pueda cargar desde el estado local sin llamar al servicio.

Adición de un motor de archivos

Para agregar el motor, volveremos al patrón promesa/futuro usado para cargar el perfil. En lugar de crear la promesa para mip::FileProfile, se crea mediante mip::FileEngine.

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

El resultado final del código anterior es que se agregará un motor para el usuario autenticado en el perfil.

Enumeración de las etiquetas de confidencialidad

Con el motor agregado, ya podemos enumerar todas las etiquetas de confidencialidad disponibles para el usuario autenticado mediante una llamada a engine->ListSensitivityLabels().

ListSensitivityLabels() capturará la lista de etiquetas y atributos de esas etiquetas para un usuario específico del servicio. El resultado se almacena en un vector de std::shared_ptr<mip::Label>.

Obtenga más información aquí sobre mip::Label.

ListSensitivityLabels()

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

o bien, simplificado:

auto labels = engine->ListSensitivityLabels();

Imprimir los nombres es una manera fácil de mostrar que hemos extraído correctamente la directiva del servicio y hemos podido obtener las etiquetas. Para aplicar la etiqueta, se requiere el identificador de etiqueta. El siguiente código realiza una iteración en todas las etiquetas, mostrando name y id para cada etiqueta primaria y secundaria.

//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;
  }
}

La colección de mip::Label devuelta por GetSensitivityLabels() se puede usar para mostrar todas las etiquetas disponibles para el usuario y, a continuación, cuando se selecciona, permite usar el identificador para aplicar etiquetas a un archivo.

Pasos siguientes

Ahora que hemos cargado el perfil, hemos agregado el motor, y tenemos etiquetas, podemos agregar un controlador para empezar a leer, escribir o eliminar etiquetas de archivos. Consulte Controladores de archivos en el SDK de MIP.