Class Check Mechanism

Understanding Dubbo’s Class Check Mechanism

Feature Description

This mechanism ensures compatibility and security between service providers and consumers.

Use Cases

To prevent potential issues due to class version mismatches, incompatible method signatures, or missing classes.

Usage

Supported Versions Dubbo >= 3.1.6

Applicable Scope Currently, serialization checks support Hessian2, Fastjson2 serialization, and generic calls. Other serialization methods are not supported.

Check Modes

The check mode has three levels: STRICT, WARN, DISABLE. STRICT: Disallows deserialization of all classes not in the allowed serialization list (whitelist). WARN: Only disallows serialization of classes in the disallowed serialization list (blacklist) and logs a warning when deserializing classes not in the allowed serialization list (whitelist). DISABLE: No checks at all.

The default for version 3.1 is WARN, while for version 3.2, it is STRICT.

Configuration via ApplicationConfig:

  1. ApplicationConfig applicationConfig = new ApplicationConfig();
  2. applicationConfig.setSerializeCheckStatus("STRICT");

Configuration via Spring XML:

  1. <dubbo:application name="demo-provider" serialize-check-status="STRICT"/>

Configuration via Spring Properties / dubbo.properties:

  1. dubbo.application.serialize-check-status=STRICT

Configuration via System Property:

  1. -Ddubbo.application.serialize-check-status=STRICT

After successful configuration, the following log message can be seen:

  1. INFO utils.SerializeSecurityManager:  [DUBBO] Serialize check level: STRICT

Note: If multiple applications in the same process (Dubbo Framework Model) have different check modes configured, the “loosest” level will take effect. For instance, if two Spring contexts are started, one set to STRICT and one to WARN, the WARN level configuration will take effect.

Serializable Interface Checks

The Serializable interface check mode has two levels: true (enabled) and false (disabled). When enabled, it rejects deserialization of all classes that do not implement Serializable.

By default, Dubbo configures this as true.

Configuration via ApplicationConfig:

  1. ApplicationConfig applicationConfig = new ApplicationConfig();
  2. applicationConfig.setCheckSerializable(true);

Configuration via Spring XML:

  1. <dubbo:application name="demo-provider" check-serializable="true"/>

Configuration via Spring Properties / dubbo.properties:

  1. dubbo.application.check-serializable=true

Configuration via System Property:

  1. -Ddubbo.application.check-serializable=true

After successful configuration, the following log message can be seen:

  1. INFO utils.SerializeSecurityManager:  [DUBBO] Serialize check serializable: true

Note 1: If multiple applications in the same process have different Serializable interface check modes, the “loosest” level will take effect. For example, if one is set to true and another to false, the false configuration will take effect. Note 2: Currently, the built-in Serializable check configurations for Hessian2 and Fastjson2 are not connected. For generic calls, configuring dubbo.application.check-serializable is sufficient to modify the check configuration; for Hessian2 serialization, both dubbo.application.check-serializable and dubbo.hessian.allowNonSerializable need to be modified; for Fastjson2 serialization, modification is not currently supported.

Auto-Scanning Configuration

Dubbo’s automatic class scanning mechanism has two configuration items: AutoTrustSerializeClass for enabling automatic scanning and TrustSerializeClassLevel for class trust levels.

In simple terms, after enabling automatic class scanning, Dubbo will automatically scan all related classes used by interfaces through ReferenceConfig and ServiceConfig, recursively trusting their package. The TrustSerializeClassLevel can limit which package levels are ultimately trusted.

The default configuration sets AutoTrustSerializeClass to true and TrustSerializeClassLevel to 3.

Configuration via ApplicationConfig:

  1. ApplicationConfig applicationConfig = new ApplicationConfig();
  2. applicationConfig.setAutoTrustSerializeClass(true);
  3. applicationConfig.setTrustSerializeClassLevel(3);

Configuration via Spring XML:

  1. <dubbo:application name="demo-provider" auto-trust-serialize-class="true" trust-serialize-class-level="3"/>

