Erstellen eines Outlook-Verschlüsselungs-Add-Ins

Implementieren Sie benutzerdefinierte Verschlüsselungs- und Entschlüsselungsfunktionen in einem Outlook-Add-In, um die E-Mail-Kommunikation zu schützen. Das OnMessageDecrypt -Ereignis ermöglicht es Ihrem Add-In, verschlüsselte Nachrichten automatisch zu identifizieren und Entschlüsselung, Inhaltsanzeige und Fehlerbenachrichtigungen zu verarbeiten.

Übersicht über die Verschlüsselungs- und Entschlüsselungsworkflows

Die folgende Tabelle enthält eine Übersicht über die Ver- und Entschlüsselungsworkflows eines Outlook-Add-Ins. Außerdem wird ermittelt, ob ein Schritt eine benutzerdefinierte Lösung erfordert oder von der Office JavaScript-API-Bibliothek (Office.js) unterstützt wird.

Testen eines abgeschlossenen Add-Ins

Um sofort ein abgeschlossenes Verschlüsselungs-Add-In in Aktion zu sehen, probieren Sie das Beispiel Verschlüsseln und Entschlüsseln von Nachrichten in Outlook aus.

Implementieren der Entschlüsselung mithilfe der ereignisbasierten Aktivierung

Sie müssen Ihre eigenen Verschlüsselungs- und Entschlüsselungsprotokolle implementieren. Das Add-In muss auch für die Behandlung des OnMessageDecrypt Ereignisses konfiguriert werden, um bequem zu bestimmen, wann Ihr Add-In eine Nachricht entschlüsseln und den entschlüsselten Inhalt anzeigen kann. Um das OnMessageDecrypt Ereignis zu implementieren, müssen Sie:

1. Konfigurieren Sie das Manifest des Add-Ins.
2. Implementieren sie die Ereignisbehandlung.

Unterstützte Umgebungen

Das OnMessageDecrypt Ereignis wird auf der Nachrichtenleseoberfläche unterstützt. Die Unterstützung variiert je nach Client- und Exchange-Umgebung, wie in der folgenden Tabelle gezeigt.

Konfigurieren des Manifests

<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. This is used by Outlook on the web and the new Outlook on Windows. -->
          <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="OnMessageDecrypt" FunctionName="onMessageDecryptHandler" 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>

Implementieren der Ereignisbehandlung

Der OnMessageDecrypt Ereignishandler wird verwendet, um den Entschlüsselungsvorgang auszuführen und zu bestimmen, ob der entschlüsselte Inhalt einer Nachricht angezeigt werden soll.

• Um sicherzustellen, dass der Handler ausgeführt wird, wenn das OnMessageDecrypt Ereignis auftritt, rufen Sie Office.actions.associate in der JavaScript-Datei auf, in der der Handler implementiert ist. Dadurch wird der im -Attribut des <LaunchEvent> -Elements im FunctionName Manifest angegebene Handlername dem JavaScript-Gegenstück zugeordnet.
• Sobald der Entschlüsselungsvorgang abgeschlossen ist, müssen Sie aufrufen event.completed , um dem Client zu signalisieren, dass das Add-In die Verarbeitung des OnMessageDecrypt Ereignisses abgeschlossen hat. Um den entschlüsselten Inhalt einer Nachricht und ihrer Anlagen anzuzeigen, übergeben Sie ein MessageDecryptEventCompletedOptions-Objekt an den event.completed Aufruf, und legen Sie dessen allowEvent-Eigenschaft auf fest true. Geben Sie dann den entschlüsselten Inhalt der Nachricht in den Eigenschaften emailBody und attachments des Objekts an. Sie können auch alle Daten angeben, die Ihr Add-In für die Verarbeitung in der contextData-Eigenschaft benötigt. Beispielsweise können Sie benutzerdefinierte Internetheader speichern, um Nachrichten in Antwort- und Weiterleitungsszenarien zu entschlüsseln.

