加密和解密数据

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

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

加密数据

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

  1. 验证提出请求的用户。

    • 同时验证身份验证令牌和授权令牌。
    • 通过对电子邮件声明进行不区分大小写的匹配，检查授权令牌和身份验证令牌是否属于同一用户。
    • 如果身份验证令牌包含可选的 google_email 声明，则必须使用不区分大小写的方法将其与授权令牌中的电子邮件声明进行比较。请勿使用身份验证令牌中的电子邮件声明进行此比较。
    • 如果身份验证令牌缺少可选的 google_email 声明，则应使用不区分大小写的方法将身份验证令牌中的电子邮件声明与授权令牌中的电子邮件声明进行比较。
    • 如果 Google 为未与 Google 账号关联的电子邮件地址签发授权令牌，则必须存在 email_type 声明。 这是 Guest Access 功能的重要组成部分，可为 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 声明。 这是 Guest Access 功能的重要组成部分，可为 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 或结构化错误回复。