加密和解密数据

本指南介绍了使用 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 的请求。
    • 检查授权令牌中的 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 的请求。
    • 检查授权令牌中的 role 声明是否为“读取器”或“写入器”。
    • 检查授权令牌中的 kacls_url 声明是否与当前的 KACLS 网址匹配。这样一来，便可检测由内部人员或不法网域管理员配置的潜在中间人服务器。

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

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

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

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

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

  6. 返回解封装的 DEK 或结构化错误响应。