2024年12月4日宣布的变更

Protocol Buffers 于 2024年12月4日宣布的变更。

我们计划在 v30 中修改 Protobuf 针对 C++ 的调试 API(包括 Protobuf AbslStringify, `proto2::ShortFormat`, `proto2::Utf8Format`, `Message::DebugString`, `Message::ShortDebugString`, `Message::Utf8DebugString`),以对通过 `debug_redact` 标记的敏感字段进行脱敏;这些 API 的输出将包含一个进程级别的随机前缀,因此将不再能被 Protobuf TextFormat 解析器解析。

动机

目前,Protobuf 调试 API 会将 proto 中的每个字段打印成人类可读的格式。这可能会导致隐私事件,即开发者意外地记录了包含敏感字段的 Protobuf 调试输出。

如何标记敏感字段

有两种方法可以标记敏感字段

  • 直接使用字段选项 `debug_redact = true` 标记字段。

    message Foo {
      optional string secret = 1 [debug_redact = true];
    }
    
  • 如果你已经通过扩展 `proto2.FieldOptions` 定义了一个 Enum 类型的字段注解,并且此注解的某些值用于标记你想脱敏的字段,那么你可以使用 `debug_redact = true` 来标记这些值。所有用此类值标记的字段都将进行脱敏。

    package my.package;
    
    extend proto2.FieldOptions {
      # The existing field annotation
      optional ContentType content_type = 1234567;
    };
    
    enum ContentType {
      PUBLIC = 0;
      SECRET = 1 [debug_redact = true];
    };
    
    message Foo {
      # will not be redacted
      optional string public_info = 1 [
        (my.package.content_type) = PUBLIC
      ];
      # will be redacted
      optional string secret = 1 [
        (my.package.content_type) = SECRET
      ];
    }
    

新的调试格式

与现有的调试格式相比,新的调试格式有两个主要区别

  • 用 `debug_redact` 标记的敏感字段会在输出格式中自动脱敏
  • 输出格式将包含一个进程级别的随机前缀,这将使它们不再能被 TextFormat 解析器解析。

请注意,无论 proto 是否包含敏感字段,第二个变更都成立,这确保了任何调试输出始终无法被反序列化,无论 proto 内容如何。