Criar um suplemento do Outlook de encriptação (pré-visualização)

Implemente a funcionalidade personalizada de encriptação e desencriptação num suplemento do Outlook para proteger as comunicações de e-mail. O OnMessageRead evento permite que o suplemento identifique automaticamente mensagens encriptadas e processe a desencriptação, a apresentação de conteúdos e as notificações de erro.

Descrição geral dos fluxos de trabalho de encriptação e desencriptação

A tabela seguinte fornece uma descrição geral dos fluxos de trabalho de encriptação e desencriptação de um suplemento do Outlook. Também identifica se um passo requer uma solução personalizada ou se é suportado pela biblioteca de API javaScript (Office.js) do Office.

Implementar a desencriptação com a ativação baseada em eventos

Tem de implementar os seus próprios protocolos de encriptação e desencriptação. O suplemento também tem de ser configurado para processar o OnMessageRead evento para determinar convenientemente quando o suplemento pode desencriptar uma mensagem e apresentar os conteúdos desencriptados. Para implementar o OnMessageRead evento, tem de:

1. Configure o manifesto do suplemento.
2. Implementar o processamento de eventos.

Ambientes suportados

O OnMessageRead evento é suportado na superfície De Leitura da Mensagem. O suporte varia consoante o cliente e o ambiente do Exchange, conforme mostrado na tabela seguinte.

Pré-visualizar as APIs de desencriptação no Outlook clássico no Windows

Para pré-visualizar as APIs de desencriptação no Outlook clássico no Windows, adira ao programa Microsoft 365 Insider e, em seguida, selecione o Canal Beta no cliente Outlook. O cliente tem de estar na Versão 2510 (Compilação 19312.20000) ou posterior.

O Outlook Clássico no Windows inclui uma cópia local das versões de produção e beta do Office.js em vez de carregar a partir da rede de entrega de conteúdos (CDN). Por predefinição, a cópia de produção local da API é referenciada. Para referenciar a cópia beta local da API, tem de configurar o registo do computador. Isto irá permitir-lhe testar as funcionalidades de pré-visualização nos processadores de eventos no Outlook clássico no Windows.

1. No registo, navegue para HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Se a chave não existir, crie-a.

2. Crie uma entrada com o nome EnableBetaAPIsInJavaScript e defina o respetivo valor como 1.

   

Configurar o manifesto

Para ativar o OnMessageRead seu suplemento no evento, tem de configurar o <VersionOverridesV1_1> nó do ficheiro manifest.xml do suplemento da seguinte forma.

• Para executar um suplemento baseado em eventos no Outlook clássico no Windows, tem de especificar o ficheiro JavaScript que contém o processador de eventos no <elemento subordinado Substituir> do <elemento Runtime> .
• Especifique o OnMessageRead evento no Type atributo de um <elemento LaunchEvent> . Tem de atribuir o nome da função do processador de eventos ao FunctionName atributo do elemento . Para facilitar a verificação se a mensagem foi encriptada pelo suplemento, tem de ser especificada uma chave de cabeçalho no HeaderName atributo . O mesmo cabeçalho é adicionado a uma mensagem encriptada pelo suplemento.

Segue-se um exemplo de um <VersionOverrides> nó que implementa o OnMessageRead evento.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.15">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the event handler. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements event-based activation. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="SoftBlock"/>
              <LaunchEvent Type="OnMessageRead" FunctionName="onMessageReadHandler" HeaderName="contoso-encrypted"/>
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
        </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      ...
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.js"/>
      </bt:Urls>
      ...
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Implementar o processamento de eventos

O OnMessageRead processador de eventos é utilizado para executar a operação de desencriptação e determinar se pretende apresentar o conteúdo desencriptado de uma mensagem.

• Para garantir que o processador é executado quando o OnMessageRead evento ocorre, chame Office.actions.associate no ficheiro JavaScript onde o processador é implementado. Esta ação mapeia o nome do processador especificado no FunctionName atributo do <LaunchEvent> elemento no manifesto para o seu equivalente JavaScript.
• Após a conclusão da operação de desencriptação, tem de chamar para indicar event.completed ao cliente que o suplemento concluiu o processamento do OnMessageRead evento. Para apresentar os conteúdos desencriptados de uma mensagem e os respetivos anexos, transmita um objeto MessageDecryptEventCompletedOptions à chamada e defina a event.completed respetiva propriedade allowEvent como true. Em seguida, especifique o conteúdo desencriptado da mensagem nas propriedades emailBody e attachments do objeto. Também pode especificar quaisquer dados que o seu suplemento possa precisar para processamento na propriedade contextData . Por exemplo, pode armazenar cabeçalhos de Internet personalizados para desencriptar mensagens em cenários de resposta e reencaminhamento.

