Class WhitelistManager
- java.lang.Object
-
- com.mchange.v2.cfg.WhitelistManager
-
- Direct Known Subclasses:
SealedSystemPropertiesWhitelistManager
public class WhitelistManager extends java.lang.ObjectResolves a whitelist of Strings -- in practice fully-qualified class names -- from System properties and an optionalPropertiesConfig, under one shape shared by every whitelist in this library.The keys
A manager is built from one base key, and derives the rest:
<base>.whitelist, and any subkey of it. These union: independent layers of an application can each contribute without having to know what the others wrote, which is the point of the scheme. The naked key counts as one of them. So a library may ship<base>.whitelist.mylib=com.example.Minewhile a deployment writes<base>.whitelist=com.example.Theirs, and both take effect.<base>.overrideWhitelist, which replaces that union rather than adding to it, for a deployment that wants to discard what its libraries contributed.- an optional deprecated key, named in full at construction, for a whitelist that predates this scheme. It does not take its turn in a precedence order at all: whatever the two families above resolved to, the deprecated key intersects with it. Where it is the only thing configured, that intersection is itself, so a deployment still carrying only this key resolves exactly as it always did. Its continued use is nagged about on every resolution.
So precedence proper is override, then the union: the override replaces the union, and the union is consulted only if no override is set. Present-but-empty counts as present in both: an operator who set a key to nothing chose deny-all, and falling through would silently widen it. An empty deprecated key reaches the same end by intersecting everything away.
Why the deprecated key narrows rather than decides
The obvious alternative is for it to decide: while present, be the whole whitelist, and have the other two families ignored. The argument for that is real -- honoring them alongside it could widen a whitelist an existing deployment had already narrowed, and the whole point of keeping this key is that such a deployment keeps what it had. Intersection meets that argument, since it cannot widen anything, and avoids a hazard deciding would introduce.
The hazard is that which key governs sits outside the per-key intersection between the two sources described below. That intersection ensures neither source can widen a key the other also set; it says nothing about a key appearing where no key appeared before. So a deprecated key introduced into the supplied config could displace an
overrideWhitelistan operator had pinned in System properties, and displace it with a wider list -- the one thing the whole scheme exists to prevent. Narrowing closes that: the deprecated key can subtract from the effective whitelist, never add to it, wherever it was written and whoever wrote it.The cost is paid by a deployment that configures both families at once, which gets the intersection rather than the deprecated key whole -- deny-all, if the two are disjoint. That is a misconfiguration being resolved toward denial, consistent with how this class resolves every other conflict, and it is warned about specifically rather than left to surface as an unexplained empty whitelist. Note that no released version ever resolved these keys any other way: the supported families and this key's handling of them arrive together, so no existing configuration changes meaning.
Two sources, and why they intersect
Each key is resolved from both System properties and the supplied config. Where only one names it, that value stands. Where both do and they disagree, the result is their intersection, and a warning says so: a whitelist is a security control, so a name only one source vouches for is not vouched for. Note this makes the two sources peers rather than one overriding the other, and note also that it constrains only keys both sources set -- a key written in just one place is taken whole, so this rule narrows disagreement, it does not make either source untrusted.
Note that there are now two intersections, and they are not the same rule. This one is across the two sources, within one key, and applies to every key. The other is across key families: the deprecated key against whatever the supported keys resolved to. A whitelist can be narrowed by both in one resolution.
The two sentinels
Two entries mean something other than a class name. They resolve conflicts in opposite directions, and both resolve toward denial.
*-- accept anything, only when it is the whitelist's sole element. A*sharing a whitelist with real entries is reported as configured but is not a wildcard, or one layer's*would silently open a gate another layer had narrowed. Callers apply that test themselves: this class hands back what was configured and warns.A lone
*is additionally re-checked against the raw values that produced it.{A,*}from one source intersected with{B,*}from the other yields exactly{*}-- so two sources that each meant to narrow would otherwise combine into accept-everything. A wildcard nobody actually asked for becomes deny-all. Keys that contributed nothing are exempt from that check: a blank key is silent, not dissenting, and must not veto a wildcard another key vouched for.The same protection covers the cross-family intersection. A lone
*surviving the deprecated key's narrowing is honored only where the deprecated list is what the effective whitelist already was -- otherwise{A,*}and{B,*}in the two families would again synthesize an accept-everything neither side wrote.[]-- deny everything. Present in any key of any of the three families above, in either source, it empties the whitelist, regardless of the precedence that would otherwise have ignored that key. It is the veto the additive union would otherwise lack: layers could widen but never narrow.It is deliberately exempt from the intersection rule. Intersection is the conservative resolution for permissions, because dropping one narrows -- but
[]is a denial, and dropping a denial widens. Without the exemption,<key>=[]set by an operator would be annihilated by any disagreeing value for the same key in the other source, leaving other keys' entries in force: the veto would degrade to a no-op.
An empty whitelist reached by accident draws a warning naming both sentinels. One reached by an explicit
[]does not -- the operator already did the thing that warning would advise.What comes back
collectWhitelistInfoSyspropsPropertiesConfig(com.mchange.v2.cfg.PropertiesConfig, com.mchange.v2.log.MLogger)returns aWhitelistInfo, never null, carrying a Set that is never null and theWhitelistInfo.Sourcethat decided it. The source is worth attending to twice over. Diagnostics should name the key actually in force rather than the subkeys an override discarded --makeWhitelistDescriptor(com.mchange.v2.cfg.WhitelistInfo.Source)renders exactly that phrase. Where the deprecated key narrowed a whitelist the supported keys built, both are reported: the source isWhitelistInfo.Source.DEPRECATED, since that is the key whose presence changed the answer, and the returned keys name every key that actually contributed, so a reader is not sent to the wrong half of a configuration. AndWhitelistInfo.Source.MISSINGdistinguishes no whitelist is configured from a configured deny-all, which is the distinction a caller needs if it means to insist that one be configured rather than silently denying everything.Every correction described here -- the
[]veto, the refusal of a spurious wildcard -- is computed outside anyMLogger.isLoggable(com.mchange.v2.log.MLevel)guard. They are security decisions and must not depend on log level; only the warnings about them are conditional.Resolution happens per call, so configuration changes are picked up without invalidating anything. The one piece of retained state is a snapshot used to warn only once, rather than on every resolution, about configurations that are supported but worth mentioning; it is guarded by this instance's monitor.
-
-
Constructor Summary
Constructors Constructor Description WhitelistManager(java.lang.String baseKey, java.lang.String deprecatedKey)
-
Method Summary
-
-
-
Method Detail
-
actuallyConfiguredWhitelist
public static boolean actuallyConfiguredWhitelist(WhitelistInfo info)
-
whitelistIsDisabled
public static boolean whitelistIsDisabled(WhitelistInfo info)
-
getTopLevelBaseKey
public java.lang.String getTopLevelBaseKey()
-
getDeprecatedKey
public java.lang.String getDeprecatedKey()
-
getWhitelistBaseKey
public java.lang.String getWhitelistBaseKey()
-
getOverrideWhitelistKey
public java.lang.String getOverrideWhitelistKey()
-
collectWhitelistInfoSyspropsPropertiesConfig
public WhitelistInfo collectWhitelistInfoSyspropsPropertiesConfig(PropertiesConfig pcfg, MLogger logger)
-
whitelistAccepts
public boolean whitelistAccepts(java.lang.String fqcn, PropertiesConfig pcfg, MLogger logger)
-
whitelistWhyNot
public java.lang.String whitelistWhyNot(java.lang.String fqcn, PropertiesConfig pcfg, MLogger logger, java.lang.String ofWhatPhrase)- Returns:
- null if there is no reason why not! that is, if the whitelist is good and the item is whitelisted.
-
collectWhitelistInfoSyspropsPropertiesConfig
protected WhitelistInfo collectWhitelistInfoSyspropsPropertiesConfig(PropertiesConfig cachedSyspropsConfig, PropertiesConfig pcfg, MLogger logger)
- Parameters:
cachedSyspropsConfig- null means use the current system properties
-
findRawSubkeysWithToken
protected java.util.Set<java.lang.String> findRawSubkeysWithToken(PropertiesConfig cachedSyspropsConfig, java.lang.String baseKey, java.lang.String token, PropertiesConfig pcfg)
-
makeWhitelistDescriptor
public java.lang.String makeWhitelistDescriptor(WhitelistInfo.Source source)
-
-