Configuration via Spring Properties / dubbo.properties:

  1. dubbo.application.auto-trust-serialize-class=true
  2. dubbo.application.trust-serialize-class-level=3

Configuration via System Property:

  1. -Ddubbo.application.auto-trust-serialize-class=true
  2. -Ddubbo.application.trust-serialize-class-level=3

After successful configuration, you can check the loaded trusted class results against expectations using QoS commands.

Note: There will be some performance overhead during startup after enabling checks.

Custom Trusted/Untrusted Class Configuration

In addition to Dubbo’s automatic scanning, you can also configure trusted/untrusted class lists via resource files.

Configuration method: Define the following files in the resource directory.

  1. # security/serialize.allowlist
  2. io.dubbo.test
  1. # security/serialize.blockedlist
  2. io.dubbo.block

After successful configuration, the following log messages can be seen:

  1. INFO utils.SerializeSecurityConfigurator:  [DUBBO] Read serialize allow list from file:/Users/albumen/code/dubbo-samples/99-integration/dubbo-samples-serialize-check/target/classes/security/serialize.allowlist
  2. INFO utils.SerializeSecurityConfigurator:  [DUBBO] Read serialize blocked list from file:/Users/albumen/code/dubbo-samples/99-integration/dubbo-samples-serialize-check/target/classes/security/serialize.blockedlist

The configuration priority is as follows: User-defined trusted classes = Framework built-in trusted classes > User-defined untrusted classes = Framework built-in untrusted classes > Automatically scanned trusted classes.

Audit Methods

Dubbo supports viewing current configuration information and trusted/untrusted class lists in real-time via QoS commands. Currently, there are two supported commands: serializeCheckStatus to view current configuration information, and serializeWarnedClasses to view the real-time warning list.

  1. serializeCheckStatus to view current configuration information

Access via console:

  1. > telnet 127.0.0.1 22222
  2. Trying 127.0.0.1...
  3. Connected to localhost.
  4. Escape character is '^]'.
  5.    ___   __  __ ___   ___   ____     
  6.   / _ \ / / / // _ ) / _ ) / __ \  
  7.  / // // /_/ // _  |/ _  |/ /_/ /    
  8. /____/ \____//____//____/ \____/   
  9. dubbo>serializeCheckStatus
  10. CheckStatus: WARN
  12. CheckSerializable: true
  14. AllowedPrefix:
  15. ...
  17. DisAllowedPrefix:
  18. ...
  20. dubbo>

Access via HTTP request for JSON format result:

  1. > curl http://127.0.0.1:22222/serializeCheckStatus      
  2. {"checkStatus":"WARN","allowedPrefix":[...],"checkSerializable":true,"disAllowedPrefix":[...]}
  1. serializeWarnedClasses to view real-time warning list

Access via console:

  1. > telnet 127.0.0.1 22222                          
  2. Trying 127.0.0.1...
  3. Connected to localhost.
  4. Escape character is '^]'.
  5.    ___   __  __ ___   ___   ____     
  6.   / _ \ / / / // _ ) / _ ) / __ \  
  7.  / // // /_/ // _  |/ _  |/ /_/ /    
  8. /____/ \____//____//____/ \____/   
  9. dubbo>serializeWarnedClasses
  10. WarnedClasses: 
  11. io.dubbo.test.NotSerializable
  12. io.dubbo.test2.NotSerializable
  13. io.dubbo.test2.OthersSerializable
  14. org.apache.dubbo.samples.NotSerializable
  16. dubbo>

Access via HTTP request for JSON format result:

  1. > curl http://127.0.0.1:22222/serializeWarnedClasses
  2. {"warnedClasses":["io.dubbo.test2.NotSerializable","org.apache.dubbo.samples.NotSerializable","io.dubbo.test.NotSerializable","io.dubbo.test2.OthersSerializable"]}

It is advisable to pay attention to the results of serializeWarnedClasses in a timely manner to determine if an attack is occurring.

Feedback

Was this page helpful?

Yes No

Last modified September 30, 2024: Update & Translate Overview Docs (#3040) (d37ebceaea7)