在 Outlook 加载项中实现自定义加密和解密功能,以保护电子邮件通信。 此 OnMessageDecrypt 事件允许加载项自动识别加密邮件并处理解密、内容显示和错误通知。
加密和解密工作流概述
提示
- 加密和解密工作流实现基于事件的激活功能。 如果不熟悉 Outlook 加载项中基于事件的激活,建议先了解该功能及其实现。 若要了解详细信息,请参阅 通过事件激活加载项。
- 对于本节中推荐的每个 API,最低要求集和支持的平台可能有所不同。 建议根据 Outlook JavaScript API 要求集 验证任何要求,并使用特定 API 的文档对其进行补充。
下表概述了 Outlook 加载项的加密和解密工作流。 它还标识步骤是否需要自定义解决方案或受 Office JavaScript (Office.js) API 库支持。
| 步骤 | 实现 |
|---|---|
| 用户撰写邮件并使用你的加载项应用加密规则 | 您必须实现自己的加密协议,以便加载项可以保护邮件及其附件的内容。 |
| 用户发送消息 | 实现 OnMessageSend 事件的处理程序,以便当用户选择“ 发送”时,加载项可以自动运行加密协议。 若要标识在解密过程中使用加载项加密的邮件,请使用 Internet 标头 API 向邮件添加标头。 标头键必须与加载项清单中 OnMessageDecrypt 事件的 LaunchEvent> 元素属性<中 HeaderName指定的值匹配。 有关详细信息,请参阅 使用基于事件的激活实现解密。 |
| 收件人收到加密邮件并打开它 | 如果收件人具有安装在 Outlook 中用于加密邮件的相同加载项,则该加载项将检查邮件中包含的标头键是否与清单中的事件指定 OnMessageDecrypt 值匹配。 此操作由处理OnMessageDecrypt事件的加载项自动完成,因此您不必手动实现检查。 如果标头匹配,则发生事件 OnMessageDecrypt 并运行其处理程序。 有关详细信息,请参阅 使用基于事件的激活实现解密。 |
| 加载项解密邮件 | 必须在事件处理程序中 OnMessageDecrypt 实现自己的解密协议。 在加载项解密邮件及其附件时,会向用户显示一条通知,提醒他们此加载项正在处理其邮件。 此通知由处理 OnMessageDecrypt 事件的加载项自动显示,因此你无需手动创建通知。 |
| 收件人查看解密的邮件及其附件(如果有) | 解密操作完成后,将自动向用户显示一条通知,提醒他们该加载项已完成消息处理。 在处理程序中 OnMessageDecrypt ,调用 event.completed 方法并向其传递一个 MessageDecryptEventCompletedOptions 对象。 使用对象, MessageDecryptEventCompletedOptions 可以指定是否向收件人显示解密的内容。 有关详细信息,请参阅 实现事件处理。 |
试用已完成的加载项
若要立即查看已完成的加密外接程序的实际应用,请尝试在 Outlook 中加密和解密邮件示例。
使用基于事件的激活实现解密
您必须实现自己的加密和解密协议。 还必须将加载项配置为处理 OnMessageDecrypt 事件,以便方便地确定加载项何时可以解密消息并显示解密的内容。 若要实现该 OnMessageDecrypt 事件,必须:
受支持的环境
消息读取图面支持该 OnMessageDecrypt 事件。 支持因客户端和 Exchange 环境而异,如下表所示。
| 客户端 | Exchange Online | Exchange 订阅版 (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" 在加载项中启用基于事件的激活。
将以下对象添加到
"extensions.runtimes"数组中。 关于此标记,请注意以下几点。- 运行时的 设置为
"id"描述性名称"autorun_runtime"。 - 该
"code"属性具有设置为 HTML 文件的子"page"属性和设置为 JavaScript 文件的子"script"属性。 Office 使用以下值之一,具体取决于平台。- Outlook 网页版和新 Windows 版 Outlook 在浏览器运行时执行处理程序,这会加载 HTML 文件。 而该文件包含加载
<script>JavaScript 文件的标记。 - Windows 上的经典 Outlook 在仅限 JavaScript 的运行时中执行事件处理程序,这会直接加载 JavaScript 文件。 有关详细信息,请参阅 Office 加载项中的运行时。
- Outlook 网页版和新 Windows 版 Outlook 在浏览器运行时执行处理程序,这会加载 HTML 文件。 而该文件包含加载
- 属性
"lifetime"设置为"short",这意味着运行时在触发事件时启动,在处理程序完成时关闭。 -
操作将 JavaScript 处理程序映射到 and
OnMessageSendOnMessageDecrypt事件。
"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" } ] } ],- 运行时的 设置为
将以下
"autoRunEvents"数组添加为数组中"extensions"对象的属性。 关于此标记,请注意以下几点。- 为加载项处理的每个事件创建一个事件对象。 在此示例中,为创建一个事件对象,为 创建了另一个
OnMessageDecrypt事件对象。OnMessageSend这两个事件都使用其统一的清单事件名称和"messageSending""messageDecrypt",如 支持的事件表中所述。 - 为确保在事件发生时运行相应的处理程序,其中
"actionId"提供的函数名称必须与前一步中数组中"runtimes.actions"适用对象的属性中使用的"id"名称匹配。 -
“options”属性为 and
OnMessageDecrypt事件提供其他配置OnMessageSend。- 对于
OnMessageSend, “sendMode” 选项指定在消息不符合加载项条件时用户是否能够发送其消息。 在此示例中,指定了该"softBlock"选项。 若要了解有关发送模式选项的详细信息,请参阅“ 使用智能警报处理 Outlook 加载项中的 OnMessageSend 和 OnAppointmentSend 事件”的“可用发送模式选项”部分。 - 对于
OnMessageDecrypt, “headerName” 选项指定用于标识邮件是否已由加载项加密的 Internet 标头名称。 同一标头会添加到由加载项加密的邮件中。
- 对于
"autoRunEvents": [ { "events": [ { "type": "messageSending", "actionId": "onMessageSendHandler", "options": { "sendMode": "softBlock" } }, { "type": "messageDecrypt", "actionId": "onMessageDecryptHandler", "options": { "headerName": "contoso-encrypted" } } ] } ]- 为加载项处理的每个事件创建一个事件对象。 在此示例中,为创建一个事件对象,为 创建了另一个
实现事件处理
OnMessageDecrypt事件处理程序用于运行解密操作并确定是否显示消息的已解密内容。
- 要确保处理程序在事件发生时
OnMessageDecrypt运行,请调用Office.actions.associate实现处理程序的 JavaScript 文件。 这会将清单中元素的<LaunchEvent>属性中FunctionName指定的处理程序名称映射到其 JavaScript 对应项。 - 解密操作完成后,必须调用
event.completed以向客户端发出信号,表明加载项已完成处理事件OnMessageDecrypt。 若要显示消息及其附件的解密内容,请将 MessageDecryptEventCompletedOptions 对象传递给调用,event.completed并将其 allowEvent 属性设置为true。 然后,在对象的 emailBody 和 attachments 属性中指定邮件的解密内容。 还可以在 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 (全新和经典) 上预览。 若要在 Windows 上的经典 Outlook 中预览此功能,必须安装版本 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 (新旧) 上预览。 若要在 Windows 上的经典 Outlook 中预览此功能,必须安装版本 2606 (内部版本 20114.15110) 或更高版本。 然后,加入 Microsoft 365 预览体验计划 并选择 Beta 版频道 选项以访问 Office Beta 版本。
如果解密操作失败,allowEvent则调用的event.completed属性设置为 false,并且 Outlook 向用户显示以下默认通知:“加载项名称>无法处理邮件”<。若要指定自定义错误消息,请设置加载项event.completed调用的 errorMessage 属性。 自定义消息以“加载项名称>错误:”<为前缀。 如果无法显示自定义消息,则改为显示默认通知。
以下代码示例演示如何为解密加载项指定自定义错误消息。
event.completed({
allowEvent: false,
errorMessage: "This message couldn't be decrypted. Contact the Contoso IT team for further assistance."
});
管理解密内容的分发 (预览)
为了帮助防止未经授权分发解密的内容,访问控制选项在 Outlook 网页版 中以及 Windows (新旧) 上提供了预览版。 若要在 Windows 上的经典 Outlook 中预览此功能,必须安装版本 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 网页版中,将属性设置为
allowCopyPaste还false可阻止用户以屏幕截图或录制的形式捕获屏幕。 屏幕捕获策略一直有效,直到用户重新加载 Outlook 浏览器选项卡。 - 在 Outlook 网页版 和 Windows 上的新版 Outlook 中,将属性
false设置为allowPrint禁用上下文菜单 (,该菜单提供“复制”、“全选”和“打印) ”等选项。 如果该allowCopyPaste属性设置为true,用户仍可以通过按 Ctrl+C 复制内容,但上下文菜单中的 “复制” 选项不可用。
行为和限制
请注意基于事件的加载项的行为和限制。若要了解详细信息,请参阅 通过事件激活加载项。
由于每个加载项都使用自己的加密协议,因此只能由加密消息的同一加载项解密消息。 如果用户未安装解密邮件所需的加载项,则会出现一条通知,提醒他们邮件已加密。 若要指导用户完成解密过程,请为加密消息的正文自定义占位符消息。 占位符消息可以包括有关如何安装加载项的信息。 若要在加密过程中设置邮件正文,请调用 Office.context.mailbox.item.body.setAsync。
为了确保数据安全性和机密性,解密的内容不会存储在 Outlook 客户端上。 每次用户打开加密邮件时,都会对其内容进行解密。
加密邮件必须先解密,然后用户才能回复或转发它。 解密加密邮件时,用户无法回复或转发该邮件。
如果用户在解密加密邮件期间导航到另一个邮件项,则解密过程将停止运行。 用户必须再次选择或打开邮件才能激活解密过程。
回复或转发加密邮件时,草稿以未加密方式保存在“ 草稿” 文件夹中。
attachments该方法的event.completed属性不支持 typeOffice.MailboxEnums.AttachmentType.Item的附件,但 Outlook 网页版 中和 Windows 中的预览 (新的和经典) 除外。 若要了解详细信息,请参阅解 密 Outlook 项目附件 (预览版) 。自定义加密加载项无法加密已受 DRM 或 S/MIME 保护的邮件。
在 Outlook 网页版和 Windows 上的新版 Outlook 中,当加密邮件按对话分组时,仅解密对话线程中当前选定的邮件。 对话线程中的其他邮件在被选中之前将保持加密状态。
在 Outlook 网页版和 Windows 上的新版 Outlook 中,用户只能下载 EML 格式的解密邮件。 无法选择以 MSG 格式下载。
解密通知
处理 OnMessageDecrypt 事件的加载项会在某些解密情况下自动显示通知,如下表所述。
| 通知 | 应用场景 |
|---|---|
| <加载项名称> 不可用,目前无法处理你的邮件。 | 仅适用于 Windows 上的经典 Outlook。 当加载项由于错误阻止加载项,或者用户的客户端或计算机处于脱机状态时,将显示此通知。 |
| <加载项名称> 无法处理消息。 | 加载项解密邮件时遇到错误。 若要重试解密操作,收件人必须切换到另一封邮件,然后再次打开加密邮件以调用 OnMessageDecrypt 该事件。 |
| <加载项名称> 加载项正在解密邮件。 | 加载项正在处理事件以 OnMessageDecrypt 解密邮件。 |
| 此邮件按 <加载项名称> 加载项加密。 | 此通知将显示给未安装必要加密加载项的收件人。 若要提供有关如何解密邮件的指导,请在加密邮件的正文中包含占位符消息。 有关详细信息,请参阅 行为和限制。 |
| <加载项名称> 加载项已解密邮件。 | 加载项已成功解密消息内容。 用户现在可以查看邮件及其附件。 |
| <加载项名称> 处理邮件所花费的时间比预期长。 | 加载项运行时间超过 5 秒,但不到 5 分钟。 |
| <加载项名称> 超时。若要重试,请选择另一封电子邮件,然后返回到此邮件。 | 加载项在运行五分钟后超时。 若要重试解密操作,收件人必须切换到另一封邮件,然后再次打开加密邮件以调用 OnMessageDecrypt 该事件。 |
| <加载项名称> 超时。 (预览) | 加载项在运行五分钟后超时。 此通知包括 重试 操作,因此收件人可以在不切换到另一封邮件的情况下重试解密操作。 此重试功能可在 Outlook 网页版 和 Windows 上预览 (新) 和经典。 若要在 Windows 上的经典 Outlook 中预览此功能,必须安装版本 2606 (内部版本 20114.15110) 或更高版本。 然后,加入 Microsoft 365 预览体验计划 并选择 Beta 版频道 选项以访问 Office Beta 版本。 |
| <加载项名称> 无法处理此消息,因为它受内置安全功能保护。 | 该加载项尝试处理已受 DRM 或 S/MIME 保护的邮件。 |
| 预览) (自定义错误消息 | 加载项解密邮件时遇到错误。 若要重试解密操作,收件人必须切换到另一封邮件,然后再次打开加密邮件以调用 OnMessageDecrypt 该事件。 有关如何自定义解密操作的错误消息的指南,请参阅 自定义解密操作的错误消息 (预览版) 。 |