SDK da Proteção de Informações da Microsoft - Conceitos de mecanismo do SDK de arquivos

Artigo
01/30/2024

O mip::FileEngine no SDK de arquivo MIP 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 entrar no aplicativo e todas as operações que o mecanismo executa 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 arquivo 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 nos objetos Profile e Engine, um mecanismo pode ter dois estados - CREATED ou LOADED. Se não for um desses dois estados, não existe. Para criar e carregar um estado, é necessário apenas fazer uma única chamada para FileProfile::LoadAsync. Se o mecanismo já existir no estado armazenado em cache, será LOADED. Se não existir, será CREATED e LOADED. CREATED implica que o aplicativo tem todas as informações do serviço necessárias para carregar o motor. LOADED implica que todas as estruturas de dados necessárias para alavancar o mecanismo foram criadas na memória.

Criar configurações do mecanismo de arquivos

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 mip::AuthDelegate implementação, os dados personalizáveis do cliente que podem ser usados para depuração ou telemetria e, opcionalmente, a localidade.

Aqui criamos um FileEngine::Settings objeto chamado 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 via:

engineSettings.SetEngineId(engineId);

Usar o nome de usuário ou e-mail ajuda a garantir que o mesmo mecanismo seja carregado cada vez que o usuário usa o serviço ou aplicativo.

Também é válido fornecer um ID de mecanismo 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 prática recomendada, o primeiro parâmetro, id, deve ser algo que permita que o motor seja facilmente conectado ao usuário associado. Algo como endereço de e-mail, UPN ou GUID de objeto AAD garantiria que o ID seja exclusivo e possa ser carregado do estado local sem chamar o serviço.

Adicionar o mecanismo de arquivo

Para adicionar o mecanismo, voltaremos ao padrão promise/future usado para carregar o perfil. Em vez de criar a promessa para mip::FileProfileo , ele é 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 sensibilidade

Usando o mecanismo adicionado, agora é possível listar todos os rótulos de sensibilidade disponíveis para o usuário autenticado chamando engine->ListSensitivityLabels().

ListSensitivityLabels() buscará a lista de rótulos e atributos desses rótulos para um usuário específico do 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, simplificado:

auto labels = engine->ListSensitivityLabels();

Imprimir as etiquetas e IDs

Imprimir os nomes é uma maneira fácil de mostrar que conseguimos extrair a política do serviço e conseguimos obter as etiquetas. Para aplicar o rótulo, é necessário o identificador do rótulo. O código abaixo itera através de 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 retornados mip::Label por GetSensitivityLabels() pode ser usada para exibir todos os rótulos disponíveis para o usuário e, em seguida, quando selecionado, usar o ID para aplicar rótulos a um arquivo.

Passos Seguintes

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

Partilhar via