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:

For security, do you want to stop malicious Java classes from being deserialized in your cluster?

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`	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" );

Edit this page Report an issue