Criar um suplemento do Outlook de encriptação

Implemente a funcionalidade personalizada de encriptação e desencriptação num suplemento do Outlook para proteger as comunicações de e-mail. O OnMessageDecrypt 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.

Experimentar um suplemento concluído

Para ver imediatamente um suplemento de encriptação concluído em ação, experimente o exemplo Encriptar e desencriptar mensagens no Outlook.

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 OnMessageDecrypt evento para determinar convenientemente quando o suplemento pode desencriptar uma mensagem e apresentar os conteúdos desencriptados. Para implementar o OnMessageDecrypt evento, tem de:

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

Ambientes suportados

O OnMessageDecrypt 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.

Configurar o manifesto

<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. This is used by Outlook on the web and the new Outlook on Windows. -->
          <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="OnMessageDecrypt" FunctionName="onMessageDecryptHandler" 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 OnMessageDecrypt 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 OnMessageDecrypt 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 OnMessageDecrypt 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 OnMessageDecrypt processador de eventos.

function onMessageDecryptHandler(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 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.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("onMessageDecryptHandler", onMessageDecryptHandler);

Desencriptar anexos de itens do Outlook (pré-visualização)

O suporte para desencriptar anexos de itens do Outlook (Office.MailboxEnums.AttachmentType.Itemparticularmente anexos de e-mail) está disponível para pré-visualização no Outlook na Web e no Windows (novo e clássico). Para pré-visualizar esta funcionalidade no Outlook clássico no Windows, tem de instalar a Versão 2606 (Compilação 20114.15110) ou posterior. Em seguida, adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta para aceder às compilações beta do Office. Para testar esta funcionalidade com o código de exemplo neste artigo, atualize a onMessageDecryptHandler função com o seguinte código.

    // Decrypted content and properties of an email attachment.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    const decryptedAttachments = [
        ...
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Item,
            content: decryptedEmailFile,
            name: emailFileName
        }
    ];
    ...

Personalizar mensagens de erro para a operação de desencriptação (pré-visualização)

As mensagens de erro personalizadas para operações de desencriptação falhadas estão disponíveis para pré-visualização no Outlook na Web e no Windows (novo e clássico). Para pré-visualizar esta funcionalidade no Outlook clássico no Windows, tem de instalar a Versão 2606 (Compilação 20114.15110) ou posterior. Em seguida, adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta para aceder às compilações beta do Office.

Se a operação de desencriptação falhar, a allowEvent propriedade da event.completed chamada está definida como falsee o Outlook apresenta a seguinte notificação predefinida ao utilizador: "<O nome> do suplemento não conseguiu processar a sua mensagem". Para especificar uma mensagem de erro personalizada, defina a propriedade errorMessage da chamada do event.completed suplemento. A sua mensagem personalizada tem o prefixo "Erro do nome> do <suplemento:". Se não for possível mostrar a sua mensagem personalizada, a notificação predefinida é apresentada.

O seguinte exemplo de código mostra como especificar uma mensagem de erro personalizada para o suplemento de desencriptação.

event.completed({
    allowEvent: false,
    errorMessage: "This message couldn't be decrypted. Contact the Contoso IT team for further assistance."
});

Gerir a distribuição de conteúdo desencriptado (pré-visualização)

Para ajudar a impedir a distribuição não autorizada de conteúdo desencriptado, as opções de controlo de acesso estão disponíveis para pré-visualização no Outlook na Web e no Windows (novo e clássico). Para pré-visualizar esta funcionalidade no Outlook clássico no Windows, tem de instalar a Versão 2606 (Compilação 20114.15110) ou posterior. Em seguida, adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta para aceder às compilações beta do Office.

Para limitar a impressão, cópia ou gravação de conteúdo desencriptado, inclua a propriedade accessControls da event.completed chamada. Em seguida, defina allowPrint, allowCopyPaste e allowSave properties como false. Se a accessControls propriedade não for especificada, os controlos de acesso são predefinidos para true.

Para testar esta funcionalidade com o código de exemplo neste artigo, atualize a event.completed chamada da onMessageDecryptHandler função com o seguinte código.

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

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 .

• A attachments propriedade do event.completed método não suporta anexos do tipo Office.MailboxEnums.AttachmentType.Item, exceto a pré-visualização no Outlook na Web e no Windows (novo e clássico). Para saber mais, veja Desencriptar anexos de itens do Outlook (pré-visualização).

• Os suplementos de encriptação personalizados não podem encriptar mensagens que já estejam protegidas por DRM ou S/MIME.

• No Outlook na Web e no novo Outlook no Windows, quando as mensagens encriptadas são agrupadas por conversação, apenas a mensagem atualmente selecionada do tópico de conversação é desencriptada. As outras mensagens no thread de conversação permanecem encriptadas até serem selecionadas.

• No Outlook na Web e no novo Outlook no Windows, os utilizadores só podem transferir uma mensagem desencriptada no formato EML. A opção para transferir no formato MSG não está disponível.

Notificações de desencriptação

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

Confira também

• Exemplo: Encriptar e desencriptar mensagens no Outlook
• 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