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

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

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

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

Реализация расшифровки с помощью активации на основе событий

Необходимо реализовать собственные протоколы шифрования и расшифровки. Надстройка также должна быть настроена для обработки OnMessageRead события, чтобы удобно определить, когда надстройка может расшифровать сообщение и отобразить расшифрованное содержимое. Чтобы реализовать OnMessageRead событие, необходимо:

1. Настройте манифест надстройки.
2. Реализуйте обработку событий.

Поддерживаемые среды

Событие OnMessageRead поддерживается в области чтения сообщений. Поддержка зависит от среды клиента и Exchange, как показано в следующей таблице.

Предварительный просмотр API расшифровки в классической версии Outlook в Windows

Чтобы просмотреть API расшифровки в классической версии Outlook в Windows, присоединитесь к программе предварительной оценки Microsoft 365, а затем выберите канал бета-версии в клиенте Outlook. Клиент должен иметь версию 2510 (сборка 19312.20000) или более позднюю.

Классический Outlook для Windows включает локальную копию рабочей и бета-версий Office.js вместо загрузки из сети доставки содержимого (CDN). По умолчанию ссылается на локальную рабочую копию API. Чтобы сослаться на локальную бета-версию API, необходимо настроить реестр компьютера. Это позволит протестировать предварительные версии функций в обработчиках событий в классической версии Outlook в Windows.

1. В реестре перейдите по адресу HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Если ключ не существует, создайте его.

2. Создайте запись с именем EnableBetaAPIsInJavaScript и задайте для нее 1значение .

   

Настройка манифеста

Чтобы активировать надстройку в событии OnMessageRead , необходимо настроить <VersionOverridesV1_1> узел файлаmanifest.xml надстройки следующим образом.

• Чтобы запустить надстройку на основе событий в классической версии Outlook в Windows, необходимо указать файл JavaScript, содержащий обработчик событий, в <дочернем элементе Override> элемента Runtime>.<
• OnMessageRead Укажите событие в атрибуте Type<элемента LaunchEvent>. Необходимо присвоить имя функции обработчика событий атрибуту FunctionName элемента . Чтобы упростить проверку того, было ли сообщение зашифровано надстройкой, в атрибуте необходимо указать ключ заголовка HeaderName . Тот же заголовок добавляется в сообщение, зашифрованное надстройкой.

Ниже приведен пример узла, реализующего <VersionOverrides>OnMessageRead событие .

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.15">
        <bt:Set Name="Mailbox"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <Runtimes>
            <!-- References the HTML file that links to the event handler. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- References the JavaScript file that contains the event handler. This is used by classic Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="WebViewRuntime.Url"/>
          <!-- Implements event-based activation. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="SoftBlock"/>
              <LaunchEvent Type="OnMessageRead" FunctionName="onMessageReadHandler" HeaderName="contoso-encrypted"/>
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
        </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      ...
      <bt:Urls>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.html"/>
        <bt:Url id="JSRuntime.Url" DefaultValue="https://www.contoso.com/launchevent.js"/>
      </bt:Urls>
      ...
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Реализация обработки событий

Обработчик OnMessageRead событий используется для выполнения операции расшифровки и определения того, следует ли отображать расшифрованное содержимое сообщения.

• Чтобы убедиться, что обработчик запускается при возникновении OnMessageRead события, вызовите Office.actions.associate в файле JavaScript, где реализован обработчик. Это сопоставляет имя обработчика, указанное FunctionName в атрибуте <LaunchEvent> элемента в манифесте, с его аналогом JavaScript.
• После завершения операции расшифровки необходимо вызвать, event.completed чтобы сообщить клиенту о том, что надстройка завершила обработку OnMessageRead события. Чтобы отобразить расшифрованное содержимое сообщения и его вложений, передайте объект MessageDecryptEventCompletedOptions в вызов и задайте для его свойства allowEvent значение true.event.completed Затем укажите расшифрованное содержимое сообщения в свойствах emailBody и вложений объекта. Вы также можете указать любые данные, которые могут потребоваться надстройке для обработки, в свойстве contextData . Например, можно хранить пользовательские заголовки Интернета для расшифровки сообщений в сценариях ответа и пересылки.

Ниже приведен пример обработчика OnMessageRead событий.

function onMessageReadHandler(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 content and properties of a mail item.
    const decryptedEmailFile = "VGhpcyBpcyBhIHRleHQgZmlsZS4=...";
    const emailFileName = "Fabrikam_Report_202508.eml";

    // 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 = "[email protected]";

    const decryptedAttachments = [
        {
            attachmentType: Office.MailboxEnums.AttachmentType.File,
            content: decryptedPdfFile,
            isInline: false,
            name: pdfFileName
        },
        {
            attachmentType: Office.MailboxEnums.AttachmentType.Item,
            content: decryptedEmailFile,
            isInline: false,
            name: emailFileName
        },
        {
            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("onMessageReadHandler", onMessageReadHandler);

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

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

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

  

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

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

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

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

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

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

См. также

• Конфиденциальность и безопасность надстроек для Office
• Активация надстроек с помощью событий
• Устранение неполадок надстроек на основе событий и отчетов о спаме
• Получение и настройка заголовков в Интернете для сообщения в надстройке Outlook
• Управление меткой конфиденциальности сообщения или встречи в режиме создания