Skip to main content
Version: 1.2.0

Type Registration

This page covers class registration mechanisms and security configurations.

Class Registration​

ForyBuilder#requireClassRegistration can be used to disable class registration. This will allow deserializing objects of unknown types, which is more flexible but may be insecure if the classes contain malicious code.

Do not disable class registration unless you can ensure your environment is secure. Malicious code in init/equals/hashCode can be executed when deserializing unknown/untrusted types when this option is disabled.

Class registration can not only reduce security risks, but also avoid classname serialization cost.

Register by ID​

You can register class with API Fory#register:

Fory fory = xxx;
fory.register(SomeClass.class);
fory.register(SomeClass1.class, 1);

Note that class registration order is important. Serialization and deserialization peers should have the same registration order. Register classes and custom serializers before the first top-level serialize, deserialize, or copy call on a Fory instance. Fory freezes registration at that point so serializer lookups can use the finalized registration state.

Internal type IDs 0-32 are reserved for built-in xlang types. Java native built-ins start at Types.NONE + 1, and user IDs are encoded as (user_id << 8) | internal_type_id.

Register by Name​

Register class by ID has better performance and smaller space overhead. But in some cases, management for a bunch of type IDs is complex. In such cases, registering class by name using API register(Class<?> cls, String name) is recommended. Use . inside the name to add a namespace prefix:

fory.register(Foo.class, "demo.Foo");

If there are no duplicate names for types, use a name without a namespace prefix to reduce serialized size.

Do not use this API to register class since it will increase serialized size a lot compared to registering class by ID.

Security Configuration​

Type Checker​

If you invoke ForyBuilder#requireClassRegistration(false) to disable class registration check, you can configure org.apache.fory.resolver.TypeChecker by ForyBuilder#withTypeChecker or TypeResolver#setTypeChecker to control which classes are allowed for serialization.

For example, you can allow classes started with org.example.*:

Fory fory = Fory.builder().withXlang(false)
  .requireClassRegistration(false)
  .withTypeChecker((typeResolver, className) -> className.startsWith("org.example."))
  .build();

AllowListChecker​

Fory provides a org.apache.fory.resolver.AllowListChecker which is an allowed/disallowed list based checker to simplify the customization of class check mechanism:

AllowListChecker checker = new AllowListChecker(AllowListChecker.CheckLevel.STRICT);
checker.allowClass("org.example.*");
ThreadSafeFory fory = Fory.builder().withXlang(false)
  .requireClassRegistration(false)
  .withTypeChecker(checker)
  .buildThreadSafeFory();

withTypeChecker installs the checker on every created Fory instance immediately, which also avoids the generic startup warning emitted when class registration is disabled without any checker. You can still use TypeResolver#setTypeChecker or ThreadSafeFory#setTypeChecker later if you need to replace the checker after build time.

Limit Max Deserialization Depth​

Fory provides ForyBuilder#withMaxDepth to limit max deserialization depth. The default max depth is 50.

If max depth is reached, Fory will throw ForyException. This can be used to prevent malicious data from causing stack overflow or other issues.

Fory fory = Fory.builder()
  .withXlang(false)
  .withMaxDepth(100)  // Set custom max depth
  .build();

Best Practices​

  1. Always enable class registration in production: Use requireClassRegistration(true)
  2. Use ID-based registration for performance: Numeric IDs are faster than string names
  3. Maintain consistent registration order: Same order on both serialization and deserialization sides
  4. Set appropriate max depth: Prevent stack overflow attacks
  5. Use AllowListChecker for fine-grained control: When you need flexible class filtering