创建加密 Outlook 加载项

在 Outlook 外接程序中实现自定义加密和解密功能，以保护电子邮件通信。 该 OnMessageDecrypt 事件允许加载项自动识别加密消息并处理解密、内容显示和错误通知。

加密和解密工作流概述

提示

  • 加密和解密工作流实现基于事件的激活功能。 如果不熟悉 Outlook 加载项中的基于事件的激活，建议首先了解该功能及其实现。 若要了解详细信息，请参阅 使用事件激活加载项。
  • 本部分建议的每个 API 的最低要求集和支持的平台可能会有所不同。 建议针对 Outlook JavaScript API 要求集 验证任何要求，并使用特定 API 的文档对其进行补充。

下表概述了 Outlook 加载项的加密和解密工作流。 它还标识步骤是否需要自定义解决方案或 Office JavaScript (Office.js) API 库支持。

步骤 实现
用户撰写邮件并使用加载项应用加密规则 您必须实现自己的加密协议，以便加载项可以保护邮件及其附件的内容。
用户发送消息 实现 OnMessageSend 事件的处理程序，以便在用户选择 “发送”时，外接程序可以自动运行加密协议。

若要标识在解密过程中使用加载项加密的消息，请使用 Internet 标头 API 向消息添加标头。 标头键必须与加载项清单中 HeaderNameOnMessageDecrypt 事件的 LaunchEvent> 元素的 属性<中指定的值匹配。 有关详细信息，请参阅 使用基于事件的激活实现解密。
收件人接收加密邮件并将其打开 如果收件人具有用于加密 Outlook 中安装的邮件的相同加载项，则外接程序会检查邮件中包含的标头密钥是否与清单中为 OnMessageDecrypt 事件指定的值匹配。 此操作由处理OnMessageDecrypt事件的加载项自动完成，因此无需手动实现检查。 如果标头匹配，则 OnMessageDecrypt 发生事件，并运行其处理程序。 有关详细信息，请参阅 使用基于事件的激活实现解密。
加载项解密消息 必须在事件处理程序中 OnMessageDecrypt 实现自己的解密协议。 当加载项解密邮件及其附件时，会向用户显示一条通知，提醒他们加载项正在处理其邮件。 此通知由处理 OnMessageDecrypt 事件的加载项自动显示，因此无需手动创建一个。
收件人查看解密的邮件及其附件（如果有） 解密操作完成后，系统会自动向用户显示一条通知，提醒他们加载项已完成消息处理。 OnMessageDecrypt在处理程序中，调用 event.completed 方法并向其传递 MessageDecryptEventCompletedOptions 对象。 MessageDecryptEventCompletedOptions使用 对象，可以指定是否向收件人显示解密的内容。 有关详细信息，请参阅 实现事件处理。

试用已完成的加载项

若要立即查看操作中已完成的加密加载项，请尝试 在 Outlook 中加密和解密邮件示例。

使用基于事件的激活实现解密

必须实现自己的加密和解密协议。 加载项还必须配置为处理事件， OnMessageDecrypt 以便方便地确定加载项何时可以解密消息并显示解密的内容。 若要实现事件 OnMessageDecrypt ，必须：

  1. 配置加载项的清单。
  2. 实现事件处理。

支持的环境

消息 OnMessageDecrypt 读取图面支持事件。 支持因客户端和 Exchange 环境而异，如下表所示。

客户端 Exchange Online Exchange Subscription Edition (SE) Exchange Server 2019 Exchange Server 2016
Web 浏览器 支持 不可用 不可用 不可用
Windows (新) 支持 不可用 不可用 不可用
Windows (经典)
版本 2602 (内部版本 19725.20126) 及更高版本		 支持 不可用 不可用 不可用
Mac 不可用 不可用 不可用 不可用
Android 不可用 不可用 不可用 不可用
iOS 不可用 不可用 不可用 不可用

配置清单

注意

