Créer un complément Outlook de chiffrement

Implémentez une fonctionnalité de chiffrement et de déchiffrement personnalisée dans un complément Outlook pour sécuriser les communications par e-mail. Cet OnMessageDecrypt événement permet à votre complément d’identifier automatiquement les messages chiffrés et de gérer le déchiffrement, l’affichage du contenu et les notifications d’erreur.

Vue d’ensemble des workflows de chiffrement et de déchiffrement

Le tableau suivant fournit une vue d’ensemble des flux de travail de chiffrement et de déchiffrement d’un complément Outlook. Il identifie également si une étape nécessite une solution personnalisée ou si elle est prise en charge par la bibliothèque d’API Office JavaScript (Office.js).

Essayer un complément terminé

Pour voir immédiatement un complément de chiffrement terminé en action, essayez l’exemple Chiffrer et déchiffrer les messages dans Outlook.

Implémenter le déchiffrement à l’aide de l’activation en fonction des événements

Vous devez implémenter vos propres protocoles de chiffrement et de déchiffrement. Le complément doit également être configuré pour gérer l’événement OnMessageDecrypt afin de déterminer facilement quand votre complément peut déchiffrer un message et afficher le contenu déchiffré. Pour implémenter l’événement OnMessageDecrypt , vous devez :

1. Configurez le manifeste du complément.
2. Implémenter la gestion des événements.

Environnements pris en charge

L’événement OnMessageDecrypt est pris en charge sur la surface de lecture du message. La prise en charge varie selon le client et l’environnement Exchange, comme indiqué dans le tableau suivant.

Configurer le manifeste

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

Implémenter la gestion des événements

Le OnMessageDecrypt gestionnaire d’événements est utilisé pour exécuter l’opération de déchiffrement et déterminer s’il faut afficher le contenu déchiffré d’un message.

• Pour vous assurer que votre gestionnaire s’exécute lorsque l’événement OnMessageDecrypt se produit, appelez Office.actions.associate le fichier JavaScript dans lequel le gestionnaire est implémenté. Cela mappe le nom du gestionnaire spécifié dans l’attribut FunctionName de l’élément <LaunchEvent> dans le manifeste à son homologue JavaScript.
• Une fois l’opération de déchiffrement terminée, vous devez appeler event.completed pour signaler au client que votre complément a terminé de traiter l’événement OnMessageDecrypt . Pour afficher le contenu déchiffré d’un message et de ses pièces jointes, transmettez un objet MessageDecryptEventCompletedOptions à l’appel event.completed et définissez sa propriété allowEvent sur true. Spécifiez ensuite le contenu déchiffré du message dans les propriétés emailBody et attachments de l’objet. Vous pouvez également spécifier les données dont votre complément peut avoir besoin pour le traitement dans la propriété contextData . Par exemple, vous pouvez stocker des en-têtes Internet personnalisés pour déchiffrer des messages dans des scénarios de réponse et de transfert.

Voici un exemple de gestionnaire d’événements OnMessageDecrypt .

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

Déchiffrer les pièces jointes aux éléments Outlook (préversion)

La prise en charge du déchiffrement des pièces jointes Outlook (Office.MailboxEnums.AttachmentType.Item), en particulier des pièces jointes de courrier électronique, est disponible en préversion dans Outlook sur le web et sur Windows (nouveau et classique). Pour afficher un aperçu de cette fonctionnalité dans Outlook classique sur Windows, vous devez installer la version 2606 (Build 20114.15110) ou ultérieure. Rejoignez ensuite le programme Microsoft 365 Insider et sélectionnez l’option Canal bêta pour accéder aux builds bêta d’Office. Pour tester cette fonctionnalité à l’aide de l’exemple de code de cet article, mettez à jour la fonction à l’aide onMessageDecryptHandler du code suivant.

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

Personnaliser les messages d’erreur pour l’opération de déchiffrement (préversion)

Des messages d’erreur personnalisés pour les opérations de déchiffrement ayant échoué peuvent être aperçus dans Outlook sur le web et sur Windows (nouveau et classique). Pour afficher un aperçu de cette fonctionnalité dans Outlook classique sur Windows, vous devez installer la version 2606 (Build 20114.15110) ou ultérieure. Rejoignez ensuite le programme Microsoft 365 Insider et sélectionnez l’option Canal bêta pour accéder aux builds bêta d’Office.

