加密和解密数据

本指南介绍了如何使用 Google Workspace 客户端加密 API 进行加密和解密。

您必须将共享加密文件的用户使用的任何身份提供方 (IdP) 服务添加到许可名单中。您通常可以在其公开提供的 .well-known 文件中找到所需的 IdP 详细信息；否则，请与组织的 Google Workspace 管理员联系以获取其 IdP 详细信息。

加密数据

当 Google Workspace 用户请求保存或存储客户端加密 (CSE) 数据时，Google Workspace 会向您的密钥访问权限控制列表服务 (KACLS) 端点网址发送 wrap 请求以进行加密。除了可选的安全检查（例如边界检查和基于 JWT 声明的检查）之外，您的 KACLS 还必须执行以下步骤：

  1. 验证请求用户。

    • 同时验证 身份验证 令牌 和 授权 令牌。
    • 通过对电子邮件声明进行不区分大小写的匹配，检查授权令牌和身份验证令牌是否属于同一用户。
    • 当身份验证令牌包含可选的 google_email 声明时，必须使用不区分大小写的方法将其与授权令牌中的电子邮件声明进行比较。请勿使用身份验证令牌中的电子邮件声明进行此比较。
    • 如果身份验证令牌缺少可选的 google_email 声明，则应使用不区分大小写的方法将身份验证令牌中的电子邮件声明与授权令牌中的电子邮件声明进行比较。
    • 如果 Google 为未与 Google 账号关联的电子邮件地址签发授权令牌，则必须提供 email_type 声明。 这是访客访问权限功能的重要组成部分，可为 KACLS 提供有价值的信息，以便对外部用户强制执行额外的安全措施。
      • 以下是一些示例，说明 KACLS 如何使用此信息：
      • 施加额外的日志记录要求。
      • 将身份验证令牌签发者限制为专用访客 IdP。
      • 要求在身份验证令牌中提供额外的声明。
      • 如果客户未配置访客访问权限，则可以拒绝所有将 email_type 设置为 google-visitor 或 customer-idp 的请求。对于 email_type 为 google 或未设置 email_type 的请求，应继续接受。
    • 当身份验证令牌包含可选的 delegated_to 声明时，它还必须包含 resource_name 声明，并且必须将这两个声明与授权令牌中的 delegated_to 和 resource_name 声明进行比较。应使用不区分大小写的方法比较 delegated_to 声明，并且令牌中的 resource_name 应与操作的 resource_name 匹配。
    • 检查授权令牌中的 role 声明是否为 writer 或 upgrader。
    • 检查授权令牌中的 kacls_url 声明是否与当前的 KACLS 网址匹配。此检查可以检测内部人员或恶意网域管理员配置的潜在中间人服务器。
    • 使用身份验证声明和授权声明执行边界检查。

  2. 使用经过身份验证的加密算法加密以下部分：

    • 数据加密密钥 (DEK)
    • 授权令牌中的 resource_name 和 perimeter_id 值
    • 任何其他敏感数据

  3. 记录操作，包括发起操作的用户、resource_name 和请求中传递的原因。

  4. 返回一个不透明的二进制对象，供 Google Workspace 与加密对象一起存储，并在任何后续密钥解包操作中按原样发送。或者，提供结构化错误 回复。

    • 二进制对象应包含加密 DEK 的唯一副本，并且可以在其中存储实现特定数据。

解密数据

当 Google Workspace 用户请求打开客户端加密 (CSE) 数据时，Google Workspace 会向您的 KACLS 端点网址 发送 unwrap 请求以进行解密。除了可选的安全检查（例如边界检查和基于 JWT 声明的检查）之外，您的 KACLS 还必须执行以下步骤：

  1. 验证请求用户。

    • 同时验证 身份验证 令牌 和 授权 令牌。
    • 通过对电子邮件声明进行不区分大小写的匹配，检查授权令牌和身份验证令牌是否属于同一用户。
    • 当身份验证令牌包含可选的 google_email 声明时，必须使用不区分大小写的方法将其与授权令牌中的电子邮件声明进行比较。请勿使用身份验证令牌中的电子邮件声明进行此比较。
    • 如果身份验证令牌缺少可选的 google_email 声明，则应使用不区分大小写的方法将身份验证令牌中的电子邮件声明与授权令牌中的电子邮件声明进行比较。
    • 如果 Google 为未与 Google 账号关联的电子邮件地址签发授权令牌，则必须提供 email_type 声明。 这是访客访问权限功能的重要组成部分，可为 KACLS 提供有价值的信息，以便对外部用户强制执行额外的安全措施。
      • 以下是一些示例，说明 KACLS 如何使用此信息：
      • 施加额外的日志记录要求。
      • 将身份验证令牌签发者限制为专用访客 IdP。
      • 要求在身份验证令牌中提供额外的声明。
      • 如果客户未配置访客访问权限，则可以拒绝所有将 email_type 设置为 google-visitor 或 customer-idp 的请求。对于 email_type 为 google 或未设置 email_type 的请求，应继续接受。
    • 当身份验证令牌包含可选的 delegated_to 声明时，它还必须包含 resource_name 声明，并且必须将这两个声明与授权令牌中的 delegated_to 和 resource_name 声明进行比较。应使用不区分大小写的方法比较 delegated_to 声明，并且令牌中的 resource_name 应与操作的 resource_name 匹配。
    • 检查授权令牌中的 role 声明是否为 reader 或 writer。
    • 检查授权令牌中的 kacls_url 声明是否与当前的 KACLS 网址匹配。此检查可以检测内部人员或恶意网域管理员配置的潜在中间人服务器。

  2. 使用经过身份验证的加密算法解密以下部分：

    • 数据加密密钥 (DEK)
    • 授权令牌中的 resource_name 和 perimeter_id 值
    • 任何其他敏感数据

  3. 检查授权令牌和解密 Blob 中的 resource_name 是否匹配。

  4. 使用身份验证声明和授权声明执行边界检查。

  5. 记录操作，包括发起操作的用户、resource_name 和请求中传递的原因。

  6. 返回解包的 DEK 或 结构化错误 回复。