事件 OnMessageDecrypt 和 "extensions.autoRunEvents.events.options.headerName" 属性以统一清单的形式处于预览状态。 不要将解密功能与生产外接程序中的统一清单一起使用。

在外接程序 的manifest.json 文件中，必须配置 "extensions.runtimes" 数组并添加数组， "extensions.autoRunEvents" 以便在外接程序中启用基于事件的激活。

  1. 将以下对象添加到 "extensions.runtimes" 数组中。 关于此标记，请注意以下几点。

    • "id"运行时的 设置为描述性名称 "autorun_runtime"。
    • 属性 "code" 具有设置为 HTML 文件的子 "page" 属性和设置为 JavaScript 文件的子 "script" 属性。 Office 根据平台使用这些值之一。
      • Outlook 网页版和新的 Outlook on Windows 在浏览器运行时中执行处理程序，这将加载 HTML 文件。 该文件又包含一个 <script> 用于加载 JavaScript 文件的标记。
      • 经典 Outlook on Windows 在仅限 JavaScript 的运行时中执行事件处理程序，该运行时直接加载 JavaScript 文件。 有关详细信息，请参阅 Office 外接程序中的运行时。
    • 属性 "lifetime" 设置为 "short"，这意味着运行时在事件触发时启动，并在处理程序完成时关闭。
    • 操作 将 JavaScript 处理程序映射到 OnMessageSend 和 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. 将以下 "autoRunEvents" 数组添加为 数组中 "extensions" 对象的属性。 关于此标记，请注意以下几点。

    • 为外接程序处理的每个事件创建一个事件对象。 在此示例中，为 OnMessageSend 创建一个事件对象，为 创建另一个事件 OnMessageDecrypt对象。 这两个事件都使用其统一清单事件名称和 "messageSending""messageDecrypt"，如 支持的事件表中所述。
    • 若要确保在事件发生时运行相应的处理程序，中 "actionId" 提供的函数名称必须与前面步骤中 "id" 数组中适用对象的 "runtimes.actions" 属性中使用的名称匹配。
    • “options”属性为 OnMessageSend 和 OnMessageDecrypt 事件提供其他配置。 
    "autoRunEvents": [
    {
        "events": [
          {
              "type": "messageSending",
              "actionId": "onMessageSendHandler",
              "options": {
                  "sendMode": "softBlock"
              }
          },
          {
              "type": "messageDecrypt",
              "actionId": "onMessageDecryptHandler",
              "options": {
                  "headerName": "contoso-encrypted"
              }
          }
        ]
    }
]

实现事件处理

事件处理程序 OnMessageDecrypt 用于运行解密操作，并确定是否显示消息的解密内容。

  • 若要确保处理程序在事件发生时 OnMessageDecrypt 运行，请在实现处理程序的 JavaScript 文件中调用 Office.actions.associate 。 这会将清单中 元素的 <LaunchEvent> 属性中指定的FunctionName处理程序名称映射到其 JavaScript 对应名称。
  • 解密操作完成后，必须调用 event.completed 以向客户端发出信号，指出加载项已完成事件处理 OnMessageDecrypt 。 若要显示邮件及其附件的解密内容，请将 MessageDecryptEventCompletedOptions 对象传递给调用， event.completed 并将其 allowEvent 属性设置为 true。 然后，在对象的 emailBody 和 附件 属性中指定邮件的解密内容。 还可以在 contextData 属性中指定加载项可能需要处理的任何数据。 例如，可以存储自定义 Internet 标头，以在答复和转发方案中解密消息。

注意

为 Windows 上的经典 Outlook 创建基于事件的加载项时，请注意以下事项。

  • 包含事件处理程序的 JavaScript 文件中当前不支持导入。
  • 当清单中指定的用于处理事件的 JavaScript 函数运行时，和 中的代码Office.onReady()Office.initialize不会运行。 建议改为将事件处理程序所需的任何启动逻辑（例如检查用户的 Outlook 版本）添加到事件处理程序。

下面是事件处理程序的示例 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);

提示

