Crear un complemento de cifrado de Outlook

Implementar la funcionalidad de cifrado y descifrado personalizados 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 de contenido y las notificaciones de error.

Información general sobre los flujos de trabajo de cifrado y descifrado

Sugerencia

  • Los flujos de trabajo de cifrado y descifrado implementan la función de activación basada en eventos. Si no está familiarizado con la activación basada en eventos en los complementos de Outlook, le recomendamos que primero obtenga información sobre la característica y su implementación. Para obtener más información, consulte Activar complementos con eventos.
  • El conjunto de requisitos mínimos y las plataformas admitidas pueden variar para cada API recomendada en esta sección. Se recomienda comprobar los requisitos con respecto a los conjuntos de requisitos de la API de JavaScript de Outlook y complementarlos con la documentación de la API específica.

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.

Paso Implementación
El usuario redacta un mensaje y usa el complemento para aplicar las reglas de cifrado Debe implementar su propio protocolo de cifrado para que el complemento pueda proteger el contenido del mensaje y sus datos adjuntos.
El usuario envía el mensaje Implemente un controlador para el evento OnMessageSend de modo que el complemento pueda ejecutar automáticamente el protocolo de cifrado cuando el usuario seleccione Enviar.

Para identificar un mensaje que se cifró con su complemento durante el proceso de descifrado, use las API de encabezados de Internet para agregar un encabezado a un mensaje. La clave de encabezado debe coincidir con el valor especificado en el HeaderName atributo del <elemento LaunchEvent> para el evento OnMessageDecrypt en el manifiesto del complemento. Para obtener más información, consulte Implementar el descifrado mediante la activación basada en eventos.
El destinatario recibe el mensaje cifrado y lo abre Si el destinatario tiene instalado en Outlook el mismo complemento que se usó para cifrar el mensaje, el complemento comprueba si la clave de encabezado incluida en el mensaje coincide con el valor especificado para el OnMessageDecrypt evento en el manifiesto. Este complemento controla el OnMessageDecrypt evento para realizar esta operación automáticamente, de forma que no es necesario implementar manualmente la comprobación. Si los encabezados coinciden, se produce el OnMessageDecrypt evento y se ejecuta su controlador. Para obtener más información, consulte Implementar el descifrado mediante la activación basada en eventos.
El complemento descifra el mensaje Debe implementar su propio protocolo de descifrado en el controlador de OnMessageDecrypt eventos. Mientras el complemento descifra el mensaje y sus datos adjuntos, se muestra una notificación al usuario para avisarle de que el complemento está procesando su mensaje. Este complemento que controla el OnMessageDecrypt evento muestra automáticamente esta notificación, de modo que no tiene que crear una manualmente.
El destinatario ve el mensaje descifrado y sus datos adjuntos, si los hay Una vez completada la operación de descifrado, se mostrará automáticamente al usuario una notificación para avisarle de que el complemento ha terminado de procesar el mensaje. En el OnMessageDecrypt controlador, llame al método event.completed y pásele un objeto MessageDecryptEventCompletedOptions . Con el MessageDecryptEventCompletedOptions objeto, puede especificar si se mostrará el contenido descifrado al destinatario. Para obtener más información, vea Implementar el control de eventos.

Probar un complemento completado

Para ver inmediatamente un complemento de cifrado completo en acción, pruebe la muestra Cifrar y descifrar mensajes en Outlook.

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

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

Entornos admitidos

El OnMessageDecrypt evento se admite en la superficie Mensaje leído. La compatibilidad varía según el cliente y el entorno de Exchange, como se muestra en la tabla siguiente.

Cliente Exchange en línea Edición de suscripción de Exchange (SE) Exchange Server 2019 Exchange Server 2016
Explorador web Compatible No disponible No disponible No disponible
Windows (nuevo) Compatible No disponible No disponible No disponible
Windows (clásico)
Versión 2602 (compilación 19725.20126) y posteriores		 Compatible No disponible No disponible No disponible
Mac No disponible No disponible No disponible No disponible
Android No disponible No disponible No disponible No disponible
iOS No disponible No disponible No disponible No disponible

Configuración del manifiesto

Nota:

El OnMessageDecrypt evento y "extensions.autoRunEvents.events.options.headerName" la propiedad están en vista previa con el manifiesto unificado. No use la característica de descifrado con el manifiesto unificado en un complemento de producción.

