AIP-147 敏感域

2025年2月17日 · [tommwq@126.com]

编号	147
原文链接	https://google.aip.dev/147
状态	批准
创建日期	2020-07-24
更新日期	2020-07-24

有时API需要收集敏感信息，例如用于存储的私钥，出于数据敏感性，这些信息在写入后不应被读取。对于这类敏感数据，需要特别考虑在API请求和应答中的表示方法。

指南

如果敏感信息是资源整体存在的必要条件，数据应当作为只输入域传递，没有对应的输出域。因为资源的存在依赖于敏感数据的存在，API用户可以假定资源的存在意味着敏感数据已存储。例如：

message SelfManagedKeypair {
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // The public key data in PEM-encoded form.
  bytes public_key = 2;

  // The private key data in PEM-encoded form.
  bytes private_key = 3 [
    (google.api.field_behavior) = INPUT_ONLY];
}

如果敏感信息在所属资源中是可选的，应当使用带有 _set 后缀的只输出布尔域表明是否存在敏感信息。例如：

message Integration {
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
  string uri = 2;

  // A secret to be passed in the `Authorization` header of the webhook.
  string shared_secret = 3 [
    (google.api.field_behavior) = INPUT_ONLY];

  // True if a `shared_secret` has been set for this Integration.
  bool shared_secret_set = 4 [
    (google.api.field_behavior) = OUTPUT_ONLY];
}

如果需要识别敏感信息，又不能完全读取敏感信息，可以使用带有 obfuscated_ 前缀的同类型域代替布尔 _set 域，提供敏感数据相关的上下文信息。混淆的具体方法不在本AIP的范围内。例如：

message AccountRecoverySettings {
  // An email to use for account recovery.
  string email = 1 [
    (google.api.field_behavior) = INPUT_ONLY];

  // An obfuscated representation of the recovery email. For example,
  // `ada@example.com` might be represented as `a**@e*****e.com`.
  string obfuscated_email = 2 [
    (google.api.field_behavior) = OUTPUT_ONLY];
}