Создание надстройки шифрования для Outlook

Внедрите пользовательские функции шифрования и расшифровки в надстройке Outlook для защиты сообщений электронной почты. Это OnMessageDecrypt событие позволяет надстройке автоматически идентифицировать зашифрованные сообщения и обрабатывать расшифровку, отображение содержимого и уведомления об ошибках.

Рабочие процессы шифрования и расшифровки

Совет

  • Рабочие процессы шифрования и расшифровки реализуют функцию активации на основе событий. Если вы не знакомы с активацией на основе событий в надстройках Outlook, рекомендуем сначала изучить эту функцию и ее реализацию. Дополнительные сведения см. в разделе Активация надстроек с помощью событий.
  • Минимальный набор требований и поддерживаемые платформы могут различаться для каждого API, рекомендуемого в этом разделе. Рекомендуется сверять все требования с наборами требований API JavaScript Outlook и дополнять их документацией для конкретного API.

В таблице ниже представлен обзор рабочих процессов шифрования и расшифровки надстройки Outlook. Он также определяет, требуется ли для шага пользовательское решение или он поддерживается библиотекой API JavaScript (Office.js).

Шаг Реализация
Пользователь пишет сообщение и использует надстройку для применения правил шифрования Необходимо реализовать собственный протокол шифрования, чтобы надстройка могла защитить содержимое сообщения и его вложений.
Сообщение отправляет пользователь Реализуйте обработчик для события OnMessageSend , чтобы надстройка могла автоматически запускать протокол шифрования, когда пользователь выбирает Отправить.

Чтобы определить, какое сообщение было зашифровано с помощью надстройки во время расшифровки, добавьте заголовок в сообщение с помощью API интернет-заголовков . Ключ заголовка должен совпадать со значением, указанным в HeaderName атрибуте <элемента LaunchEvent> для события OnMessageDecrypt в манифесте надстройки. Дополнительные сведения см. в разделе Реализация расшифровки с помощью активации на основе событий.
Получатель получает зашифрованное сообщение и открывает его Если у получателя есть та же надстройка, которая использовалась для шифрования сообщения, установленного в 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
Браузер Поддерживается Недоступно Недоступно Недоступно
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" свойства есть дочернее "page" свойство, которому задано значение HTML-файла, и дочернее "script" свойство, которому задан файл JavaScript. В зависимости от платформы Office используется одно из этих значений.
      • Outlook в Интернете и новый Outlook в Windows выполняют обработчик в среде выполнения браузера, которая загружает HTML-файл. Этот файл, в свою очередь, содержит <script> тег, который загружает файл JavaScript.
      • Классический Outlook для Windows выполняет обработчик событий в среде выполнения, поддерживающей только JavaScript, которая загружает файл JavaScript напрямую. Дополнительные сведения см. в статье "Среды выполнения в надстройках Office".
    • Свойство "lifetime" имеет значение "short", что означает, что среда выполнения запускается при срабатывании события и завершает работу по завершении обработчика.
    • Действия сопоставляют обработчики JavaScript с OnMessageSend событиями 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. Добавьте следующий "autoRunEvents" массив в качестве свойства объекта в массиве "extensions" . Обратите внимание на следующие особенности этой разметки.

    • Объект события создается для каждого события, которое обрабатывает надстройка. В этом примере один объект события создан для, а другой — для OnMessageSendOnMessageDecrypt. Оба события используют свое единое имя "messageSending" события манифеста и "messageDecrypt", как описано в таблице поддерживаемых событий.
    • Чтобы гарантировать выполнение соответствующего обработчика при возникновении события, имя функции, указанное в, "actionId" должно совпадать с именем, используемым в "id" свойстве соответствующего объекта в массиве "runtimes.actions" на более раннем шаге.
    • Свойство "options" обеспечивает дополнительную настройку для OnMessageSend событий and OnMessageDecrypt .
      • Параметр OnMessageSend"sendMode" определяет, может ли пользователь отправить сообщение, если оно не соответствует условиям надстройки. В этом примере "softBlock" параметр указан. Дополнительные сведения о параметрах режима отправки см. в разделе "Доступные параметры режима отправки" статьи Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью интеллектуальных оповещений.
      • Параметр OnMessageDecrypt"headerName" указывает имя интернет-заголовка, которое используется, чтобы определить, было ли сообщение зашифровано надстройкой. Такой же заголовок добавляется в сообщение, зашифрованное надстройкой.
    "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 события. Чтобы отобразить расшифрованное содержимое сообщения и его вложений, передайте вызову event.completed объект MessageDecryptEventCompletedOptions и задайте для его свойства allowEvent значение true. Затем укажите расшифрованное содержимое сообщения в свойствах emailBody и attachments объекта. В свойстве contextData можно также указать любые данные, которые могут потребоваться надстройке для обработки. Например, можно хранить пользовательские интернет-заголовки для расшифровки сообщений в сценариях ответа и пересылки.