En el archivo manifest.json del complemento, debe configurar la matriz y agregarla para habilitar la "extensions.runtimes""extensions.autoRunEvents" activación basada en eventos en el complemento.

  1. Agregue el siguiente objeto a la matriz "extensions.runtimes". Tenga en cuenta lo siguiente sobre este marcado.

    • El "id" del tiempo de ejecución se establece en el nombre "autorun_runtime"descriptivo .
    • La "code" propiedad tiene una propiedad secundaria "page" establecida en un archivo HTML y una propiedad secundaria "script" establecida en un archivo JavaScript. Office usa uno de estos valores en función de la plataforma.
      • Outlook en la Web y el nuevo Outlook en Windows ejecutan el controlador en tiempo de ejecución del explorador, que carga un archivo HTML. Ese archivo, a su vez, contiene una <script> etiqueta que carga el archivo JavaScript.
      • Outlook clásico en Windows ejecuta el controlador de eventos en un tiempo de ejecución solo JavaScript, que carga un archivo JavaScript directamente. Para obtener más información, vea Entornos de ejecución en complementos de Office.
    • La "lifetime" propiedad se establece en "short", lo que significa que el tiempo de ejecución se inicia cuando se desencadena el evento y se cierra cuando se completa el controlador.
    • Las acciones asignan controladores de JavaScript a los OnMessageSend eventos and OnMessageDecrypt .
    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.16"
                }
            ]
        },
        "id": "autorun_runtime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/launchevents.html",
            "script": "https://localhost:3000/launchevents.js"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "onMessageSendHandler",
                "type": "executeFunction"
            },
            {
                "id": "onMessageDecryptHandler",
                "type": "executeFunction"
            }
        ]
    }
],

  2. Agregue la siguiente "autoRunEvents" matriz como propiedad del objeto de la "extensions" matriz. Tenga en cuenta lo siguiente sobre este marcado.

    • Se crea un objeto de evento para cada evento que controla el complemento. En este ejemplo, se crea un objeto de evento para OnMessageSend y otro para OnMessageDecrypt. Ambos eventos usan su nombre "messageSending" de evento manifiesto unificado y "messageDecrypt", como se describe en la tabla de eventos admitidos.
    • Para asegurarse de que se ejecuta el controlador adecuado cuando se produce un evento, el nombre de la función proporcionado en "actionId" debe coincidir con el nombre utilizado en la "id" propiedad del objeto aplicable de la "runtimes.actions" matriz de un paso anterior.
    • La propiedad "options" proporciona configuración adicional para los OnMessageSend eventos and OnMessageDecrypt .
      • Para OnMessageSend, la opción "sendMode" especifica si un usuario puede enviar su mensaje si no cumple las condiciones de un complemento. En este ejemplo, se especifica la "softBlock" opción. Para obtener más información sobre las opciones del modo de envío, consulte la sección "Opciones de modo de envío disponibles" de Controlar los eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes.
      • Para OnMessageDecrypt, la opción "headerName" especifica el nombre de encabezado de Internet utilizado para identificar si el complemento cifró un mensaje. El mismo encabezado se agrega a un mensaje cifrado por el complemento.
    "autoRunEvents": [
    {
        "events": [
          {
              "type": "messageSending",
              "actionId": "onMessageSendHandler",
              "options": {
                  "sendMode": "softBlock"
              }
          },
          {
              "type": "messageDecrypt",
              "actionId": "onMessageDecryptHandler",
              "options": {
                  "headerName": "contoso-encrypted"
              }
          }
        ]
    }
]

Implementar la gestión de eventos

El OnMessageDecrypt controlador de eventos se utiliza para ejecutar la operación de descifrado y determinar si se va a mostrar el contenido descifrado de un mensaje.

  • Para asegurarse de que el controlador se ejecuta cuando se produce el OnMessageDecrypt evento, llame Office.actions.associate al archivo JavaScript donde está implementado 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 para indicar al cliente que el complemento ha terminado de procesar el 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.

Nota:

Tenga en cuenta lo siguiente al crear un complemento basado en eventos para Outlook clásico en Windows.

  • Las importaciones no se admiten actualmente en el archivo JavaScript que contiene el controlador de eventos.
  • Cuando se ejecuta la función de JavaScript especificada en el manifiesto para controlar un evento, se codifica Office.onReady() y Office.initialize no se ejecuta. En su lugar, se recomienda agregar al controlador de eventos cualquier lógica de inicio que necesite el controlador de eventos, como comprobar la versión de Outlook del usuario.

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

Sugerencia

Cuando las imágenes se agregan a un mensaje como datos adjuntos insertados, se les asigna automáticamente un identificador de contenido. En el cuerpo de un mensaje, el identificador de contenido de datos adjuntos insertados se especifica en el src atributo del <img> elemento similar al ejemplo siguiente.

<img width=96 height=96 id="Picture_1" src="cid:image001.png@01DC1E6F.FC7C7410">

Para identificar fácilmente y proporcionar estos datos adjuntos en línea durante el descifrado, se recomienda guardar los identificadores de contenido de los datos adjuntos en línea en el encabezado del mensaje durante el cifrado. Llame a Office.context.mailbox.item.getAttachmentsAsync para obtener el identificador de contenido de datos adjuntos en línea. A continuación, llame a Office.context.mailbox.item.internetHeaders.setAsync para guardar el identificador en el encabezado del mensaje.

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

La compatibilidad para descifrar datos adjuntos de elementos de Outlook (Office.MailboxEnums.AttachmentType.Item), especialmente datos adjuntos de correo electrónico, está disponible para su versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una versión preliminar de esta característica en Outlook clásico en Windows, debes 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 de 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, actualiza 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
        }
    ];
    ...