当图像作为内联附件添加到邮件时，会自动为其分配内容 ID。 在邮件正文中，内联附件的内容 ID 在 元素的 <img> 属性中src指定，类似于以下示例。

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

为了在解密期间轻松识别并提供这些内联附件，我们建议在加密期间将内联附件的内容 ID 保存到邮件头。 调用 Office.context.mailbox.item.getAttachmentsAsync 以获取内联附件 的内容 ID 。 然后，调用 Office.context.mailbox.item.internetHeaders.setAsync 将 ID 保存到邮件头。

解密 Outlook 项目附件 (预览)

支持解密 Outlook 项目附件 () Office.MailboxEnums.AttachmentType.Item ，尤其是电子邮件附件，可在Outlook 网页版和 Windows (新) 和经典) 中预览。 若要在经典 Outlook on Windows 中预览此功能，必须安装版本 2606 (内部版本 20114.15110) 或更高版本。 然后，加入 Microsoft 365 预览体验计划 ，并选择 “Beta 频道” 选项以访问 Office beta 版本。 若要使用本文中的示例代码测试此功能，请使用以下代码更新 onMessageDecryptHandler 函数。

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

自定义解密操作的错误消息 (预览)

失败解密操作的自定义错误消息在 Outlook 网页版 和 Windows (新) 和经典) 中提供预览版。 若要在经典 Outlook on Windows 中预览此功能，必须安装版本 2606 (内部版本 20114.15110) 或更高版本。 然后，加入 Microsoft 365 预览体验计划 ，并选择 “Beta 频道” 选项以访问 Office beta 版本。

如果解密操作失败，allowEvent则调用的 event.completed 属性设置为 false，Outlook 向用户显示以下默认通知：“<加载项名称>无法处理邮件。”若要指定自定义错误消息，请设置加载项调用的 event.completederrorMessage 属性。 自定义消息的前缀为“ <加载项名称>错误：”。 如果无法显示自定义消息，则会改为显示默认通知。

以下代码示例演示如何为解密加载项指定自定义错误消息。

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

管理解密内容的分发 (预览)

为了帮助防止未经授权的分发解密内容，访问控制选项在 Outlook 网页版 和 Windows (新) 和经典) 中提供预览版。 若要在经典 Outlook on Windows 中预览此功能，必须安装版本 2606 (内部版本 20114.15110) 或更高版本。 然后，加入 Microsoft 365 预览体验计划 ，并选择 “Beta 频道” 选项以访问 Office beta 版本。

若要限制打印、复制或保存解密内容，请包含调用的 event.completedaccessControls 属性。 然后，将 allowPrint、 allowCopyPaste 和 allowSave 属性设置为 false。 accessControls如果未指定 属性，则访问控制默认为 true。

若要使用本文中的示例代码测试此功能，请使用以下代码更新 event.completed 函数的 onMessageDecryptHandler 调用。

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

注意

  • 在 Outlook 网页版 中，将 属性设置为 allowCopyPastefalse 也会阻止用户以屏幕截图或录制的形式捕获其屏幕。 屏幕捕获策略一直有效，直到用户重新加载 Outlook 浏览器选项卡。
  • 在Outlook 网页版和新的 Outlook on Windows 中，将 属性设置为allowPrintfalse禁用上下文菜单 (该菜单提供“复制”、“全选”和“打印) ” 等选项。 如果 属性 allowCopyPaste 设置为 true，则用户仍可以通过按 Ctrl+C 复制内容，但上下文菜单中的 “复制 ”选项不可用。