Примечание.

При создании надстройки на основе событий для классического Outlook в Windows учитывайте следующее.

  • В настоящее время импорт не поддерживается в файле 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);

Совет

Когда изображения добавляются в сообщение в качестве встроенных вложений, им автоматически присваивается идентификатор содержимого. В тексте сообщения идентификатор содержимого встроенного вложения указывается в src атрибуте <img> элемента, как в следующем примере.

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

Чтобы легко было идентифицировать и предоставлять такие вложения во время расшифровки, рекомендуется во время шифрования сохранять идентификаторы содержимого встроенных вложений в заголовке сообщения. Вызовите Office.context.mailbox.item.getAttachmentsAsync , чтобы получить идентификатор содержимого встроенного вложения. Затем вызовите Office.context.mailbox.item.internetHeaders.setAsync , чтобы сохранить идентификатор в заголовке сообщения.

Расшифровка вложений элементов Outlook (предварительная версия)

Поддержка расшифровки вложений элементов Outlook (Office.MailboxEnums.AttachmentType.Item), особенно вложений электронной почты, доступна для предварительного просмотра в Outlook в Интернете и в Windows (новой и классической). Чтобы воспользоваться этой функцией в классической версии Outlook для Windows, необходимо установить версию 2606 (сборка 20114.15110) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите вариант бета-канала , чтобы получить доступ к бета-версиям сборок Office. Чтобы протестировать эту функцию с помощью примера кода из этой статьи, обновите 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 для Windows, необходимо установить версию 2606 (сборка 20114.15110) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите вариант бета-канала , чтобы получить доступ к бета-версиям сборок Office.

Если операция расшифровки завершается сбоем, свойство allowEvent вызова event.completed имеет значение false, и Outlook выводит пользователю следующее уведомление по умолчанию: "<Не удалось обработать имя> надстройки". Чтобы указать настраиваемое сообщение об ошибке, задайте свойство errorMessage вызова надстройки event.completed . Вашему настраиваемому сообщению предназначается префикс "Ошибка из <имени> надстройки:". Если не удается отобразить ваше настраиваемое сообщение, вместо него выводится уведомление по умолчанию.

В следующем примере кода показано, как указать настраиваемое сообщение об ошибке для надстройки расшифровки.

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

Управление распространением расшифрованного содержимого (предварительная версия)

Чтобы предотвратить несанкционированное распространение расшифрованного содержимого, параметры управления доступом доступны для предварительного просмотра в Outlook в Интернете и в Windows (новой и классической). Чтобы воспользоваться этой функцией в классической версии Outlook для Windows, необходимо установить версию 2606 (сборка 20114.15110) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите вариант бета-канала , чтобы получить доступ к бета-версиям сборок Office.

Чтобы ограничить печать, копирование или сохранение расшифрованного содержимого, включите свойство accessControls вызова event.completed . Затем задайте свойствам 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 в Интернете и новом Outlook для Windows при присвоении allowPrintfalse свойству значения отключается контекстное меню (в котором доступны такие параметры, как "Копировать", "Выделить все" и "Печать"). Если свойство allowCopyPaste имеет значение true, пользователь по-прежнему может копировать содержимое, нажав клавишу CTRL+C, но параметр "Копировать " в контекстном меню недоступен.

