Creación de un complemento de Cifrado de Outlook (versión preliminar)

Implemente la funcionalidad de cifrado y descifrado personalizada en un complemento de Outlook para proteger las comunicaciones por correo electrónico. El OnMessageRead evento permite que el complemento identifique automáticamente los mensajes cifrados y controle el descifrado, la visualización del contenido y las notificaciones de error.

Introducción a los flujos de trabajo de cifrado y descifrado

En la tabla siguiente se proporciona información general sobre los flujos de trabajo de cifrado y descifrado de un complemento de Outlook. También identifica si un paso requiere una solución personalizada o si es compatible con la biblioteca de API de JavaScript (Office.js) de Office.

Implementación del descifrado mediante la activación basada en eventos

Debe implementar sus propios protocolos de cifrado y descifrado. El complemento también debe configurarse para controlar el OnMessageRead evento a fin de determinar convenientemente cuándo el complemento puede descifrar un mensaje y mostrar el contenido descifrado. Para implementar el OnMessageRead evento, debe:

1. Configure el manifiesto del complemento.
2. Implemente el control de eventos.

Entornos admitidos

El OnMessageRead evento se admite en la superficie Lectura de mensajes. La compatibilidad varía según el cliente y el entorno de Exchange, como se muestra en la tabla siguiente.

Vista previa de las API de descifrado en Outlook clásico en Windows

Para obtener una vista previa de las API de descifrado en Outlook clásico en Windows, únase al programa Microsoft 365 Insider y elija el canal beta en el cliente de Outlook. El cliente debe estar en la versión 2510 (compilación 19312.20000) o posterior.

Outlook clásico en Windows incluye una copia local de las versiones de producción y beta de Office.js en lugar de cargar desde la red de entrega de contenido (CDN). De forma predeterminada, se hace referencia a la copia de producción local de la API. Para hacer referencia a la copia beta local de la API, debe configurar el registro del equipo. Esto le permitirá probar las características de vista previa en los controladores de eventos en Outlook clásico en Windows.

1. En el Registro, vaya a HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Si la clave no existe, créela.

2. Cree una entrada denominada EnableBetaAPIsInJavaScript y establezca su valor en 1.

   

Configuración del manifiesto

Para activar el complemento en el OnMessageRead evento, debe configurar el <nodo VersionOverridesV1_1> del archivo demanifest.xml del complemento de la siguiente manera.

• Para ejecutar un complemento basado en eventos en Outlook clásico en Windows, debe especificar el archivo JavaScript que contiene el controlador de eventos en el <elemento secundario Override> del <elemento Runtime> .
• Especifique el OnMessageRead evento en el Type atributo de un <elemento LaunchEvent> . Debe asignar el nombre de función del controlador de eventos al FunctionName atributo del elemento . Para facilitar la comprobación de si el complemento cifró el mensaje, se debe especificar una clave de encabezado en el HeaderName atributo . El mismo encabezado se agrega a un mensaje cifrado por el complemento.

A continuación se muestra un ejemplo de un <VersionOverrides> nodo que implementa el 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>

Implementación del control de eventos

El OnMessageRead controlador de eventos se usa para ejecutar la operación de descifrado y determinar si se debe mostrar el contenido descifrado de un mensaje.

• Para asegurarse de que el controlador se ejecuta cuando se produce el OnMessageRead evento, llame a Office.actions.associate en el archivo JavaScript donde se implementa el controlador. Esto asigna el nombre del controlador especificado en el FunctionName atributo del <LaunchEvent> elemento del manifiesto a su homólogo de JavaScript.
• Una vez finalizada la operación de descifrado, debe llamar event.completed a para indicar al cliente que el complemento ha completado el procesamiento del OnMessageRead evento. Para mostrar el contenido descifrado de un mensaje y sus datos adjuntos, pase un objeto MessageDecryptEventCompletedOptions a la event.completed llamada y establezca su propiedad allowEvent en true. A continuación, especifique el contenido descifrado del mensaje en las propiedades emailBody y attachments del objeto. También puede especificar los datos que el complemento pueda necesitar para su procesamiento en la propiedad contextData . Por ejemplo, puede almacenar encabezados de Internet personalizados para descifrar mensajes en escenarios de respuesta y reenvío.

A continuación se muestra un ejemplo de un OnMessageRead controlador 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);

Comportamiento y limitaciones

• Tenga en cuenta los comportamientos y las limitaciones de los complementos basados en eventos. Para más información, consulte Activación de complementos con eventos.

• Dado que cada complemento usa su propio protocolo de cifrado, el mismo complemento que lo cifró solo puede descifrar un mensaje. Cuando un usuario no tiene instalado el complemento necesario para descifrar un mensaje, una notificación le avisa de que el mensaje está cifrado. Para guiar al usuario a través del proceso de descifrado, personalice un mensaje de marcador de posición para el cuerpo del mensaje cifrado. El mensaje de marcador de posición puede incluir información sobre cómo instalar el complemento. Para establecer el cuerpo del mensaje durante el proceso de cifrado, llame a Office.context.mailbox.item.body.setAsync.

  

• Para garantizar la seguridad y confidencialidad de los datos, el contenido descifrado no se almacena en el cliente de Outlook. El contenido de un mensaje cifrado se descifra cada vez que un usuario lo abre.

• Primero se debe descifrar un mensaje cifrado para que un usuario pueda responderlo o reenviarlo. Un usuario no puede responder ni reenviar un mensaje cifrado mientras se está descifrando.

• Si un usuario navega a otro elemento de correo mientras se descifra un mensaje cifrado, el proceso de descifrado deja de ejecutarse. El usuario debe seleccionar o volver a abrir el mensaje para activar el proceso de descifrado.

• Al responder o reenviar mensajes cifrados, los borradores se guardan sin cifrar en la carpeta Borradores .

Notificaciones de descifrado

Los complementos que controlan el OnMessageRead evento muestran automáticamente notificaciones en determinados escenarios de descifrado, como se describe en la tabla siguiente.

Vea también

• Privacidad y seguridad de complementos de Office
• Activación de complementos con eventos
• Solución de problemas de complementos de informes de correo no deseado y basados en eventos
• Obtener y establecer encabezados de Internet en un mensaje en un complemento de Outlook
• Administrar la etiqueta de confidencialidad del mensaje o cita en modo de redacción