Gmail S/MIME API 提供程式輔助存取權，可為 Google Workspace 網域中的使用者管理 S/MIME 電子郵件憑證。
管理員必須為網域啟用 S/MIME，憑證才能運作。
S/MIME 標準提供公開金鑰加密和 MIME 資料簽署的規格。在使用者帳戶中設定 S/MIME 憑證後，Gmail 會以以下方式使用該憑證：
- Gmail 會使用使用者的憑證和私密金鑰簽署傳送的郵件。
- Gmail 會使用使用者的私密金鑰解密傳入的郵件。
- Gmail 會使用收件者的憑證和公開金鑰加密傳出郵件。
- Gmail 會使用寄件者的憑證和公開金鑰驗證傳入的郵件。
您可以產生個別的 S/MIME 憑證，然後使用 API 上傳。每個 S/MIME 憑證都會對應至使用者電子郵件帳戶的特定別名。別名包括主要電子郵件地址，以及自訂的「寄件者身分」地址。系統會將單一 S/MIME 憑證標示為每個別名的預設值。
授權 API 存取權
授權存取 API 的方式有兩種：
- 您可以使用服務帳戶，並設定全網域授權委派功能。如需這些條款的說明，請參閱驗證和授權總覽條款。如要瞭解如何啟用這個選項，請參閱「建立具有全網域授權委派功能的服務帳戶」
- 您可以使用標準 OAuth2 流程，要求使用者同意才能取得 Oauth2 存取權杖。詳情請參閱驗證和授權總覽。如要使用這個選項，網域管理員必須在網域控制面板中勾選「啟用 S/MIME API 使用者存取權」核取方塊。
ACL 範圍
這個 API 會使用與 Gmail sendAs 方法相同的 ACL 範圍：
- gmail.settings.basic
- 如要更新主要 SendAs S/MIME，就必須使用這個範圍。
- gmail.settings.sharing
- 如要透過 S/MIME 更新自訂內容，就必須使用這個權限範圍。
使用 API
users.settings.sendAs.smimeInfo 資源提供用於管理 S/MIME 憑證的方法。每張憑證都會與使用者的一個「以身分代發」別名建立關聯。
上傳 S/MIME 金鑰
使用 smimeInfo.insert() 方法，為使用者所屬別名上傳新的 S/MIME 金鑰。您可以使用下列參數識別目標別名：
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me來指出目前已驗證的使用者。 - sendAsEmail
- 您要上傳金鑰的別名。這是使用這個別名傳送郵件時，會顯示在「寄件者：」標頭中的電子郵件地址。
S/MIME 憑證和私密金鑰應以該格式出現在 pkcs12 欄位中；要求中不得設定其他欄位。PKCS12 欄位應包含使用者 S/MIME 金鑰和簽署憑證鏈結。API 會先對這個欄位執行標準驗證，再接受該欄位，驗證項目如下：
- 主旨與指定的電子郵件地址相符。
- 到期日有效。
- 核發憑證的憑證授權單位 (CA) 在我們的信任清單中。
- 憑證符合 Gmail 的技術限制。
如果金鑰已加密，密碼應位於 encryptedKeyPassword 欄位中。成功的 insert() 呼叫會傳回 smimeInfo 的 ID，可用於日後參照金鑰。
列出使用者的 S/MIME 金鑰
使用 smimeInfo.list() 方法，針對指定別名的使用者傳回 S/MIME 金鑰清單。您可以使用下列參數識別目標別名：
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me來指出目前已驗證的使用者。 - sendAsEmail
- 用於列出金鑰的別名。這是使用這個別名傳送郵件時，會顯示在「寄件者：」標頭中的電子郵件地址。
擷取別名的 S/MIME 金鑰
使用 smimeInfo.get() 方法，針對使用者的特定「傳送者」別名，傳回特定 S/MIME 金鑰。您可以使用下列參數識別目標別名：
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me來指出目前已驗證的使用者。 - sendAsEmail
- 您要擷取金鑰的別名。這是使用這個別名傳送郵件時，會顯示在「寄件者：」標頭中的電子郵件地址。
刪除 S/MIME 金鑰
使用 smimeInfo.delete() 方法，從別名中刪除指定的 S/MIME 金鑰。您可以使用下列參數識別目標別名：
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me來指出目前已驗證的使用者。 - sendAsEmail
- 您要擷取金鑰的別名。這是使用這個別名傳送郵件時，會顯示在「寄件者：」標頭中的電子郵件地址。
- id
- SmimeInfo 的固定 ID。
為別名設定預設 S/MIME 金鑰
使用 smimeInfo.setDefault() 方法，將指定的 S/MIME 金鑰標示為指定別名的預設值。您可以使用下列參數識別目標別名：
- userId
- 使用者的電子郵件地址。您可以使用特殊值
me來指出目前已驗證的使用者。 - sendAsEmail
- 您要擷取金鑰的別名。這是使用這個別名傳送郵件時，會顯示在「寄件者：」標頭中的電子郵件地址。
- id
- SmimeInfo 的固定 ID。
程式碼範例
以下程式碼範例示範如何使用 API 管理擁有多位使用者的機構的 S/MIME 憑證。
為 S/MIME 憑證建立 SmimeInfo 資源
以下程式碼範例示範如何從檔案讀取憑證，將其編碼為 base64url 字串，然後指派至 smimeInfo 資源的 pkcs12 欄位：
Java
Python
上傳 S/MIME 憑證
如要上傳憑證，請呼叫 smimeInfo.insert，並在要求主體中提供 smimeInfo 資源：
Java
Python
管理多位使用者憑證的範例
您可能會想一次管理機構中多位使用者的憑證。以下範例說明如何在單一批次呼叫中管理多位使用者的憑證。
從 CSV 檔案插入憑證
假設您有一份 CSV 檔案，其中列出使用者 ID 和每位使用者憑證的路徑：
$ 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
您可以使用先前提到的 createSmimeInfo 和 insertSmimeInfo 呼叫，依 CSV 檔案中指定的方式上傳憑證：
Python
您可以使用先前提到的 create_smime_info 和 insert_smime_info 呼叫，依 CSV 檔案中指定的方式上傳憑證：
憑證管理功能
這個範例會結合 smimeInfo API 的多個呼叫，說明如何管理貴機構的憑證。它會列出使用者的憑證，如果預設憑證已過期或未設定，就會上傳指定檔案中找到的憑證。然後將到期日最晚的憑證設為預設值。
接著，這會從處理 CSV 檔案的函式呼叫，如前一個範例所示。