Créer un complément Outlook de chiffrement

Implémentez des fonctionnalités de chiffrement et de déchiffrement personnalisées dans un complément Outlook pour sécuriser les communications par e-mail. L’événement OnMessageDecrypt 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

Conseil

  • Les workflows de chiffrement et de déchiffrement implémentent la fonctionnalité d’activation basée sur les événements. Si vous n’êtes pas familiarisé avec l’activation basée sur les événements dans les compléments Outlook, nous vous recommandons d’en savoir plus sur la fonctionnalité et son implémentation. Pour plus d’informations, consultez Activer des compléments avec des événements.
  • L’ensemble minimal de conditions requises et les plateformes prises en charge peuvent varier pour chaque API recommandée dans cette section. Nous vous recommandons de vérifier toutes les exigences par rapport aux ensembles de conditions requises de l’API JavaScript Outlook et de les compléter avec la documentation de l’API spécifique.

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

Étape Implémentation
L’utilisateur compose un message et utilise votre complément pour appliquer des règles de chiffrement Vous devez implémenter votre propre protocole de chiffrement afin que le complément puisse sécuriser le contenu du message et ses pièces jointes.
L’utilisateur envoie le message Implémentez un gestionnaire pour l’événement OnMessageSend afin que votre complément puisse exécuter automatiquement votre protocole de chiffrement lorsque l’utilisateur sélectionne Envoyer.

Pour identifier un message chiffré à l’aide de votre complément pendant le processus de déchiffrement, utilisez les API d’en-têtes Internet pour ajouter un en-tête à un message. La clé d’en-tête doit correspondre à la valeur spécifiée dans l’attribut HeaderName de l’élément <LaunchEvent> pour l’événement OnMessageDecrypt dans le manifeste du complément. Pour plus d’informations, consultez Implémenter le déchiffrement à l’aide de l’activation basée sur les événements.
Le destinataire reçoit le message chiffré et l’ouvre Si le destinataire a le même complément que celui utilisé pour chiffrer le message installé dans Outlook, le complément vérifie si la clé d’en-tête incluse dans le message correspond à la valeur spécifiée pour l’événement OnMessageDecrypt dans le manifeste. Cette opération est effectuée automatiquement par un complément qui gère l’événementOnMessageDecrypt, afin que vous n’ayez pas à implémenter manuellement le case activée. Si les en-têtes correspondent, l’événement OnMessageDecrypt se produit et son gestionnaire s’exécute. Pour plus d’informations, consultez Implémenter le déchiffrement à l’aide de l’activation basée sur les événements.
Le complément déchiffre le message Vous devez implémenter votre propre protocole de déchiffrement dans le gestionnaire d’événements OnMessageDecrypt . Pendant que votre complément déchiffre le message et ses pièces jointes, une notification est présentée à l’utilisateur pour l’avertir que son message est en cours de traitement par le complément. Cette notification est automatiquement affichée par un complément qui gère l’événement OnMessageDecrypt , afin que vous n’ayez pas à en créer un manuellement.
Le destinataire affiche le message déchiffré et ses pièces jointes, le cas échéant Une fois l’opération de déchiffrement terminée, une notification s’affiche automatiquement à l’utilisateur pour l’avertir que le complément a terminé le traitement du message. Dans votre OnMessageDecrypt gestionnaire, appelez la méthode event.completed et passez-lui un objet MessageDecryptEventCompletedOptions . Avec l’objet MessageDecryptEventCompletedOptions , vous pouvez spécifier s’il faut afficher le contenu déchiffré au destinataire. Pour plus d’informations, consultez Implémenter la gestion des événements.

Essayer un complément terminé

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

Implémenter le déchiffrement à l’aide de l’activation basée sur les é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.

Client Exchange Online Exchange Subscription Edition (SE) Exchange Server 2019 Exchange Server 2016
Navigateur Web Pris en charge Non disponible Non disponible Non disponible
Windows (nouveau) Pris en charge Non disponible Non disponible Non disponible
Windows (classique)
Version 2602 (build 19725.20126) et versions ultérieures		 Pris en charge Non disponible Non disponible Non disponible
Mac Non disponible Non disponible Non disponible Non disponible
Android Non disponible Non disponible Non disponible Non disponible
iOS Non disponible Non disponible Non disponible Non disponible

Configurer le manifeste

Remarque

L’événement OnMessageDecrypt et "extensions.autoRunEvents.events.options.headerName" la propriété sont en préversion avec le manifeste unifié. N’utilisez pas la fonctionnalité de déchiffrement avec le manifeste unifié dans un complément de production.

