SDK da Proteção de Informações da Microsoft: conceitos do mecanismo do SDK de arquivo

Artigo
01/30/2024

O mip::FileEngine no SDK do arquivo da PIM fornece uma interface para todas as operações que são executadas em nome de uma identidade especificada. Um mecanismo será adicionado para cada usuário que iniciar sessão no aplicativo e todas as operações que o mecanismo executar serão executadas no contexto dessa identidade.

O FileEngine tem duas responsabilidades principais: listar rótulos para um usuário autenticado e criar manipuladores de arquivos para executar operações de Arquivos em nome do usuário.

mip::FileEngine
ListSensitivityLabels(): obtém a lista de rótulos para o mecanismo carregado.
CreateFileHandler(): cria um mip::FileHandler para um arquivo ou fluxo específico.

Adicionar um mecanismo de arquivo

Conforme abordado em objetos de Perfil e Mecanismo, um mecanismo pode ter dois estados: CREATED ou LOADED. Se o mecanismo não tiver um desses dois estados, ele não existirá. Para criar e carregar um estado, só é necessário fazer uma única chamada para FileProfile::LoadAsync. Se o mecanismo já existir no estado armazenado em cache, ele será LOADED. Se o mecanismo não existir, ele será CREATED e LOADED. CREATED implica que o aplicativo tem todas as informações do serviço necessárias para carregar o mecanismo. LOADED implica que todas as estruturas de dados necessárias para aproveitar o mecanismo foram criadas na memória.

Criar configurações do mecanismo de arquivo

Semelhante a um perfil, o mecanismo também requer um objeto de configurações, mip::FileEngine::Settings. Esse objeto armazena o identificador exclusivo do mecanismo, a implantação mip::AuthDelegate, dados personalizáveis do cliente que podem ser usados para depuração ou telemetria e, opcionalmente, a localidade.

Aqui, criamos um objeto FileEngine::Settings denominado engineSettings usando a identidade do usuário do aplicativo.

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.

Ao criar engineSettings dessa maneira, é importante também definir explicitamente um engineId exclusivo ao:

engineSettings.SetEngineId(engineId);

Usar o nome de usuário ou email ajuda a garantir que o mesmo mecanismo seja carregado sempre que o usuário usar o serviço ou aplicativo.

Também é válido fornecer uma ID de mecanismo personalizador:

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 melhor prática, o primeiro parâmetro, id, deve ser algo que permita que o mecanismo seja facilmente conectado ao usuário associado. Algo como endereço de email, UPN ou GUID de objeto do AAD garantiria que a ID fosse exclusiva e pudesse ser carregada no estado local sem chamar o serviço.

Adicionar o mecanismo de arquivo

Para adicionar o mecanismo, voltaremos ao padrão promessa/futuro usado para carregar o perfil. Em vez de criar a promessa para mip::FileProfile, ela é criado usando 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();

O resultado final do código acima é que o mecanismo para o usuário autenticado será adicionado ao perfil.

Listar rótulos de confidencialidade

Com o uso do mecanismo adicionado, agora é possível listar todos os rótulos de confidencialidade disponíveis ao usuário autenticado chamando engine->ListSensitivityLabels().

ListSensitivityLabels() buscará a lista de rótulos e atributos desses rótulos para um usuário específico no serviço. O resultado é armazenado em um vetor de std::shared_ptr<mip::Label>.

ListSensitivityLabels()

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

Ou, simplificando:

auto labels = engine->ListSensitivityLabels();

Imprimir as etiquetas e IDs

A impressão dos nomes é uma maneira fácil de mostrar que retiramos com êxito a política do serviço e conseguimos obter os rótulos. Para aplicar o rótulo, é necessário o identificador de rótulo. O código abaixo itera por todos os rótulos, exibindo o name e o id para cada rótulo pai e filho.

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

A coleção de mip::Label retornados por GetSensitivityLabels() pode ser usada para exibir todos os rótulos disponíveis para o usuário e, em seguida, quando selecionado, use a ID para aplicar rótulos a um arquivo.

Próximas etapas

Agora que o perfil está carregado, o mecanismo adicionado e temos rótulos, podemos adicionar um manipulador para começar a ler, gravar ou remover rótulos dos arquivos. Confira Manipuladores de arquivos no SDK da PIM.

Compartilhar via