Class WhitelistInfo

  • All Implemented Interfaces:
    java.io.Serializable

    public class WhitelistInfo
    extends java.lang.Object
    implements java.io.Serializable
    The outcome of one whitelist resolution: the effective whitelist, the configuration keys it was computed from, and which family of keys governed.

    It records a resolution rather than a configuration. The whitelist here is what WhitelistManager arrived at after every narrowing rule it applies, so it is not the union of what the named keys say, and that is the point of reporting the keys alongside it: when an effective whitelist is surprising, its provenance is usually the explanation.

    Instances are immutable, and both sets they expose are unmodifiable. A WhitelistInfo cannot exist in a partly-specified state: all three components are required, and the constructor refuses null for any of them.

    Serialization, and why it is worth the trouble

    Java serialization has been a long-running source of security trouble, and this library reaches for it reluctantly. This class supports it for one concrete reason: it is carried by InstantiationNotPermittedException, and an exception's fields must be serializable or the exception is not. See that class for why that matters — in short, a refusal travels as the cause of a SQLException into application code, and a cause chain containing one non-serializable link cannot be written at all, so the refusal would reach a remote reader as an unrelated I/O error.

    Marking the field transient instead would have serialized without complaint and arrived empty, leaving a refusal able to say that a name was rejected but not against what — discarding the half that makes it actionable, and discarding it silently. So this class does the work itself.

    Deserialization bypasses constructors, which is how serializable value classes acquire states their own invariants forbid. That is not tolerable in a class whose toString() every diagnostic path calls: a null source arriving off a stream would mean an NPE thrown from inside a log statement, while reporting a security refusal. So readObject runs the same validation the constructor runs, reporting a rejection as a InvalidObjectException because that is an IOException and deserializing code is written to catch those; and it re-applies the same hardening, so that a stream supplying a bare mutable set cannot leave an accessor documented as unmodifiable returning something modifiable. The serialized form carries its own version short, so fields may be added later without misreading older streams.

    Validation makes a deserialized instance well-formed, not true. Nothing stops a forged stream describing a whitelist that was never configured. That is acceptable only because this type is a record of a decision, never an input to one: whitelist enforcement resolves the whitelist afresh from live configuration at each gate, and never consults a WhitelistInfo it was handed. Code that begins to trust one it received over a wire would be making a security decision from attacker-supplied bytes.

    See Also:
    WhitelistManager, InstantiationNotPermittedException.getWhitelistInfo(), Serialized Form
    • Constructor Detail

      • WhitelistInfo

        public WhitelistInfo​(java.util.Set<java.lang.String> whitelist,
                             java.util.Set<java.lang.String> fromKeys,
                             WhitelistInfo.Source source)
    • Method Detail

      • getWhitelist

        public java.util.Set<java.lang.String> getWhitelist()
      • getFromKeys

        public java.util.Set<java.lang.String> getFromKeys()
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object