Dans le fichier manifest.json de votre complément, vous devez configurer le "extensions.runtimes" tableau et ajouter le tableau pour activer l’activation "extensions.autoRunEvents" basée sur les événements dans votre complément.

  1. Ajoutez l’objet suivant au "extensions.runtimes" tableau. Notez les points suivants concernant ce balisage.

    • Le "id" du runtime est défini sur le nom "autorun_runtime"descriptif .
    • La "code" propriété a une propriété enfant "page" qui est définie sur un fichier HTML et une propriété enfant "script" qui est définie sur un fichier JavaScript. Office utilise l’une de ces valeurs en fonction de la plateforme.
      • Outlook sur le web et le nouvel Outlook sur Windows exécutent le gestionnaire dans un runtime de navigateur, qui charge un fichier HTML. Ce fichier, à son tour, contient une <script> balise qui charge le fichier JavaScript.
      • Outlook classique sur Windows exécute le gestionnaire d’événements dans un runtime JavaScript uniquement, qui charge directement un fichier JavaScript. Pour plus d’informations, voir Runtimes dans les compléments Office.
    • La "lifetime" propriété est définie sur "short", ce qui signifie que le runtime démarre lorsque l’événement est déclenché et s’arrête lorsque le gestionnaire se termine.
    • Les actions mappent les gestionnaires JavaScript aux OnMessageSend événements et 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. Ajoutez le tableau suivant "autoRunEvents" en tant que propriété de l’objet dans le "extensions" tableau. Notez les points suivants concernant ce balisage.

    • Un objet event est créé pour chaque événement géré par le complément. Dans cet exemple, un objet événement est créé pour OnMessageSend et un autre pour OnMessageDecrypt. Les deux événements utilisent leur nom d’événement manifeste unifié, "messageSending" et "messageDecrypt", comme décrit dans le tableau des événements pris en charge.
    • Pour vous assurer que le gestionnaire approprié s’exécute lorsqu’un événement se produit, le nom de fonction fourni dans "actionId" doit correspondre au nom utilisé dans la "id" propriété de l’objet applicable dans le "runtimes.actions" tableau d’une étape précédente.
    • La propriété « options » fournit une configuration supplémentaire pour les OnMessageSend événements et OnMessageDecrypt . 
    "autoRunEvents": [
    {
        "events": [
          {
              "type": "messageSending",
              "actionId": "onMessageSendHandler",
              "options": {
                  "sendMode": "softBlock"
              }
          },
          {
              "type": "messageDecrypt",
              "actionId": "onMessageDecryptHandler",
              "options": {
                  "headerName": "contoso-encrypted"
              }
          }
        ]
    }
]

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 dans le fichier JavaScript où 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 équivalent JavaScript.
  • Une fois l’opération de déchiffrement terminée, vous devez appeler pour signaler event.completed au client que votre complément a terminé le traitement de l’événement OnMessageDecrypt . Pour afficher le contenu déchiffré d’un message et de ses pièces jointes, passez un objet MessageDecryptEventCompletedOptions à l’appel event.completed et définissez sa propriété allowEvent sur true. Ensuite, spécifiez le contenu déchiffré du message dans les propriétés emailBody et pièces jointes de l’objet. Vous pouvez également spécifier toutes 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 les messages dans les scénarios de réponse et de transfert.

Remarque

Tenez compte des points suivants lors de la création d’un complément basé sur des événements pour Outlook classique sur Windows.

  • Les importations ne sont actuellement pas prises en charge dans le fichier JavaScript contenant le gestionnaire d’événements.
  • Lorsque la fonction JavaScript spécifiée dans le manifeste pour gérer un événement s’exécute, le code dans Office.onReady() et Office.initialize n’est pas exécuté. Nous vous recommandons d’ajouter au gestionnaire d’événements toute logique de démarrage requise par le gestionnaire d’événements, telle que la vérification de la version d’Outlook de l’utilisateur.

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

Conseil

Lorsque des images sont ajoutées à un message en tant que pièces jointes inline, un ID de contenu leur est automatiquement attribué. Dans le corps d’un message, l’ID de contenu d’une pièce jointe inline est spécifié dans l’attribut src de l’élément <img> , comme dans l’exemple suivant.

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

Pour identifier et fournir facilement ces pièces jointes inline lors du déchiffrement, nous vous recommandons d’enregistrer les ID de contenu des pièces jointes inline dans l’en-tête du message pendant le chiffrement. Appelez Office.context.mailbox.item.getAttachmentsAsync pour obtenir l’ID de contenu d’une pièce jointe inline. Ensuite, appelez Office.context.mailbox.item.internetHeaders.setAsync pour enregistrer l’ID dans l’en-tête du message.

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

La prise en charge du déchiffrement des pièces jointes d’éléments Outlook (Office.MailboxEnums.AttachmentType.Itemen particulier les 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 une version ultérieure. Ensuite, rejoignez 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 onMessageDecryptHandler fonction avec le 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)

