Criar um suplemento de criptografia do Outlook

Implemente a funcionalidade de criptografia e descriptografia personalizadas em um suplemento do Outlook para proteger as comunicações por email. O OnMessageDecrypt evento permite que o suplemento identifique automaticamente as mensagens criptografadas e manipule a descriptografia, a exibição de conteúdo e as notificações de erro.

Visão geral dos fluxos de trabalho de criptografia e descriptografia

A tabela a seguir fornece uma visão geral dos fluxos de trabalho de criptografia e descriptografia de um suplemento do Outlook. Ele também identifica se uma etapa requer uma solução personalizada ou se é compatível com a biblioteca de APIs JavaScript (Office.js) do Office.

Experimentar um suplemento concluído

Para ver imediatamente um suplemento de criptografia concluído em ação, experimente o exemplo Criptografar e descriptografar mensagens no Outlook.

Implementar a descriptografia usando a ativação baseada em eventos

Você deve implementar seus próprios protocolos de criptografia e descriptografia. O suplemento também deve ser configurado para manipular o OnMessageDecrypt evento para determinar convenientemente quando seu suplemento pode descriptografar uma mensagem e exibir o conteúdo descriptografado. Para implementar o OnMessageDecrypt evento, você deve:

1. Configure o manifesto do suplemento.
2. Implementar a manipulação de eventos.

Ambientes com suporte

O OnMessageDecrypt evento tem suporte na superfície de Leitura de Mensagem. O suporte varia de acordo com o cliente e o ambiente do Exchange, conforme mostrado na tabela a seguir.

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 a manipulação de eventos

O OnMessageDecrypt manipulador de eventos é usado para executar a operação de descriptografia e determinar se o conteúdo descriptografado de uma mensagem deve ser exibido.

• Para garantir que o manipulador seja executado quando o OnMessageDecrypt evento ocorrer, chame Office.actions.associate o arquivo JavaScript em que o manipulador está implementado. Isso mapeia o nome do manipulador especificado no FunctionName atributo do <LaunchEvent> elemento no manifesto para sua contraparte JavaScript.
• Depois que a operação de descriptografia for concluída, você deverá ligar event.completed para sinalizar ao cliente que o suplemento concluiu o OnMessageDecrypt processamento do evento. Para exibir o conteúdo descriptografado de uma mensagem e seus anexos, passe um objeto MessageDecryptEventCompletedOptions para a event.completed chamada e defina sua propriedade allowEvent como true. Em seguida, especifique o conteúdo descriptografado da mensagem nas propriedades emailBody e attachments do objeto. Você também pode especificar quaisquer dados que seu suplemento possa precisar processar na propriedade contextData . Por exemplo, você pode armazenar cabeçalhos personalizados da Internet para descriptografar mensagens em cenários de resposta e encaminhamento.

Veja a seguir um exemplo de um OnMessageDecrypt manipulador 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);

Descriptografar anexos de item do Outlook (visualização)

O suporte para descriptografar anexos de itens do Outlook (Office.MailboxEnums.AttachmentType.Item), especialmente anexos de email, está disponível para visualização no Outlook na Web e no Windows (novo e clássico). Para visualizar esse recurso no Outlook clássico no Windows, você deve instalar a versão 2606 (Build 20114.15110) ou posterior. Em seguida, ingresse no programa Microsoft 365 Insider e selecione a opção Canal Beta para acessar as compilações beta do Office. Para testar esse recurso usando o código de exemplo neste artigo, atualize a onMessageDecryptHandler função com o código a seguir.

    // 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 descriptografia (versão prévia)

Mensagens de erro personalizadas para operações de descriptografia com falha estão disponíveis para visualização no Outlook na Web e no Windows (novo e clássico). Para visualizar esse recurso no Outlook clássico no Windows, você deve instalar a versão 2606 (Build 20114.15110) ou posterior. Em seguida, ingresse no programa Microsoft 365 Insider e selecione a opção Canal Beta para acessar as compilações beta do Office.

Se a operação de descriptografia falhar, a allowEventevent.completed propriedade da chamada será definida como falsee o Outlook mostrará a seguinte notificação padrão ao usuário: "<O nome> do suplemento falhou ao processar sua mensagem". Para especificar uma mensagem de erro personalizada, defina a propriedade errorMessage da chamada do event.completed suplemento. Sua mensagem personalizada é prefixada com "Erro do nome> do <suplemento:". Se sua mensagem personalizada não puder ser mostrada, a notificação padrão será mostrada em vez disso.

