...

Apache Commons Net and its SubnetUtils class handles IPv4 CIDR matching nicely. But unfortunately, it does not support IPv6 yet as previously mentioned above. Therefore, our approach is to wait for proposed SubnetUtils6 addition to Apache Commons Net and then use it directly when the dependency is available.

Compatibility

Backward Compatibility

Existing ACLs work exactly as before

...

(i.e., no changes to exact IP or wildcard matching). The CIDR matching logic is additive and only activates when an ACL host pattern contains a '/' character. 

Mixed-version clusters

...

CIDR ACLs cannot be created until all brokers

...

supported them. This is enforced at ACL creation time in AclControlManager.validateHostPattern(). Any attempt to create a CIDR-based ACL on an older metadata version results in a an UnsupportedVersionException (where an user will be warned with specific version,  which is required). This guarantees that CIDR host patterns never appear in AccessControlEntryRecord entries on clusters where brokers may not understand them.

Downgrades safety 

Since CIDR host patterns are persisted in AccessControlEntryRecord metadata records, allowing metadata version downgrade while such records exist would leave the cluster in an inconsistent state (i.e., the ACLs would be still stored and replayed, but older brokers would not regnonize the CIDR format and would fail to match correctly. 

So to prevent this we introduce pre-downgrade validation step. Before any metadata version downgrade is applied, FeatureControlManager invokes a validator registered by QuorumController that checks whether CIDR ACLs currently exists. If the target metadata version does not support CIDR and any ACL host pattern contains CIDR notation, the downgrade is rejected with the error:

Cannot downgrade below IBP_x_x_IVx while CIDR-based ACL host patterns exist.
Remove all CIDR ACLs first.

IPv4-mapped IPv6 address

Javas networking stack automatically resolves IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.0.5) to their native IPv4 form (192.168.0.5). As a result, the host address seen by the authorizer is always the plain IPv4 address. Administrators should use IPv4 CIDR notation (e.g., 192.168.0.0/24) for IPv4 subnets and native IPv6 CIDR notation (e.g., 2001:db8::/32) for IPv6 subnets. Creating ACLs using IPv4-mapped IPv6 CIDR patterns such as ::ffff:192.168.0.0/120 is not supported and will not match IPv4 clients, since the clients resolved address will go through the IPv4 matching path while the ACL pattern would be evaluated as IPv6. 

Test plan

All related stuff within subnet handling is tested via commons-net library via RFC examples for IPv6 and IPv4 (i.e., https://datatracker.ietf.org/doc/html/rfc5952, https://datatracker.ietf.org/doc/html/rfc1519). In AclControlManagerTest, we will cover validation of host patterns (i.e., valid/invalid IPv4 or IPv6 CIDR, null/empty inputs and even malformed prefixes) and metadata version gating (i.e., CIDR rejected on older version, accepted on IBP_x_x_IVx, end-to-end ACL creation with CIDR hosts and backwards compatibility with exact IPs and wildcards on older versions. Moreover, in FeatureControlManagerTest we will cover pre-downgrade validation mechanism i.e, block metadata version downgreade when validator returns an error, allows when downgrade pass. Also in StandardAuthorizerTest, CIDR host matching for IPv4 and IPv6 (boundary addresses, range membership, invalid/null patterns), full authorizer flow iterating all addresses in a /24 and /120 range, and overlaping CIDR ACLs semantics which would confirm DENY always takes precedence regardless of prefix length. The downgrade lifecycle will be tested in AclControlManagerTest (i.e., creating CIDR ACL (on supported version), attempting and failing to downgrade (to un-supported version), removing ACL, then succesfully downgrading).

...

Rejected Alternatives

IP Range Notation (e.g., 10.0.0.1-10.0.0.100) KIP-252 proposed supporting arbitrary IP ranges. We are not doing this because CIDR covers the vast majority of real-world use cases, and adding range support would complicate the implementation without much benefit.

...