Hazelcast IMDG support has expired.

We recommend that you try Hazelcast Platform.

A newer version of IMDG is available.

View latest

Untrusted Deserialization Protection

4.2 4.1 4.0 3.12 3.11 3.10 3.9 3.8 3.7 3.6 3.5

Hazelcast offers a Java deserialization protection based on whitelisting and blacklisting the class/package names. These listings support prefixes.

This protection is controlled using the configuration element java-serialization-filter under serialization, as shown in the example below.

  • XML

  • YAML

<hazelcast>
    ...
    <serialization>
        <java-serialization-filter defaults-disabled="true">
            <whitelist>
		<class>example.Foo</class>
		<package>com.acme.app</package>
		<prefix>com.hazelcast.</prefix>
		<prefix>java.</prefix>
		<prefix>javax.</prefix>
		<prefix>[</prefix>
            </whitelist>
            <blacklist>
                <class>com.acme.app.BeanComparator</class>
            </blacklist>
        </java-serialization-filter>
    </serialization>
    ...
</hazelcast>
hazelcast:
  serialization:
    java-serialization-filter:
      defaults-disabled: true
      whitelist:
        class:
          - example.Foo
        package:
          - com.acme.app
        prefix:
          - com.hazelcast.
          - java.
          - javax.
          - \[
      blacklist:
        class:
          - com.acme.app.BeanComparator

As an alternative, you can also configure it programmatically using the JavaSerializationFilterConfig object, as shown in the below example:

Config config = new Config();
JavaSerializationFilterConfig javaSerializationFilterConfig = new JavaSerializationFilterConfig();
javaSerializationFilterConfig.getWhitelist().addClasses(SomeDeserialized.class.getName());
config.getSerializationConfig().setJavaSerializationFilterConfig(javaSerializationFilterConfig);
Untrusted deserialization protection is not enabled by default. You can enable it simply by setting the element java-serialization-filter or using a non-null JavaSerializationFilterConfig object.

The protection uses a whitelist as the default configuration. When this list is not explicitly provided, the following default prefixes are used for the whitelist:

  • java

  • com.hazelcast.

  • [ (for primitives and arrays)

If you do not want to use the default whitelist prefixes, you must set the defaults-disabled attribute to true.

Once the protection is enabled, the following filtering rules are used when the objects are deserialized:

  • When whitelist is not provided:

    • if the deserialized object’s getClass().getName() is blacklisted or getClass().getPackage().getName() is blacklisted, then deserialization fails

    • deserialization is allowed otherwise.

  • When whitelist is provided:

    • if the deserialized object’s getClass().getName() or getClass().getPackage().getName() is blacklisted, then deserialization fails

    • if the deserialized object’s getClass().getName() or getClass().getPackage().getName() is whitelisted, then deserialization is allowed

    • deserialization fails otherwise.

When deserialization fails, a SecurityException is thrown.

Note that the safest way to provide a protection against untrusted deserialization is using whitelisting (also keep in mind that maintaining such a whitelist can be difficult).

Help and support