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
- 此范围是更新主要“发件人别名”S/MIME 所必需的。
- gmail.settings.sharing
- 此范围是更新自定义 from 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,该 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 文件的函数(如上一个示例中所示)调用此函数。