Es folgt ein Beispiel für einen OnMessageDecrypt Ereignishandler.

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);

Entschlüsseln von Outlook-Elementanlagen (Vorschau)

Unterstützung für das Entschlüsseln von Outlook-Elementanlagen (Office.MailboxEnums.AttachmentType.Item), insbesondere E-Mail-Anlagen, ist für die Vorschau in Outlook im Web und unter Windows (neu und klassisch) verfügbar. Um eine Vorschau dieses Features im klassischen Outlook unter Windows anzuzeigen, müssen Sie Version 2606 (Build 20114.15110) oder höher installieren. Nehmen Sie dann am Microsoft 365 Insider-Programm teil, und wählen Sie die Option Betakanal aus, um auf Office-Beta-Builds zuzugreifen. Um dieses Feature mithilfe des Beispielcodes in diesem Artikel zu testen, aktualisieren Sie die onMessageDecryptHandler Funktion mit dem folgenden Code.

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

Anpassen von Fehlermeldungen für den Entschlüsselungsvorgang (Vorschau)

Benutzerdefinierte Fehlermeldungen für fehlgeschlagene Entschlüsselungsvorgänge sind in Outlook im Web und unter Windows (neu und klassisch) als Vorschau verfügbar. Um eine Vorschau dieses Features im klassischen Outlook unter Windows anzuzeigen, müssen Sie Version 2606 (Build 20114.15110) oder höher installieren. Nehmen Sie dann am Microsoft 365 Insider-Programm teil, und wählen Sie die Option Betakanal aus, um auf Office-Beta-Builds zuzugreifen.

Wenn der Entschlüsselungsvorgang fehlschlägt, wird die allowEvent -Eigenschaft des event.completed Aufrufs auf falsefestgelegt, und Outlook zeigt die folgende Standardbenachrichtigung für den Benutzer an: "<Add-In-Name> konnte Ihre Nachricht nicht verarbeiten." Um eine benutzerdefinierte Fehlermeldung anzugeben, legen Sie die errorMessage-Eigenschaft des Add-In-Aufrufs event.completed fest. Ihrer benutzerdefinierten Nachricht wird "Error from <add-in name>:" vorangestellt. Wenn Ihre benutzerdefinierte Nachricht nicht angezeigt werden kann, wird stattdessen die Standardbenachrichtigung angezeigt.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine benutzerdefinierte Fehlermeldung für Ihr Entschlüsselungs-Add-In angeben.

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

Verwalten der Verteilung entschlüsselter Inhalte (Vorschau)

Um die nicht autorisierte Verteilung entschlüsselter Inhalte zu verhindern, stehen Zugriffssteuerungsoptionen für die Vorschau in Outlook im Web und unter Windows (neu und klassisch) zur Verfügung. Um eine Vorschau dieses Features im klassischen Outlook unter Windows anzuzeigen, müssen Sie Version 2606 (Build 20114.15110) oder höher installieren. Nehmen Sie dann am Microsoft 365 Insider-Programm teil, und wählen Sie die Option Betakanal aus, um auf Office-Beta-Builds zuzugreifen.

Um das Drucken, Kopieren oder Speichern von entschlüsselten Inhalten einzuschränken, schließen Sie die accessControls-Eigenschaft des event.completed Aufrufs ein. Legen Sie dann die Eigenschaften allowPrint, allowCopyPaste und allowSave auf fest false. Wenn die accessControls -Eigenschaft nicht angegeben ist, ist die Zugriffssteuerung standardmäßig auf truefestgelegt.

Um dieses Feature mit dem Beispielcode in diesem Artikel zu testen, aktualisieren Sie den event.completed Aufruf der onMessageDecryptHandler Funktion mit dem folgenden Code.

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

Verhalten und Einschränkungen

• Beachten Sie das Verhalten und die Einschränkungen ereignisbasierter Add-Ins. Weitere Informationen finden Sie unter Aktivieren von Add-Ins mit Ereignissen.

