Creación de un complemento de Outlook de cifrado

Implemente la funcionalidad de cifrado y descifrado personalizada en un complemento de Outlook para proteger las comunicaciones por correo electrónico. El OnMessageDecrypt 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.

Prueba de un complemento completado

Para ver inmediatamente un complemento de cifrado completado en acción, pruebe el ejemplo Cifrar y descifrar mensajes en Outlook.

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 OnMessageDecrypt evento a fin de determinar convenientemente cuándo el complemento puede descifrar un mensaje y mostrar el contenido descifrado. Para implementar el OnMessageDecrypt evento, debe:

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

Entornos admitidos

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

Configuración del manifiesto

<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>

Implementación del control de eventos

El OnMessageDecrypt 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 OnMessageDecrypt 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 OnMessageDecrypt 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 OnMessageDecrypt controlador 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);

Descifrar datos adjuntos de elementos de Outlook (versión preliminar)

La compatibilidad con el descifrado de datos adjuntos de elementos de Outlook (Office.MailboxEnums.AttachmentType.Item), especialmente los datos adjuntos de correo electrónico, está disponible para la versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una vista previa de esta característica en Outlook clásico en Windows, debe instalar la versión 2606 (compilación 20114.15110) o posterior. A continuación, únase al programa Microsoft 365 Insider y seleccione la opción Canal beta para acceder a las compilaciones beta de Office. Para probar esta característica con el código de ejemplo de este artículo, actualice la onMessageDecryptHandler función con el código siguiente.

    // 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
        }
    ];
    ...

Personalización de mensajes de error para la operación de descifrado (versión preliminar)

Los mensajes de error personalizados para las operaciones de descifrado con errores están disponibles para la versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una vista previa de esta característica en Outlook clásico en Windows, debe instalar la versión 2606 (compilación 20114.15110) o posterior. A continuación, únase al programa Microsoft 365 Insider y seleccione la opción Canal beta para acceder a las compilaciones beta de Office.

Si se produce un error en la operación de descifrado, la allowEvent propiedad de la event.completed llamada se establece falseen y Outlook muestra la siguiente notificación predeterminada al usuario: "<El nombre> del complemento no pudo procesar el mensaje". Para especificar un mensaje de error personalizado, establezca la propiedad errorMessage de la llamada del event.completed complemento. El mensaje personalizado tiene el prefijo "Error del nombre> del <complemento:". Si no se puede mostrar el mensaje personalizado, se muestra la notificación predeterminada en su lugar.

En el ejemplo de código siguiente se muestra cómo especificar un mensaje de error personalizado para el complemento de descifrado.

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

Administración de la distribución de contenido descifrado (versión preliminar)

Para ayudar a evitar la distribución no autorizada de contenido descifrado, las opciones de control de acceso están disponibles para la versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una vista previa de esta característica en Outlook clásico en Windows, debe instalar la versión 2606 (compilación 20114.15110) o posterior. A continuación, únase al programa Microsoft 365 Insider y seleccione la opción Canal beta para acceder a las compilaciones beta de Office.

Para limitar la impresión, copia o guardado del contenido descifrado, incluya la propiedad accessControls de la event.completed llamada. A continuación, establezca las propiedades allowPrint, allowCopyPaste y allowSave en false. Si no se especifica la accessControls propiedad , los controles de acceso tienen como valor predeterminado true.

Para probar esta característica con el código de ejemplo de este artículo, actualice la event.completed llamada de la onMessageDecryptHandler función con el código siguiente.

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

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 .

• La attachments propiedad del event.completed método no admite datos adjuntos de tipo Office.MailboxEnums.AttachmentType.Item, excepto la versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener más información, vea Descifrado de datos adjuntos de elementos de Outlook (versión preliminar).

• Los complementos de cifrado personalizados no pueden cifrar los mensajes que ya están protegidos por DRM o S/MIME.

• En Outlook en la Web y el nuevo Outlook en Windows, cuando los mensajes cifrados se agrupan por conversación, solo se descifra el mensaje seleccionado actualmente del subproceso de conversación. Los demás mensajes del subproceso de conversación permanecen cifrados hasta que se seleccionan.

• En Outlook en la Web y el nuevo Outlook en Windows, los usuarios solo pueden descargar un mensaje descifrado en el formato EML. La opción para descargar en formato MSG no está disponible.

Notificaciones de descifrado

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

Vea también

• Ejemplo: Cifrado y descifrado de mensajes en Outlook
• 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