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

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

Общие сведения о рабочих процессах шифрования и расшифровки

Совет

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

В следующей таблице представлен обзор рабочих процессов шифрования и расшифровки надстройки Outlook. Он также определяет, требуется ли для шага пользовательское решение или он поддерживается библиотекой API Office 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 и 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 .
      • Для 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, где реализован обработчик. Это сопоставляет имя обработчика, указанное FunctionName в атрибуте <LaunchEvent> элемента в манифесте, с его аналогом JavaScript.
  • После завершения операции расшифровки необходимо вызвать, event.completed чтобы сообщить клиенту о том, что надстройка завершила обработку OnMessageDecrypt события. Чтобы отобразить расшифрованное содержимое сообщения и его вложений, передайте объект MessageDecryptEventCompletedOptions в вызов и задайте для его свойства allowEvent значение true.event.completed Затем укажите расшифрованное содержимое сообщения в свойствах emailBody и вложений объекта. Вы также можете указать любые данные, которые могут потребоваться надстройке для обработки, в свойстве 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.

Чтобы ограничить печать, копирование или сохранение расшифрованного содержимого, добавьте свойство event.completedaccessControls вызова. Затем задайте для свойств allowPrint, allowCopyPaste и allowSave значение false. accessControls Если свойство не указано, по умолчанию для управления доступом используется значение true.

Чтобы протестировать эту функцию с помощью примера кода, приведенного onMessageDecryptHandler в этой статье, обновите event.completed вызов функции следующим кодом.

    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 установка allowPrint свойства в false значение отключает контекстное меню (которое предоставляет такие параметры, как Копировать, Выделить все и Печать). allowCopyPaste Если для свойства задано значение true, пользователь по-прежнему может копировать содержимое, нажав клавиши CTRL+C, но параметр Копировать в контекстном меню недоступен.

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

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

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

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

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

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

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

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

  • Свойство attachments метода не поддерживает вложения типа Office.MailboxEnums.AttachmentType.Item, за исключением предварительной event.completed версии в 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