Segue-se um exemplo de um OnMessageRead processador de eventos.

function onMessageReadHandler(event) {
    // Your code to decrypt the contents of a message would appear here.
    ...

    // Use the results from your decryption process to display the decrypted contents of the message body and attachments.
    const decryptedBodyContent = "<p>Please find attached the recent report and its supporting documentation.</p>";
    const decryptedBody = {
        coercionType: Office.CoercionType.Html,
        content: decryptedBodyContent
    };

    // Decrypted content and properties of a file attachment.
    const decryptedPdfFile = "JVBERi0xLjQKJeLjz9MKNCAwIG9i...";
    const pdfFileName = "Fabrikam_Report_202509";

    // Decrypted content and properties of a mail item.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    // Decrypted properties of a cloud attachment.
    const cloudFilePath = "https://contosostorage.com/reports/weekly_forecast.xlsx";
    const cloudFileName = "weekly_forecast.xlsx";

    // Decrypted content and properties of an inline image.
    const decryptedImageFile = "iVBORw0KGgoAAAANSUhEUgAA...";
    const imageFileName = "banner.png";
    const imageContentId = "image001.png@01DC1DD9.1A4AA300";

    const decryptedAttachments = [
        {
            attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedPdfFile,
            isInline: false,
            name: pdfFileName
        },
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Item,
            content: decryptedEmailFile,
            isInline: false,
            name: emailFileName
        },
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Cloud,
            isInline: false,
            name: cloudFileName,
            path: cloudFilePath
        },
        {
            attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedImageFile,
            contentId: imageContentId,
            isInline: true,
            name: imageFileName
        }
    ];

    event.completed({
        allowEvent: true,
        emailBody: decryptedBody,
        attachments: decryptedAttachments,
        contextData: { messageType: "ReplyFromDecryptedMessage" }
    });
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onMessageReadHandler", onMessageReadHandler);

Comportamento e limitações

• Tenha em atenção os comportamentos e limitações dos suplementos baseados em eventos. Para saber mais, veja Ativar suplementos com eventos.

• Uma vez que cada suplemento utiliza o seu próprio protocolo de encriptação, uma mensagem só pode ser desencriptada pelo mesmo suplemento que o encriptou. Quando um utilizador não tem o suplemento necessário instalado para desencriptar uma mensagem, uma notificação alerta-o de que a mensagem está encriptada. Para orientar o utilizador através do processo de desencriptação, personalize uma mensagem de marcador de posição para o corpo da mensagem encriptada. A mensagem de marcador de posição pode incluir informações sobre como instalar o seu suplemento. Para definir o corpo da mensagem durante o processo de encriptação, ligue para Office.context.mailbox.item.body.setAsync.

  

• Para garantir a segurança e confidencialidade dos dados, os conteúdos desencriptados não são armazenados no cliente do Outlook. O conteúdo de uma mensagem encriptada é desencriptado sempre que um utilizador a abre.

• Primeiro, é necessário desencriptar uma mensagem encriptada para que um utilizador possa responder ou reencaminhá-la. Um utilizador não pode responder ou reencaminhar uma mensagem encriptada enquanto está a ser desencriptada.

• Se um utilizador navegar para outro item de correio enquanto uma mensagem encriptada estiver a ser desencriptada, o processo de desencriptação deixa de ser executado. O utilizador tem de selecionar ou abrir novamente a mensagem para ativar o processo de desencriptação.

• Ao responder ou reencaminhar mensagens encriptadas, os rascunhos são guardados sem encriptação na pasta Rascunhos .

Notificações de desencriptação

Os suplementos que processam o OnMessageRead evento apresentam automaticamente notificações em determinados cenários de desencriptação, conforme descrito na tabela seguinte.

Confira também

• Privacidade e segurança para Suplementos do Office
• Ativar suplementos com eventos
• Resolver problemas de suplementos baseados em eventos e relatórios de spam
• Obter e definir cabeçalhos da Internet numa mensagem num suplemento do Outlook
• Gerir a etiqueta de confidencialidade da sua mensagem ou compromisso no modo de composição