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?

note

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

xml

<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>

YAML

yaml

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

Java

java

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.

warning

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

xml

<hazelcast>
    <serialization>
        <allow-override-default-serializers>true</allow-override-default-serializers>
    </serialization>
</hazelcast>

YAML

xml

hazelcast:
    serialization:
        allow-override-default-serializers: true

Java

java

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.

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

xml

<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>

YAML

yaml

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

Java

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