O exemplo de código a seguir mostra como especificar uma mensagem de erro personalizada para o suplemento de descriptografia.

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

Gerenciar a distribuição de conteúdo descriptografado (versão prévia)

Para ajudar a impedir a distribuição não autorizada de conteúdo descriptografado, as opções de controle de acesso estão disponíveis para visualização no Outlook na Web e no Windows (novo e clássico). Para visualizar esse recurso no Outlook clássico no Windows, você deve instalar a versão 2606 (Build 20114.15110) ou posterior. Em seguida, ingresse no programa Microsoft 365 Insider e selecione a opção Canal Beta para acessar as compilações beta do Office.

Para limitar a impressão, a cópia ou o salvamento de conteúdo descriptografado, inclua a propriedade accessControls da event.completed chamada. Em seguida, defina as propriedades allowPrint, allowCopyPaste e allowSave como false. Se a propriedade não for especificada, os accessControls controles de acesso serão padrão para true.

Para testar esse recurso usando o código de exemplo neste artigo, atualize a event.completed chamada da função com o onMessageDecryptHandler código a seguir.

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

Comportamento e limitações

• Esteja ciente dos comportamentos e limitações dos suplementos baseados em eventos. Para saber mais, consulte Ativar suplementos com eventos.

• Como cada suplemento usa seu próprio protocolo de criptografia, uma mensagem só pode ser descriptografada pelo mesmo suplemento que a criptografou. Quando um usuário não tem o suplemento necessário instalado para descriptografar uma mensagem, uma notificação o alerta de que a mensagem está criptografada. Para guiar o usuário pelo processo de descriptografia, personalize uma mensagem de espaço reservado para o corpo da mensagem criptografada. A mensagem de espaço reservado pode incluir informações sobre como instalar o suplemento. Para definir o corpo da mensagem durante o processo de criptografia, chame Office.context.mailbox.item.body.setAsync.

  

• Para garantir a segurança e a confidencialidade dos dados, o conteúdo descriptografado não é armazenado no cliente Outlook. O conteúdo de uma mensagem criptografada é descriptografado sempre que o usuário a abre.

• Uma mensagem criptografada deve ser descriptografada antes que um usuário possa respondê-la ou encaminhá-la. Um usuário não pode responder ou encaminhar uma mensagem criptografada enquanto ela está sendo descriptografada.

• Se um usuário navegar para outro item de email enquanto uma mensagem criptografada estiver sendo descriptografada, o processo de descriptografia deixará de ser executado. O usuário deve selecionar ou abrir a mensagem novamente para ativar o processo de descriptografia.

• Ao responder ou encaminhar mensagens criptografadas, os rascunhos são salvos sem criptografia na pasta Rascunhos .

• A attachments propriedade do event.completed método não dá suporte a anexos do tipo Office.MailboxEnums.AttachmentType.Item, exceto para visualização no Outlook na Web e no Windows (novo e clássico). Para saber mais, consulte Descriptografar anexos de itens do Outlook (versão prévia).

• Suplementos de criptografia personalizados não podem criptografar mensagens que já estão protegidas por DRM ou S/MIME.

• No Outlook na Web e no novo Outlook no Windows, quando as mensagens criptografadas são agrupadas por conversa, somente a mensagem selecionada no momento do thread de conversa é descriptografada. As outras mensagens no thread de conversa permanecem criptografadas até que sejam selecionadas.

• No Outlook na Web e no novo Outlook no Windows, os usuários só podem baixar uma mensagem descriptografada no formato EML. A opção de baixar no formato MSG não está disponível.

Notificações de descriptografia

Os suplementos que manipulam o OnMessageDecrypt evento exibem notificações automaticamente em determinados cenários de descriptografia, conforme descrito na tabela a seguir.

Confira também

• Exemplo: Criptografar e descriptografar mensagens no Outlook
• Privacidade e segurança para Suplementos do Office
• Ativar suplementos com eventos
• Solucionar problemas de suplementos baseados em eventos e de relatórios de spam
• Obter e definir cabeçalhos da Internet em uma mensagem em um suplemento do Outlook
• Gerenciar o rótulo de confidencialidade da sua mensagem ou compromisso no modo de redação