Si l’opération de déchiffrement échoue, la allowEvent propriété de l’appel event.completed est définie sur false, et Outlook affiche la notification par défaut suivante à l’utilisateur : «< Le nom> du complément n’a pas pu traiter votre message ». Pour spécifier un message d’erreur personnalisé, définissez la propriété errorMessage de l’appel event.completed de votre complément. Votre message personnalisé est précédé de « Erreur du nom> du <complément : ». Si votre message personnalisé ne peut pas être affiché, la notification par défaut s’affiche à la place.

L’exemple de code suivant montre comment spécifier un message d’erreur personnalisé pour votre complément de déchiffrement.

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

Gérer la distribution du contenu déchiffré (préversion)

Pour empêcher la distribution non autorisée de contenu déchiffré, les options de contrôle d’accès sont disponibles en préversion dans Outlook sur le web et sur Windows (nouveau et classique). Pour afficher un aperçu de cette fonctionnalité dans Outlook classique sur Windows, vous devez installer la version 2606 (Build 20114.15110) ou ultérieure. Rejoignez ensuite le programme Microsoft 365 Insider et sélectionnez l’option Canal bêta pour accéder aux builds bêta d’Office.

Pour limiter l’impression, la copie ou l’enregistrement de contenu déchiffré, incluez la propriété accessControls de l’appel event.completed . Ensuite, définissez les propriétés allowPrint, allowCopyPaste et allowSave sur false. Si la propriété n’est pas spécifiée, les accessControls contrôles d’accès sont définis par défaut sur true.

Pour tester cette fonctionnalité à l’aide de l’exemple de code de cet article, mettez à jour l’appel event.completed de la onMessageDecryptHandler fonction à l’aide du code suivant.

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

Comportement et limitations

• Tenez compte des comportements et des limites des compléments basés sur des événements. Pour plus d’informations, voir Activer des compléments avec des événements.

• Dans la mesure où chaque complément utilise son propre protocole de chiffrement, un message ne peut être déchiffré que par le même complément que celui qui l’a chiffré. Lorsqu’un utilisateur n’a pas installé le complément requis pour déchiffrer un message, une notification l’avertit que le message est chiffré. Pour guider l’utilisateur tout au long du processus de déchiffrement, personnalisez un message d’espace réservé pour le corps du message chiffré. Le message d’espace réservé peut inclure des informations sur l’installation de votre complément. Pour définir le corps du message pendant le processus de chiffrement, appelez Office.context.mailbox.item.body.setAsync.

  

• Pour assurer la sécurité et la confidentialité des données, le contenu déchiffré n’est pas stocké sur le client Outlook. Le contenu d’un message chiffré est déchiffré chaque fois qu’un utilisateur l’ouvre.

• Un message chiffré doit d’abord être déchiffré avant qu’un utilisateur puisse y répondre ou le transférer. Un utilisateur ne peut pas répondre ou transférer un message chiffré pendant qu’il est en cours de déchiffrement.

• Si un utilisateur accède à un autre élément de courrier pendant le déchiffrement d’un message chiffré, le processus de déchiffrement cesse de fonctionner. L’utilisateur doit sélectionner ou rouvrir le message pour activer le processus de déchiffrement.

• Lors de la réponse ou du transfert de messages chiffrés, les brouillons sont enregistrés non chiffrés dans le dossier Brouillons .

• La attachments propriété de la event.completed méthode ne prend pas en charge les pièces jointes de type Office.MailboxEnums.AttachmentType.Item, sauf pour l’aperçu dans Outlook sur le web et sur Windows (nouveau et classique). Pour plus d’informations, voir Déchiffrer les pièces jointes aux éléments Outlook (préversion).

• Les compléments de chiffrement personnalisés ne peuvent pas chiffrer les messages déjà protégés par DRM ou S/MIME.

• Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows, lorsque les messages chiffrés sont regroupés par conversation, seul le message actuellement sélectionné dans le thread de conversation est déchiffré. Les autres messages du fil de conversation restent chiffrés jusqu’à ce qu’ils soient sélectionnés.

• Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows, les utilisateurs peuvent uniquement télécharger un message déchiffré au format EML. L’option de téléchargement au format MSG n’est pas disponible.

Notifications de déchiffrement

Les compléments qui gèrent l’événement affichent automatiquement des OnMessageDecrypt notifications dans certains scénarios de déchiffrement, comme décrit dans le tableau suivant.

Voir aussi

• Exemple : chiffrer et déchiffrer des messages dans Outlook
• Confidentialité et sécurité pour les compléments Office
• Activer des compléments avec des événements
• Résoudre les problèmes liés aux modules complémentaires de signalement d'événements et de spams
• Obtenir et définir des en-têtes Internet sur un message dans un complément Outlook
• Gérer les étiquettes de confidentialité dans les compléments Office