Add info about security filters [DOC-768]#2264
Conversation
|
Preview deployment: https://6a6225a6e24a933b1cce6642--hazelcast-docs-uat.netlify.app |
| xref:security:tls-ssl.adoc#mutual-authentication[mutual TLS authentication] and disabling xref:clusters:network-configuration.adoc#multicast-element[multicast join] configuration. | ||
| We recommend using Java serialization filter configuration for whitelisting the set of trusted classes or | ||
| packages which are allowed for deserialization. | ||
| * Hazelcast can fall back to zero-configuration Compact serialization for classes that have no explicit serializer. We recommend restricting the classes eligible for zero-config Compact serialization by defining an allowlist of only the classes your application needs, rather than relying on the default behavior. See xref:serialization:compact-serialization.adoc#zero-config-filter[Restricting Classes for Zero-Config Compact Serialization]. |
There was a problem hiding this comment.
| * Hazelcast can fall back to zero-configuration Compact serialization for classes that have no explicit serializer. We recommend restricting the classes eligible for zero-config Compact serialization by defining an allowlist of only the classes your application needs, rather than relying on the default behavior. See xref:serialization:compact-serialization.adoc#zero-config-filter[Restricting Classes for Zero-Config Compact Serialization]. | |
| * Hazelcast can use zero-configuration Compact serialization for eligible classes that have no explicit serializer. We recommend restricting the classes allowed to use zero-config Compact serialization by defining an allowlist of only the classes your application needs, rather than relying on the default behavior. See xref:serialization:compact-serialization.adoc#zero-config-filter[Restricting Classes for Zero-Config Compact Serialization]. | |
| If you do not use zero-configuration Compact serialization, disable defaults and configure empty allowlist for best security. |
@th0masb could you verify this, in particular the requirement about disabling defaults to configure empty allowlist. We might have discussed this previously, but I realized (again?) that this is a bit unfortunate. If you start with empty allowlist and disabled defaults, but then want to add some unreasonable classes to allowlist (eg. com.hazelcast) you lose the safety net of default blocklist.
|
|
||
| Zero-config Compact serialization uses reflection to serialize any class that does not have another registered serializer. To control which classes are eligible for this, and to prevent classes from being serialized unintentionally, configure a filter that allows or blocks classes. | ||
|
|
||
| The filter uses an allowlist and a blocklist. This is the same format as the xref:sql:sql-reflection-configuration.adoc[SQL Java reflection filter]. You can allow or block classes by fully qualified class name, package name, or class-name prefix. The filter can be set on both members and clients. |
There was a problem hiding this comment.
it is better to link to https://docs.hazelcast.com/hazelcast/5.7/serialization/serialization-configuration#untrusted-classes instead of SQL docs (SQL is a specific feature)
| xref:security:tls-ssl.adoc#mutual-authentication[mutual TLS authentication] and disabling xref:clusters:network-configuration.adoc#multicast-element[multicast join] configuration. | ||
| We recommend using Java serialization filter configuration for whitelisting the set of trusted classes or | ||
| packages which are allowed for deserialization. | ||
| * Hazelcast can fall back to zero-configuration Compact serialization for classes that have no explicit serializer. We recommend restricting the classes eligible for zero-config Compact serialization by defining an allowlist of only the classes your application needs, rather than relying on the default behavior. See xref:serialization:compact-serialization.adoc#zero-config-filter[Restricting Classes for Zero-Config Compact Serialization]. |
There was a problem hiding this comment.
I would also add a recomendation to configure serialization restrictions (Java - previous point) and ZCCS (this point) not only on members but also on clients. And they do not have to be the same, although blocked classes will not be usable in client/member that has them blocked.
| When a filter is configured: | ||
|
|
||
| * If a class is on the blocklist, serializing an object of that class throws an exception. | ||
| * If a class is on the blocklist, deserializing its data returns a `GenericRecord` instead of an instance of the class, rather than throwing an exception. |
There was a problem hiding this comment.
this is actually quite nice feature, possibly worth highlighting a bit more. some features like PredicateAPI/SQL query can process a compact-serialized class even if it is blocked from serialization, because extracting individual fields without object creation is safe.
entry processor or other member-side code can use GenericRecord to access the data, which may be sufficient in some cases
|
|
||
| * If a class is on the blocklist, serializing an object of that class throws an exception. | ||
| * If a class is on the blocklist, deserializing its data returns a `GenericRecord` instead of an instance of the class, rather than throwing an exception. | ||
| * If the allowlist is non-empty, only classes on the allowlist (and not on the blocklist) are eligible for zero-config Compact serialization. |
There was a problem hiding this comment.
only classes on the allowlist (and not on the blocklist)
both conditions need to be met. partentheses introduce a bit of assymetry in the text. Maybe:
| * If the allowlist is non-empty, only classes on the allowlist (and not on the blocklist) are eligible for zero-config Compact serialization. | |
| * If the allowlist is non-empty, only classes on the allowlist which are not on the blocklist are eligible for zero-config Compact serialization. |
?
|
|
||
| The filter uses an allowlist and a blocklist. This is the same format as the xref:sql:sql-reflection-configuration.adoc[SQL Java reflection filter]. You can allow or block classes by fully qualified class name, package name, or class-name prefix. The filter can be set on both members and clients. | ||
|
|
||
| When a filter is configured: |
There was a problem hiding this comment.
describe also how to configure empty filter to effectively disable ZCCS
| [[zero-config-filter]] | ||
| == Restricting Classes for Zero-Config Compact Serialization | ||
|
|
||
| Zero-config Compact serialization uses reflection to serialize any class that does not have another registered serializer. To control which classes are eligible for this, and to prevent classes from being serialized unintentionally, configure a filter that allows or blocks classes. |
There was a problem hiding this comment.
these restrictions apply only to ZCCS. it is possible to register explicit serializers for classes that are not allowed for ZCCS.
2 participants
https://hazelcast.atlassian.net/browse/DOC-768
Documents the SQL reflection and zero-config Compact serialisation filters.