行为和限制

  • 请注意基于事件的加载项的行为和限制。若要了解详细信息，请参阅 使用事件激活加载项。

  • 由于每个外接程序都使用其自己的加密协议，因此消息只能由加密它的同一加载项解密。 如果用户未安装解密消息所需的加载项，则会发出通知，提醒他们消息已加密。 若要引导用户完成解密过程，请为加密邮件的正文自定义占位符消息。 占位符消息可以包含有关如何安装加载项的信息。 若要在加密过程中设置邮件正文，请调用 Office.context.mailbox.item.body.setAsync。

    加密消息的示例占位符消息。

  • 为确保数据安全性和机密性，已解密的内容不会存储在 Outlook 客户端上。 每次用户打开加密邮件时，都会解密该邮件的内容。

  • 必须先解密加密邮件，然后用户才能答复或转发该邮件。 在解密加密邮件时，用户无法回复或转发该邮件。

  • 如果用户在解密加密邮件时导航到另一个邮件项，则解密过程将停止运行。 用户必须再次选择或打开邮件才能激活解密过程。

  • 答复或转发加密邮件时，草稿以未加密的方式保存在 “草稿 ”文件夹中。

  • attachments方法的 event.completed 属性不支持 类型的Office.MailboxEnums.AttachmentType.Item附件，Outlook 网页版 和 Windows (新) 和经典) 的预览版除外。 若要了解详细信息，请参阅 解密 Outlook 项目附件 (预览) 。

  • 自定义加密加载项无法加密已受 DRM 或 S/MIME 保护的消息。

  • 在 Outlook 网页版 和新的 Outlook on Windows 中，当加密邮件按对话分组时，仅解密来自会话线程的当前所选邮件。 对话线程中的其他消息将保持加密状态，直到选择它们。

  • 在 Outlook 网页版 和新 Outlook on Windows 中，用户只能下载 EML 格式的解密邮件。 MSG 格式的下载选项不可用。

解密通知

处理 OnMessageDecrypt 事件的加载项在某些解密方案中自动显示通知，如下表所述。

通知 应用场景
<加载项名称> 不可用，目前无法处理你的消息。 仅适用于经典 Outlook on Windows。 当加载项加载失败时，将显示此通知，因为错误阻止加载项加载或用户的客户端或计算机脱机。
<加载项名称> 无法处理邮件。 加载项解密消息时遇到错误。 若要重试解密操作，收件人必须切换到另一封邮件，然后再次打开加密邮件以调用事件 OnMessageDecrypt 。
<加载项名称> 加载项正在解密邮件。 加载项正在处理 事件 OnMessageDecrypt 以解密消息。
此消息由 <外接程序名称> 加载项加密。 此通知将显示给未安装必要加密加载项的收件人。 若要提供有关如何解密消息的指导，请在加密邮件的正文中包含占位符消息。 有关详细信息，请参阅 行为和限制。
<加载项名称> 加载项已解密邮件。 加载项已成功解密消息的内容。 用户现在可以查看邮件及其附件。
<加载项名称> 处理邮件所需的时间比预期长。 加载项运行时间已超过 5 秒，但不到 5 分钟。
<加载项名称> 超时。若要重试，请选择另一封电子邮件，然后返回到此邮件。 加载项在运行 5 分钟后超时。 若要重试解密操作，收件人必须切换到另一封邮件，然后再次打开加密邮件以调用事件 OnMessageDecrypt 。
<加载项名称> 超时。 (预览) 加载项在运行 5 分钟后超时。 此通知包括 重试 操作，以便收件人可以重试解密操作，而无需切换到其他邮件。 此重试功能在 Outlook 网页版 和 Windows (新的和经典) 中提供预览版。 若要在经典 Outlook on Windows 中预览此功能，必须安装版本 2606 (内部版本 20114.15110) 或更高版本。 然后，加入 Microsoft 365 预览体验计划 ，并选择 “Beta 频道” 选项以访问 Office beta 版本。
<加载项名称> 无法处理此消息，因为它受内置安全功能保护。 加载项尝试处理已受 DRM 或 S/MIME 保护的消息。
预览) (自定义错误消息 加载项解密消息时遇到错误。 若要重试解密操作，收件人必须切换到另一封邮件，然后再次打开加密邮件以调用事件 OnMessageDecrypt 。 有关如何为解密操作自定义错误消息的指南，请参阅 自定义解密操作的错误消息 (预览版) 。

另请参阅

  • Last updated on