In diesem Dokument wird erläutert, wie Sie S/MIME-E-Mail-Zertifikate mit der Gmail API verwenden.
Die Gmail API bietet programmgesteuerten Zugriff zum Verwalten von S/MIME-E‑Mail-Zertifikaten für Nutzer in einer Google Workspace-Domain.
Ein Administrator muss gehostetes S/MIME für die Domain aktivieren, damit die Zertifikate funktionieren.
Der S/MIME-Standard bietet eine Spezifikation für die Verschlüsselung mit öffentlichen Schlüsseln und die Signierung von MIME-Daten. Wenn Sie S/MIME-Zertifikate für ein Nutzerkonto konfigurieren, verwendet Gmail sie auf folgende Weise:
Ausgehende E‑Mails mit dem Nutzerzertifikat und dem privaten Schlüssel signieren.
Eingehende E‑Mails mit dem privaten Schlüssel des Nutzers entschlüsseln.
Verschlüsseln Sie ausgehende E‑Mails mit dem Zertifikat und dem öffentlichen Schlüssel des Empfängers.
Eingehende E‑Mails mit dem Absenderzertifikat und dem öffentlichen Schlüssel überprüfen.
Sie können individuelle S/MIME-Zertifikate generieren und mithilfe der Gmail API hochladen. Jedes S/MIME-Zertifikat gilt für einen bestimmten Alias für das E-Mail-Konto eines Nutzers. Aliasse umfassen die primäre E-Mail-Adresse und benutzerdefinierte „Senden als“-Adressen. Die API kennzeichnet ein einzelnes S/MIME-Zertifikat als Standard für jeden Alias.
Weitere Informationen zu Aliasen finden Sie unter Aliase und Signaturen mit der Gmail API verwalten.
API-Zugriff autorisieren
Verwenden Sie eine der folgenden Methoden, um den Zugriff auf die Gmail API zu autorisieren:
Verwenden Sie ein Dienstkonto mit domainweiter Delegierung von Befugnissen. Eine Erklärung dieser Begriffe finden Sie unter Informationen zur Authentifizierung und Autorisierung. Informationen zum Aktivieren dieser Option finden Sie unter Anmeldedaten für den Zugriff erstellen.
Verwenden Sie einen standardmäßigen OAuth 2.0-Vorgang, für den die Nutzereinwilligung erforderlich ist, um ein OAuth 2.0-Zugriffstoken zu erhalten. Weitere Informationen finden Sie unter Informationen zu Authentifizierung und Autorisierung.
Damit diese Option verwendet werden kann, muss der Domainadministrator in der Google Admin-Konsole das Kästchen S/MIME-Verschlüsselung für den Versand und Empfang von E‑Mails aktivieren anklicken. Weitere Informationen finden Sie im Hilfeartikel Gehostetes S/MIME in der Admin-Konsole aktivieren.
Autorisierungsbereiche
Die Gmail API verwendet die gleichen OAuth-Bereiche wie die Gmail-Methoden „sendAs“:
gmail.settings.basic: Erforderlich, um das primäreSendAs-S/MIME zu aktualisieren.gmail.settings.sharing: Erforderlich, um die benutzerdefinierte Von-S/MIME zu aktualisieren.
S/MIME-Schlüssel konfigurieren
Die Ressource settings.sendAs.smimeInfo bietet mehrere Methoden zum Verwalten von S/MIME-Zertifikaten. Jedes Zertifikat ist einem „Senden als“-Alias für einen Nutzer zugeordnet.
Verwenden Sie die Methode settings.sendAs.list für die Ressource settings.sendAs, um die Aliasse vom Typ „Senden als“ für einen Nutzer zu ermitteln.
S/MIME-Schlüssel hochladen
Verwenden Sie die Methode settings.sendAs.smimeInfo.insert für die Ressource settings.sendAs.smimeInfo, um einen neuen S/MIME-Schlüssel für einen Alias hochzuladen, der zu einem Nutzer gehört. Identifizieren Sie den Zielalias mit den folgenden Pfadparametern:
userId: E-Mail-Adresse des Nutzers. Verwenden Sie den speziellen Wertme, um den authentifizierten Nutzer anzugeben.sendAsEmail: Der Alias, für den Sie den Schlüssel hochladen. Diese E‑Mail-Adresse wird imFrom:-Header für E‑Mails angezeigt, die mit diesem Alias gesendet werden.
Geben Sie das S/MIME-Zertifikat und den privaten Schlüssel im Feld pkcs12 im PKCS #12-Format an. Legen Sie in der Anfrage keine anderen Felder fest. Das Feld pkcs12 enthält sowohl den S/MIME-Schlüssel des Nutzers als auch die Signaturzertifikatskette. Die API führt Standardvalidierungen für dieses Feld durch, bevor es akzeptiert wird. Dabei wird Folgendes geprüft:
- Der Betreff stimmt mit der angegebenen E‑Mail-Adresse überein.
- Die Abläufe sind gültig.
- Die ausstellende Zertifizierungsstelle ist in der Liste der vertrauenswürdigen Zertifizierungsstellen von Google enthalten.
- Die Zertifikate entsprechen den technischen Einschränkungen von Gmail.
Wenn der Schlüssel verschlüsselt ist, geben Sie das Passwort im Feld encryptedKeyPassword an. Ein erfolgreicher Methodenaufruf settings.sendAs.smimeInfo.insert gibt die Ressource settings.sendAs.smimeInfo id zurück, die in Zukunft zum Verweisen auf den Schlüssel verwendet wird.
S/MIME-Schlüssel eines Nutzers auflisten
Verwenden Sie die Methode settings.sendAs.smimeInfo.list für die Ressource settings.sendAs.smimeInfo, um die Liste der S/MIME-Schlüssel für den angegebenen Nutzer für den angegebenen Alias zurückzugeben. Identifizieren Sie den Zielalias mit den folgenden Pfadparametern:
userId: E-Mail-Adresse des Nutzers. Verwenden Sie den speziellen Wertme, um den authentifizierten Nutzer anzugeben.sendAsEmail: Der Alias, für den Schlüssel aufgelistet werden sollen. Diese E‑Mail-Adresse wird imFrom:-Header für E‑Mails angezeigt, die mit diesem Alias gesendet werden.
S/MIME-Schlüssel für einen Alias abrufen
Verwenden Sie die Methode settings.sendAs.smimeInfo.get für die Ressource settings.sendAs.smimeInfo, um die spezifischen S/MIME-Schlüssel für einen bestimmten „Senden als“-Alias für einen Nutzer zurückzugeben. Identifizieren Sie den Zielalias mit den folgenden Pfadparametern:
userId: E-Mail-Adresse des Nutzers. Verwenden Sie den speziellen Wertme, um den authentifizierten Nutzer anzugeben.sendAsEmail: Der Alias, für den Sie die Schlüssel abrufen. Diese E‑Mail-Adresse wird imFrom:-Header für E‑Mails angezeigt, die mit diesem Alias gesendet werden.
S/MIME-Schlüssel löschen
Verwenden Sie die Methode settings.sendAs.smimeInfo.delete für die Ressource settings.sendAs.smimeInfo, um den angegebenen S/MIME-Schlüssel aus einem Alias zu löschen. Geben Sie den Zielalias mit den folgenden Pfadparametern an:
userId: E-Mail-Adresse des Nutzers. Verwenden Sie den speziellen Wertme, um den authentifizierten Nutzer anzugeben.sendAsEmail: Der Alias, aus dem Sie den Schlüssel löschen. Diese E‑Mail-Adresse wird imFrom:-Header für E‑Mails angezeigt, die mit diesem Alias gesendet werden.id: Die unveränderliche ID für diesmimeInfo.
Ein gelöschter Schlüssel ist nicht mehr sichtbar und kann nicht mehr verwendet werden. Sie können keine empfangenen S/MIME-E‑Mails entschlüsseln, die mit dem entsprechenden öffentlichen Schlüssel verschlüsselt wurden. Bevor Sie einen Schlüssel löschen, müssen Sie ihn bei der ausstellenden Zertifizierungsstelle (CA) widerrufen.
Standard-S/MIME-Schlüssel für einen Alias festlegen
Verwenden Sie die Methode settings.sendAs.smimeInfo.setDefault für die Ressource settings.sendAs.smimeInfo, um den angegebenen S/MIME-Schlüssel als Standard für den angegebenen Alias zu kennzeichnen. Identifizieren Sie den Zielalias mit den folgenden Pfadparametern:
userId: E-Mail-Adresse des Nutzers. Verwenden Sie den speziellen Wertme, um den authentifizierten Nutzer anzugeben.sendAsEmail: Der Alias, für den der Standardschlüssel festgelegt werden soll. Diese E‑Mail-Adresse wird imFrom:-Header für E‑Mails angezeigt, die mit diesem Alias gesendet werden.id: Die unveränderliche ID für diesmimeInfo.
Für den „Senden als“-Alias eines Nutzers kann nur ein S/MIME-Schlüssel als Standard festgelegt werden. Durch Aufrufen der Methode settings.sendAs.smimeInfo.setDefault wird die vorherige Standardeinstellung aufgehoben.
Wenn ein Nutzer mit einem bestimmten Schlüssel signierte S/MIME-Nachrichten empfängt, weist Gmail den Schlüssel mit dem not_before-Gültigkeitsdatum, das am weitesten in der Zukunft liegt, als Standard zu, wenn E-Mails verschlüsselt werden, die an den zugehörigen Nutzer gesendet werden. Damit Gmail-Nutzer, mit denen der Nutzer bereits kommuniziert hat, den neuen Standardschlüssel verwenden, muss das not_before-Datum des neuen Standardschlüssels nach dem des vorherigen Standardschlüssels liegen. Alternativ können Sie den vorherigen Standardschlüssel widerrufen.
Codebeispiele
Die folgenden Codebeispiele zeigen, wie Sie die Gmail API verwenden, um S/MIME-Zertifikate für eine Organisation mit mehreren Nutzern zu verwalten:
smimeInfo-Ressource für ein S/MIME-Zertifikat erstellen
In diesem Codebeispiel wird gezeigt, wie ein Zertifikat aus einer Datei gelesen, in einen Base64URL-String codiert und dem Feld pkcs12 in der settings.sendAs.smimeInfo-Ressource zugewiesen wird:
Java
Python
S/MIME-Zertifikat hochladen
Rufen Sie zum Hochladen eines Zertifikats die Methode settings.sendAs.smimeInfo.insert auf und geben Sie die Ressource settings.sendAs.smimeInfo im Text der Anfrage an:
Java
Python
Zertifikate mehrerer Nutzer verwalten
Die folgenden Codebeispiele zeigen, wie Sie Zertifikate für mehrere Nutzer in einer Organisation in einem Batchaufruf verwalten:
Zertifikate aus einer CSV-Datei einfügen
Hier ist ein Beispiel für eine CSV-Datei mit Nutzer-IDs und dem Pfad zum Zertifikat jedes Nutzers:
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
Java
Mit den Beispielen CreateSmimeInfo und InsertSmimeInfo können Sie die Zertifikate für die in einer CSV-Datei angegebenen Nutzer hochladen:
Python
Mit den Beispielen create_smime_info und insert_smime_info können Sie die Zertifikate für die in einer CSV-Datei angegebenen Nutzer hochladen:
Zertifikatsverwaltung
In diesem Beispiel werden mehrere Methoden aus der settings.sendAs.smimeInfo-Ressource kombiniert, um zu zeigen, wie Sie Zertifikate für Ihre Organisation verwalten. Darin sind die Zertifikate für den Nutzer aufgeführt. Wenn das Standardzertifikat abgelaufen oder nicht festgelegt ist, wird das Zertifikat hochgeladen, das in der angegebenen Datei gefunden wurde. Anschließend wird das Zertifikat mit dem Ablaufdatum, das am weitesten in der Zukunft liegt, als Standard festgelegt.
Diese Funktion verarbeitet dann eine CSV-Datei, ähnlich wie das vorherige Beispiel Zertifikate aus einer CSV-Datei einfügen.
Java
Python
Weitere Informationen
- Aliasse und Signaturen mit der Gmail API verwalten
- Gmail API-Bereiche auswählen
- Gehostetes S/MIME für die Nachrichtenverschlüsselung aktivieren