本指南介绍了如何使用 Google Workspace Client-side Encryption API 进行加密和解密。
您必须将用户共享加密文件的所有身份提供方 (IdP) 服务列入许可名单。您通常可以在其公开提供的 .well-known 文件中找到所需的 IdP 详细信息;否则,请与组织的 Google Workspace 管理员联系,获取其 IdP 详细信息。
加密数据
当 Google Workspace 用户请求保存或存储客户端加密 (CSE) 数据时,Google Workspace 会向您的 KACLS 端点网址发送 wrap
请求进行加密。除了可选的安全检查(例如基于边界的检查和基于 JWT 声明的检查)之外,您的 KACLS 还必须执行以下步骤:
验证发出请求的用户。
- 验证身份验证令牌和授权令牌。
- 通过对电子邮件声明进行不区分大小写的匹配,检查授权令牌和身份验证令牌是否属于同一用户。
- 当身份验证令牌包含可选的
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 网址匹配。此检查允许检测由内部人员或流氓网域管理员配置的潜在中间人服务器。 - 使用身份验证和授权声明执行边界检查。
使用经过身份验证的加密算法加密以下部分:
- 数据加密密钥 (DEK)
- 授权令牌中的
resource_name
和perimeter_id
值 - 任何其他敏感数据
记录操作,包括发起该操作的用户、
resource_name
以及请求中传递的原因。返回一个不透明的二进制对象,该对象将由 Google Workspace 与加密对象一起存储,并在任何后续密钥解封装操作中按原样发送。或者,提供结构化错误回复。
- 二进制对象应包含加密的 DEK 的唯一副本,其中可以存储特定于实现的数据。
解密数据
当 Google Workspace 用户请求打开客户端加密 (CSE) 数据时,Google Workspace 会向您的 KACLS 端点网址发送 unwrap
请求以进行解密。除了可选的安全检查(例如基于边界的检查和基于 JWT 声明的检查)之外,您的 KACLS 还必须执行以下步骤:
验证发出请求的用户。
- 验证身份验证令牌和授权令牌。
- 通过对电子邮件声明进行不区分大小写的匹配,检查授权令牌和身份验证令牌是否属于同一用户。
- 当身份验证令牌包含可选的
google_email
声明时,必须使用不区分大小写的方法将其与授权令牌中的电子邮件声明进行比较。请勿在此比较中使用身份验证令牌中的电子邮件声明。 - 如果身份验证令牌缺少可选的
google_email
声明,则应使用不区分大小写的方法,将身份验证令牌中的电子邮件声明与授权令牌中的电子邮件声明进行比较。 - 如果 Google 为未与 Google 帐号关联的电子邮件地址颁发授权令牌,则必须存在
email_type
声明。这构成了访客访问功能的关键部分,为 KACLS 提供有价值的信息,以便对外部用户强制执行额外的安全措施。- KACLS 会如何使用此类信息的一些示例如下:
- 强制执行额外的日志记录要求。
- 将身份验证令牌颁发者限制为专用访客 IdP。
- 要求对身份验证令牌进行额外声明。
- 如果客户未配置访客访问权限,则
email_type
设置为google-visitor
或customer-idp
的所有请求都会被拒绝。email_type
为google
或未设置email_type
的请求应继续被接受。
- 检查授权令牌中的
role
声明是否为“reader”或“writer”。 - 检查授权令牌中的
kacls_url
声明是否与当前的 KACLS 网址匹配。这样可以检测由内部人员或流氓网域管理员配置的潜在中间人服务器。
使用经过身份验证的加密算法解密以下部分:
- 数据加密密钥 (DEK)
- 授权令牌中的
resource_name
和perimeter_id
值 - 任何其他敏感数据
检查授权令牌中的
resource_name
与解密后的 blob 是否匹配。使用身份验证和授权声明执行边界检查。
记录操作,包括发起该操作的用户、
resource_name
以及请求中传递的原因。返回解封装的 DEK 或结构化错误回复。