Personalizar los 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 su versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una versión preliminar de esta característica en Outlook clásico en Windows, debes 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 de 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 en falsey 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 event.completed llamada del complemento. El mensaje personalizado tiene el prefijo "Error del nombre> del <complemento:". Si no se puede mostrar el mensaje personalizado, se mostrará 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."
});

Administrar 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 vista previa en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una versión preliminar de esta característica en Outlook clásico en Windows, debes 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 de canal beta para acceder a las compilaciones beta de Office.

Para limitar la impresión, copia o guardado de 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 propiedad, los accessControls 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
        }
    });

Nota:

  • En Outlook en la Web, establecer la allowCopyPaste propiedad en también impide que false los usuarios capturen su pantalla en forma de capturas de pantalla o grabaciones. La directiva de captura de pantalla permanece en vigor hasta que el usuario vuelve a cargar la pestaña del navegador de Outlook.
  • En Outlook en la Web y en el nuevo Outlook en Windows, al establecer la allowPrint propiedad en false se deshabilita el menú contextual (que proporciona opciones como Copiar, Seleccionar todo e Imprimir). Si la allowCopyPaste propiedad está establecida en true, el usuario puede seguir copiando contenido presionando Ctrl+C, pero la opción Copiar del menú contextual no está disponible.

Comportamiento y limitaciones

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

  • Puesto que cada complemento usa su propio protocolo de cifrado, un mensaje solo puede ser descifrado por el mismo complemento que lo cifró. 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.

    Mensaje de marcador de posición de ejemplo de un mensaje cifrado.

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

  • Un mensaje cifrado debe descifrarse primero antes de que un usuario pueda responderlo o reenviarlo. Un usuario no puede responder ni reenviar un mensaje cifrado mientras se descifra.

  • 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 abrir el mensaje de nuevo 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 vista previa en Outlook en la Web y en Windows (nuevo y clásico). Para obtener más información, consulte Descifrar datos adjuntos de elementos de Outlook (versión preliminar).

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

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

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

Notificaciones de descifrado

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

Notificación Escenario
<El nombre> del complemento no está disponible y no puede procesar el mensaje en este momento. Se aplica solo a la versión clásica de Outlook en Windows. Esta notificación se muestra cuando no se puede cargar el complemento porque un error ha impedido que el complemento se cargue o el cliente o la máquina del usuario están desconectados.
<El nombre> del complemento no pudo procesar el mensaje. Se ha producido un error mientras el complemento descifraba el mensaje. Para volver a intentar la operación de descifrado, el destinatario debe cambiar a otro mensaje y, a continuación, abrir de nuevo el mensaje cifrado para invocar el OnMessageDecrypt evento.
<Nombre> del complemento El complemento está descifrando el mensaje. El complemento controla el OnMessageDecrypt evento para descifrar el mensaje.
Este mensaje se cifra mediante <el nombre> de complemento. Esta notificación se muestra a los destinatarios que no tienen instalado el complemento de cifrado necesario. Para proporcionar instrucciones sobre cómo descifrar el mensaje, incluya un mensaje de marcador de posición en el cuerpo del mensaje cifrado. Para obtener más información, consulte Comportamiento y limitaciones.
<Nombre> del complemento El complemento ha descifrado el mensaje. El complemento descifró correctamente el contenido del mensaje. El usuario ya puede ver el mensaje y sus datos adjuntos.
<El nombre> del complemento tarda más tiempo del esperado en procesar el mensaje. El complemento se ha estado ejecutando durante más de cinco segundos, pero menos de cinco minutos.
<Se ha agotado el tiempo de espera para el nombre> del complemento. Para volver a intentarlo, seleccione otro correo electrónico y vuelva a este mensaje. El complemento agota el tiempo de espera después de ejecutarse durante cinco minutos. Para volver a intentar la operación de descifrado, el destinatario debe cambiar a otro mensaje y, a continuación, abrir de nuevo el mensaje cifrado para invocar el OnMessageDecrypt evento.
<Se ha agotado el tiempo de espera para el nombre> del complemento. (versión preliminar) El complemento agota el tiempo de espera después de ejecutarse durante cinco minutos. Esta notificación incluye una acción de reintento para que el destinatario pueda reintentar la operación de descifrado sin cambiar a otro mensaje. Esta característica de reintento está disponible en versión preliminar en Outlook en la Web y en Windows (nuevo y clásico). Para obtener una versión preliminar de esta característica en Outlook clásico en Windows, debes 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 de canal beta para acceder a las compilaciones beta de Office.
<El nombre> del complemento no puede procesar este mensaje porque está protegido por una característica de seguridad integrada. El complemento intenta procesar un mensaje que ya está protegido por DRM o S/MIME.
Mensaje de error personalizado (versión preliminar) Se ha producido un error mientras el complemento descifraba el mensaje. Para volver a intentar la operación de descifrado, el destinatario debe cambiar a otro mensaje y, a continuación, abrir de nuevo el mensaje cifrado para invocar el OnMessageDecrypt evento. Para obtener instrucciones sobre cómo personalizar un mensaje de error para la operación de descifrado, consulte Personalización de mensajes de error para la operación de descifrado (versión preliminar).

Vea también

  • Last updated on