A newer version of Hazelcast Platform is available.

View latest

Configuring Serializers

You can configure clusters to be able to serialize and deserialize custom objects and classes as well as override built-in serializers and whitelist certain Java classes.

Production Checklist

Before you start configuring members, consider the following checklist:

Running clusters must be restarted before any configuration changes take effect.

Disallowing Deserialization of Untrusted Java Classes

To stop Hazelcast from deserializing arbitrary classes, you can allow or disallow deserialization of Java classes by class name or package name, using the java-serialization-filter option.

The following filtering rules are used when the objects are deserialized:

  • When the whitelist option is empty:

    • If the deserialized object’s class name or package name is blacklisted, deserialization fails.

    • Otherwise, deserialization is allowed.

  • When the whitelist option is provided:

    • If the deserialized object’s class name or package name is blacklisted, deserialization fails.

    • If the deserialized object’s class name or package name is whitelisted, deserialization is allowed

    • Otherwise, deserialization fails.

When deserialization fails, a SecurityException is thrown.

By default, class names or package names that have these prefixed are allowed:

  • java

  • com.hazelcast.

  • [ (for primitives and arrays)

If you do not want to allow these default prefixes, set the defaults-disabled attribute to true.

  • XML

  • YAML

  • Java

<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
Config config = new Config();
JavaSerializationFilterConfig javaSerializationFilterConfig = new JavaSerializationFilterConfig();
javaSerializationFilterConfig.getWhitelist().addClasses(SomeDeserialized.class.getName());
config.getSerializationConfig().setJavaSerializationFilterConfig(javaSerializationFilterConfig);

Overriding the Built-in Serializers

To enable your cluster to override the built-in serializers, set the allow-override-default-serializers option to true.

Built-in serializers are used heavily by Hazelcast internals. If any of the instances in a cluster overrides a built-in serializer, all members and clients in that cluster must override it with the same serializer.

You should override the built-in serializers only for the following use case:

You implement serialization of a type, and Hazelcast later adds a built-in serializer for the same type in a future release.

  • XML

  • YAML

  • Java

<hazelcast>
    <serialization>
        <allow-override-default-serializers>true</allow-override-default-serializers>
    </serialization>
</hazelcast>
hazelcast:
    serialization:
        allow-override-default-serializers: true
SerializationConfig{
  boolean isAllowOverrideDefaultSerializers();

  SerializationConfig setAllowOverrideDefaultSerializers(final boolean allowOverrideDefaultSerializers);}

Configuration Options

Use these configuration options to configure serialization:

Deprecation Notice for Portable Serialization

Portable Serialization has been deprecated. We recommend you use Compact Serialization as Portable Serialization will be removed as of version 7.0.

Table 1. Serialization configuration options
Option Description Default

portable-version

Defines the version of a portable serialization implementation. A portable version differentiates two of the same classes that have differ such as those that have different fields or different field types.

0

use-native-byte-order

Whether to use the native byte order of the underlying platform.

false

byte-order

Defines the byte order that the serialization uses: BIG_ENDIAN or LITTLE_ENDIAN.

BIG_ENDIAN

enable-compression

Enables compression if the default Java serialization is used.

false

enable-shared-object

Enables shared object if the default Java serialization is used.

false

allow-unsafe

Whether to allow unsafe to be used.

false

allow-override-default-serializers

Whether to allow built-in serializers to be overridden.

false

data-serializable-factory

Registers a class that implements com.hazelcast.nio.serialization.DataSerializableFactory. See Registering EmployeeDataSerializableFactory

portable-factory

Registers a PortableFactory class. See Registering the Portable Factory

global-serializer

Registers a global serializer class to be used when no other serializer is available. This element has the optional boolean attribute override-java-serialization. When set to true, the Java serialization step is assumed to be handled by the global serializer. Default: false. See Global Serializer.

serializer

The class name of the custom serializer implementation. See Custom Serialization

check-class-def-errors

Whether to check for class definition errors at startup and throw a serialization exception with an error definition.

java-serialization-filter

Provides deserialization protection based on whitelisting and blacklisting the class/package names.

compact-serialization-config (beta)

Provides ways to enable Compact serialization and register explicit or reflective compact serializers for classes. See CompactSerializationConfig section for details.

Full Example of Serialization Configuration

The following are example configuration settings for various serializers.

  • XML

  • YAML

  • Java

<hazelcast>
    <serialization>
        <portable-version>0</portable-version>
        <use-native-byte-order>false</use-native-byte-order>
        <byte-order>BIG_ENDIAN</byte-order>
        <data-serializable-factories>
            <data-serializable-factory factory-id="1">com.hazelcast.examples.DataSerializableFactory
            </data-serializable-factory>
        </data-serializable-factories>
        <portable-factories>
            <portable-factory factory-id="1">com.hazelcast.examples.PortableFactory</portable-factory>
        </portable-factories>
        <serializers>
            <global-serializer>com.hazelcast.examples.GlobalSerializerFactory</global-serializer>
            <serializer type-class="com.hazelcast.examples.DummyType"
                        class-name="com.hazelcast.examples.SerializerFactory"/>
        </serializers>
        <check-class-def-errors>true</check-class-def-errors>
        <java-serialization-filter defaults-disabled="true">
            <blacklist>
                <class>com.acme.app.BeanComparator</class>
            </blacklist>
            <whitelist>
                <class>java.lang.String</class>
                <class>example.Foo</class>
                <package>com.acme.app</package>
                <package>com.acme.app.subpkg</package>
                <prefix>com.hazelcast.</prefix>
                <prefix>java</prefix>
            </whitelist>
        </java-serialization-filter>
    </serialization>
</hazelcast>
hazelcast:
  serialization:
    portable-version: 0
    use-native-byte-order: false
    byte-order: BIG_ENDIAN
    data-serializable-factories:
      - factory-id: 1
        class-name: com.hazelcast.examples.DataSerializableFactory
    portable-factories:
      - factory-id: 1
        class-name: com.hazelcast.examples.PortableFactory
    global-serializer:
      class-name: com.hazelcast.examples.GlobalSerializerFactory
    serializers:
      - type-class: com.hazelcast.examples.DummyType
        class-name: com.hazelcast.examples.SerializerFactory
    check-class-def-errors: true
    java-serialization-filter:
      defaults-disabled: true
      blacklist:
        class:
          - com.acme.app.BeanComparator
      whitelist:
        class:
          - java.lang.String
          - example.Foo
        package:
          - com.acme.app
          - com.acme.app.subpkg
        prefix:
          - com.hazelcast.
          - java
Config config = new Config();
SerializationConfig srzConfig = config.getSerializationConfig();
srzConfig.setPortableVersion( "2" ).setUseNativeByteOrder( true );
srzConfig.setAllowUnsafe( true ).setEnableCompression( true );
srzConfig.setCheckClassDefErrors( true );

GlobalSerializerConfig globSrzConfig = srzConfig.getGlobalSerializerConfig();
globSrzConfig.setClassName( "abc.Class" );

SerializerConfig serializerConfig = srzConfig.getSerializerConfig();
serializerConfig.setTypeClass( "Employee" )
                .setClassName( "com.EmployeeSerializer" );