Les messages d’erreur personnalisés pour les opérations de déchiffrement ayant échoué 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 une version ultérieure. Ensuite, rejoignez 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 de event.completed 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 une version ultérieure. Ensuite, rejoignez 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 du 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 accessControls propriété n’est pas spécifiée, les contrôles d’accès par défaut sont 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 avec le code suivant.

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

Remarque

  • Dans Outlook sur le web, la définition de la allowCopyPaste propriété sur false empêche également les utilisateurs de capturer leur écran sous la forme de captures d’écran ou d’enregistrements. La stratégie de capture d’écran reste en vigueur jusqu’à ce que l’utilisateur recharge l’onglet du navigateur Outlook.
  • Dans Outlook sur le web et le nouvel Outlook sur Windows, la définition de la allowPrint propriété false sur désactive le menu contextuel (qui fournit des options telles que Copier, Sélectionner tout et Imprimer). Si la propriété a la allowCopyPaste valeur true, l’utilisateur peut toujours copier du contenu en appuyant sur Ctrl+C, mais l’option Copier dans le menu contextuel n’est pas disponible.

Comportement et limitations

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

  • Étant donné que 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.

    Exemple de message d’espace réservé d’un message chiffré.

  • Pour garantir 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 déchiffré.

  • Si un utilisateur accède à un autre élément de courrier pendant qu’un message chiffré est déchiffré, le processus de déchiffrement cesse de s’exécuter. L’utilisateur doit sélectionner ou ouvrir à nouveau 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, à l’exception de 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 d’éléments Outlook (préversion) .

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

  • Dans Outlook sur le web et le nouvel 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 thread de conversation restent chiffrés jusqu’à ce qu’ils soient sélectionnés.

  • Dans Outlook sur le web et le nouvel 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 OnMessageDecrypt affichent automatiquement des notifications dans certains scénarios de déchiffrement, comme décrit dans le tableau suivant.

Notification Scénario
<Le nom> du complément n’est pas disponible et ne peut pas traiter votre message pour l’instant. S’applique uniquement à Outlook classique sur Windows. Cette notification s’affiche lorsque le chargement du complément échoue, car une erreur a empêché le chargement du complément ou parce que le client ou l’ordinateur de l’utilisateur est hors connexion.
<Le nom> du complément n’a pas pu traiter votre message. Une erreur s’est produite lors du déchiffrement du message par le complément. Pour réessayer l’opération de déchiffrement, le destinataire doit basculer vers un autre message, puis ouvrir à nouveau le message chiffré pour appeler l’événement OnMessageDecrypt .
<Le nom> du complément déchiffre votre message. Le complément gère l’événement OnMessageDecrypt pour déchiffrer le message.
Ce message est chiffré par <le nom du complément> . Cette notification s’affiche pour les destinataires qui n’ont pas le complément de chiffrement nécessaire installé. Pour fournir des conseils sur la façon de déchiffrer le message, incluez un message d’espace réservé dans le corps du message chiffré. Pour plus d’informations, consultez Comportement et limitations.
<Le nom> du complément a déchiffré votre message. Le complément a correctement déchiffré le contenu du message. L’utilisateur peut désormais afficher le message et ses pièces jointes.
<Le nom> du complément prend plus de temps que prévu pour traiter votre message. Le complément s’exécute depuis plus de cinq secondes, mais moins de cinq minutes.
<Le nom> du complément a expiré. Pour réessayer, sélectionnez un autre e-mail, puis revenez à ce message. Le complément expire après une exécution de cinq minutes. Pour réessayer l’opération de déchiffrement, le destinataire doit basculer vers un autre message, puis ouvrir à nouveau le message chiffré pour appeler l’événement OnMessageDecrypt .
<Le nom> du complément a expiré. (préversion) Le complément expire après une exécution de cinq minutes. Cette notification inclut une action Réessayer afin que le destinataire puisse réessayer l’opération de déchiffrement sans passer à un autre message. Cette fonctionnalité de nouvelle tentative 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 une version ultérieure. Ensuite, rejoignez le programme Microsoft 365 Insider et sélectionnez l’option Canal bêta pour accéder aux builds bêta d’Office.
<Le nom> du complément ne peut pas traiter ce message, car il est protégé par une fonctionnalité de sécurité intégrée. Le complément tente de traiter un message déjà protégé par DRM ou S/MIME.
Message d’erreur personnalisé (préversion) Une erreur s’est produite lors du déchiffrement du message par le complément. Pour réessayer l’opération de déchiffrement, le destinataire doit basculer vers un autre message, puis ouvrir à nouveau le message chiffré pour appeler l’événement OnMessageDecrypt . Pour obtenir des conseils sur la façon de personnaliser un message d’erreur pour l’opération de déchiffrement, consultez Personnaliser les messages d’erreur pour l’opération de déchiffrement (préversion) .

Voir aussi

  • Last updated on