Поведение и ограничения

  • Помните о поведении и ограничениях надстроек, основанных на событиях. Дополнительные сведения см. в разделе Активация надстроек с помощью событий.

  • Поскольку каждая надстройка использует собственный протокол шифрования, сообщение может быть расшифровано только той надстройкой, которая его зашифровала. Если у пользователя не установлена надстройка, необходимая для расшифровки сообщения, пользователь получает уведомление о том, что сообщение зашифровано. Чтобы провести пользователя через процесс расшифровки, настройте сообщение-заполнитель для текста зашифрованного сообщения. Сообщение-заполнитель может содержать сведения об установке надстройки. Чтобы настроить текст сообщения в процессе шифрования, вызовите Office.context.mailbox.item.body.setAsync.

    Пример сообщения-заполнителя зашифрованного сообщения.

  • Чтобы обеспечить безопасность и конфиденциальность данных, расшифрованное содержимое не хранится в клиенте Outlook. Содержимое зашифрованного сообщения расшифровывается каждый раз, когда пользователь его открывает.

  • Зашифрованное сообщение должно быть сначала расшифровано, прежде чем пользователь сможет ответить или переслать его. Пользователь не может ответить или переслать зашифрованное сообщение во время его расшифровки.

  • Если пользователь переходит к другому элементу почты во время расшифровки зашифрованного сообщения, процесс расшифровки останавливается. Пользователь должен выбрать или открыть сообщение еще раз, чтобы активировать процесс расшифровки.

  • При ответе на зашифрованные сообщения или их пересылке черновики сохраняются в незашифрованном виде в папке "Черновики ".

  • Свойство attachmentsevent.completed метода не поддерживает вложения типаOffice.MailboxEnums.AttachmentType.Item, за исключением предварительного просмотра в Outlook в Интернете и в Windows (новой и классической). Дополнительные сведения см. в статье Расшифровка вложений элементов Outlook (предварительная версия).

  • Пользовательские надстройки шифрования не могут шифровать сообщения, которые уже защищены DRM или S/MIME.

  • В Outlook в Интернете и новом Outlook для Windows, когда зашифрованные сообщения группируются по беседе, расшифровывается только выбранное в данный момент сообщение из цепочки беседы. Другие сообщения в цепочке беседы остаются зашифрованными до тех пор, пока они не будут выбраны.

  • В Outlook в Интернете и новом Outlook для Windows пользователи могут скачать только расшифрованное сообщение в формате EML. Возможность скачивания в формате MSG недоступна.

Уведомления о расшифровке

Надстройки, обрабатывающие событие, OnMessageDecrypt автоматически отображают уведомления в определенных сценариях расшифровки, как описано в следующей таблице.

Уведомление Сценарий
<Имя> надстройки недоступно и в настоящее время не удается обработать ваше сообщение. Применяется только к классической версии Outlook для Windows. Это уведомление отображается, если надстройка не загружается из-за ошибки, препятствующей загрузке надстройки либо клиент или компьютер пользователя находится в автономном режиме.
<Не> удалось обработать имя надстройки. Во время расшифровки сообщения надстройкой произошла ошибка. Чтобы повторно выполнить операцию расшифровки, получатель должен переключиться на другое сообщение, а затем снова открыть зашифрованное сообщение, чтобы вызвать OnMessageDecrypt событие.
<Имя> надстройки Надстройка расшифровывает сообщение. Надстройка обрабатывает OnMessageDecrypt событие для расшифровки сообщения.
Это сообщение зашифровано <именем> надстройки. Это уведомление отображается получателям, у которых не установлена необходимая надстройка шифрования. Чтобы предоставить руководство по расшифровке сообщения, включите сообщение-заполнитель в текст зашифрованного сообщения. Дополнительные сведения см. в разделе Поведение и ограничения.
<Имя> надстройки Надстройка расшифровала ваше сообщение. Надстройка успешно расшифровала содержимое сообщения. Теперь пользователь может просмотреть сообщение и его вложения.
<Обработка имени надстройки> занимает больше времени, чем ожидалось. Надстройка работает более пяти секунд, но менее пяти минут.
<Время> ожидания имени надстройки истекло. Чтобы повторить попытку, выберите другой адрес электронной почты и вернитесь к этому сообщению. Время ожидания надстройки истекло после пяти минут. Чтобы повторно выполнить операцию расшифровки, получатель должен переключиться на другое сообщение, а затем снова открыть зашифрованное сообщение, чтобы вызвать OnMessageDecrypt событие.
<Время> ожидания имени надстройки истекло. (предварительная версия) Время ожидания надстройки истекло после пяти минут. Это уведомление включает действие "Повторить попытку ", чтобы получатель мог повторно выполнить операцию расшифровки, не переходя к другому сообщению. Эта функция доступна для предварительного просмотра в Outlook в Интернете и в Windows (новой и классической). Чтобы воспользоваться этой функцией в классической версии Outlook для Windows, необходимо установить версию 2606 (сборка 20114.15110) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите вариант бета-канала , чтобы получить доступ к бета-версиям сборок Office.
<Имя> надстройки не может обработать это сообщение, так как она защищена встроенной функцией безопасности. Надстройка пытается обработать сообщение, которое уже защищено DRM или S/MIME.
Настраиваемое сообщение об ошибке (предварительная версия) Во время расшифровки сообщения надстройкой произошла ошибка. Чтобы повторно выполнить операцию расшифровки, получатель должен переключиться на другое сообщение, а затем снова открыть зашифрованное сообщение, чтобы вызвать OnMessageDecrypt событие. Рекомендации по настройке сообщений об ошибках для операции расшифровки см. в разделе Настройка сообщений об ошибках для операции расшифровки (ознакомительная версия).

См. также

  • Last updated on