SDK da Proteção de Informações da Microsoft - conceitos dos objetos de perfil e mecanismo

  • Artigo

Perfis

Onde MipContext é a classe para armazenar configurações específicas do SDK, o perfil é a classe raiz para todas as operações específicas de proteção e rotulagem da PIM no SDK. Antes de usar um dos três conjuntos de API, o aplicativo cliente deve criar um perfil. Operações futuras são executadas pelo perfil ou por outros objetos adicionados ao perfil. Apenas um único objeto de perfil por processo é recomendado. A criação de mais de um pode resultar em comportamento inesperado.

Há três tipos de perfil no SDK da PIM:

A API usada no aplicativo de consumo determina qual classe de perfil deve ser usada.

O próprio perfil oferece as seguintes funcionalidades:

  • Define se o estado deve ser carregado na memória ou persistido no disco e, se persistir no disco, deve ser criptografado.
  • Define o mip::ConsentDelegate que deve ser usado nas operações de consentimento.
  • Define a implementação do mip::FileProfile::Observer que será usada para retornos de chamada assíncronos nas operações de perfil.

Configurações do perfil de trabalho

  • MipContext: o objeto MipContext que foi inicializado para armazenar informações do aplicativo, caminho de estado etc.
  • CacheStorageType: define como armazenar o estado: na memória, no disco ou no disco e criptografado.
  • consentDelegate: um ponteiro compartilhado de classe mip::ConsentDelegate.
  • observer: um ponteiro compartilhado para a implementação do perfil Observer (em PolicyProfile, ProtectionProfile e FileProfile).
  • applicationInfo: um objeto mip::ApplicationInfo. Informações sobre o aplicativo que está consumindo o SDK, que corresponde à ID e ao nome do registro do aplicativo Microsoft Entra.

Mecanismos

Os mecanismos do SDK de arquivo, perfil e proteção fornecem uma interface para operações executadas por uma identidade específica. Um mecanismo é adicionado ao objeto de perfil para cada usuário ou entidade de serviço que inicia sessão no aplicativo. É possível executar operações delegadas por meio do mip::ProtectionSettings e pelo manipulador de arquivo ou proteção. Consulte a seção de configurações de proteção nos conceitos do FileHandler para obter mais detalhes.

Há três classes de mecanismo no SDK, uma para cada API. A seguinte lista mostra as classes de mecanismo e algumas das funções associadas a cada uma:

  • mip::ProtectionEngine
  • mip::PolicyEngine
    • ListSensitivityLabels(): obtém a lista de rótulos para o mecanismo carregado.
    • GetSensitivityLabel(): obtém o rótulo do conteúdo existente.
    • ComputeActions(): fornecido com uma ID de rótulo e metadados opcionais, retorna a lista de ações que devem ocorrer para um item específico.
  • 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.

A criação de um mecanismo exige a transmissão de um objeto de configurações de mecanismo específico que contém as configurações para o tipo de mecanismo a ser criado. O objeto de configurações permite que o desenvolvedor especifique detalhes sobre o identificador do mecanismo, a implementação de mip::AuthDelegate, a localidade e as configurações personalizadas, bem como outros detalhes específicos da API.

Estados do mecanismo

Um mecanismo pode ter um de dois estados:

  • CREATED: criado indica que o SDK tem informações de estado local suficientes depois de chamar os serviços de back-end necessários.
  • LOADED: o SDK criou as estruturas de dados necessárias para que o mecanismo esteja operacional.

Um mecanismo deve ser criado e carregado para executar operações. A classe Profile expõe alguns métodos de gerenciamento de mecanismo: AddEngineAsync, DeleteEngineAsync e UnloadEngineAsync.

A tabela a seguir descreve os possíveis estados do mecanismo e quais métodos podem alterar esse estado:

Estado do mecanismo NONE CREATED LOADED
NONE AddEngineAsync
CREATED DeleteEngineAsync AddEngineAsync
LOADED DeleteEngineAsync UnloadEngineAsync

ID do mecanismo

Cada mecanismo tem um identificador exclusivo, id, que é usado em todas as operações de gerenciamento de mecanismo. O aplicativo pode fornecer um id, ou o SDK pode gerar um, se o aplicativo não fornecê-lo. Todas as demais propriedades do mecanismo (por exemplo, endereço de email nas informações de identidade) são payloads opacos para o SDK. O SDK NÃO executa nenhuma lógica para manter qualquer uma das outras propriedades exclusivas ou impor outras restrições.

Importante

**Como melhor prática, use uma ID exclusiva de mecanismo para o usuário e utiliza-a sempre que o usuário executar uma operação com o SDK. Deixar de fornecer uma ID exclusiva existente do mecanismo para um usuário ou serviço resultará em ciclos extras do serviço. Esses ciclos do serviço podem resultar em limitação e degradação do desempenho. **

// Create the FileEngineSettings object
FileEngine::Settings engineSettings(mip::Identity(mUsername), // This will be the engine ID. UPN, email address, or other unique user identifiers are recommended. 
													          mAuthDelegate,            // authDelegate implementation 
													          "",                       // ClientData
													          "en-US",                  // Client Locale
                                    false);                   // Load Sensitive Information Types

Métodos de gerenciamento de mecanismo

Como mencionado anteriormente, há três métodos de gerenciamento de mecanismo no SDK: AddEngineAsync, DeleteEngineAsync e UnloadEngineAsync.

AddEngineAsync

Esse método carrega um mecanismo existente ou cria um se ainda não existir um no estado local.

Se o aplicativo não fornecer um id, em FileEngineSettings, AddEngineAsync gerará um novo id. Em seguida, ele verificará se um mecanismo com id já existe no cache de armazenamento local. Se existir, ele carregará esse mecanismo. Se o mecanismo não existir no cache local, um novo mecanismo será criado chamando as APIs e os serviços de back-end necessários.

Em ambos os casos, se o método for bem-sucedido, o mecanismo estará carregado e pronto para uso.

DeleteEngineAsync

Exclui o mecanismo com o id informado. Todos os rastreamentos do mecanismo são removidos do cache local.

UnloadEngineAsync

Descarrega as estruturas de dados na memória para o mecanismo com o id informado. O estado local desse mecanismo ainda está intacto e pode ser recarregado com AddEngineAsync.

Esse método permite que o aplicativo seja criterioso sobre o uso de memória, descarregando mecanismos que não devem ser usados em breve.

Próximas etapas