• Da jedes Add-In ein eigenes Verschlüsselungsprotokoll verwendet, kann eine Nachricht nur von demselben Add-In entschlüsselt werden, das sie verschlüsselt hat. Wenn ein Benutzer nicht das erforderliche Add-In zum Entschlüsseln einer Nachricht installiert hat, wird er in einer Benachrichtigung darüber benachrichtigt, dass die Nachricht verschlüsselt ist. Um den Benutzer durch den Entschlüsselungsprozess zu führen, passen Sie eine Platzhalternachricht für den Text der verschlüsselten Nachricht an. Die Platzhaltermeldung kann Informationen zur Installation des Add-Ins enthalten. Um den Nachrichtentext während des Verschlüsselungsvorgangs festzulegen, rufen Sie Office.context.mailbox.item.body.setAsync auf.

  

• Um Datensicherheit und Vertraulichkeit sicherzustellen, werden entschlüsselte Inhalte nicht auf dem Outlook-Client gespeichert. Der Inhalt einer verschlüsselten Nachricht wird jedes Mal entschlüsselt, wenn ein Benutzer sie öffnet.

• Eine verschlüsselte Nachricht muss zuerst entschlüsselt werden, bevor ein Benutzer sie beantworten oder weiterleiten kann. Ein Benutzer kann eine verschlüsselte Nachricht nicht beantworten oder weiterleiten, während sie entschlüsselt wird.

• Wenn ein Benutzer zu einem anderen E-Mail-Element navigiert, während eine verschlüsselte Nachricht entschlüsselt wird, wird der Entschlüsselungsprozess beendet. Der Benutzer muss die Nachricht erneut auswählen oder öffnen, um den Entschlüsselungsprozess zu aktivieren.

• Beim Beantworten oder Weiterleiten verschlüsselter Nachrichten werden Entwürfe unverschlüsselt im Ordner Entwürfe gespeichert.

• Die attachments -Eigenschaft der event.completed -Methode unterstützt keine Anlagen vom Typ Office.MailboxEnums.AttachmentType.Item, mit Ausnahme der Vorschau in Outlook im Web und unter Windows (neu und klassisch). Weitere Informationen finden Sie unter Entschlüsseln von Outlook-Elementanlagen (Vorschau).

• Benutzerdefinierte Verschlüsselungs-Add-Ins können keine Nachrichten verschlüsseln, die bereits durch DRM oder S/MIME geschützt sind.

• Wenn verschlüsselte Nachrichten in Outlook im Web und dem neuen Outlook unter Windows nach Unterhaltung gruppiert werden, wird nur die aktuell ausgewählte Nachricht aus dem Unterhaltungsthread entschlüsselt. Die anderen Nachrichten im Unterhaltungsthread bleiben verschlüsselt, bis sie ausgewählt sind.

• In Outlook im Web und dem neuen Outlook unter Windows können Benutzer nur eine entschlüsselte Nachricht im EML-Format herunterladen. Die Option zum Herunterladen im MSG-Format ist nicht verfügbar.

Entschlüsselungsbenachrichtigungen

Add-Ins, die das OnMessageDecrypt Ereignis behandeln, zeigen automatisch Benachrichtigungen in bestimmten Entschlüsselungsszenarien an, wie in der folgenden Tabelle beschrieben.

Siehe auch

• Beispiel: Verschlüsseln und Entschlüsseln von Nachrichten in Outlook
• Datenschutz und Sicherheit für Office-Add-Ins
• Aktivieren von Add-Ins mit Ereignissen
• Problembehandlung bei ereignisbasierten Add-Ins und Spam-Berichts-Add-Ins
• Abrufen und Festlegen von Internetheadern für eine Nachricht in einem Outlook-Add-In
• Verwalten der Vertraulichkeitsbezeichnung Ihrer Nachricht oder Ihres Termins im Verfassenmodus