Class PropertiesMasker
- java.lang.Object
-
- com.mchange.v2.util.PropertiesMasker
-
public class PropertiesMasker extends java.lang.ObjectRewrites aPropertiesso that it can be written to a log or a diagnostic report without disclosing the credentials configuration routinely carries. The policy it applies -- which names are sensitive, and how a URL-borne credential is concealed -- lives inMaskUtils, which is usable on its own where the thing to be masked is a single value rather than a wholeProperties.Why this exists
A dump of resolved configuration is the most useful diagnostic this library can offer and the most dangerous thing it can print. Asked why a setting is not taking effect, the honest answer is usually "here is every value in force and where each came from" -- and the same dump carries whatever was passed as
-Dmyapp.db.password=..., every credential in a properties file, and the account and password embedded in a JDBC URL. Logs are shipped to aggregators, pasted into issue reports and mailed to vendors, so a dump that is safe only because nobody has raised the log level is not safe.c3p0 has long masked this where it knew exactly what it was holding: AuthMaskingProperties conceals two keys,
userandpassword, because it is looking at a JDBC authentication map and nothing else. That approach does not survive generalization. A dump of System properties holds keys this library has never heard of, named by applications and libraries it will never see, so there is no list to consult. What is left is heuristics over names, plus inspection of values whose shape is known.That the tests are heuristics, and deliberately loose ones, is argued in
MaskUtils-- as is what they retain on purpose, which is as much a part of the contract as what they mask.Two mechanisms, because neither subsumes the other
- Key names. A key whose name contains one of
MaskUtils.DEFAULT_MASKABLE_LOWERCASE_SUBSTRINGShas its whole value replaced. Matching ignores case and ignores separators, so one entry coversapiKey,api.key,api-keyandapi_key-- necessary rather than tidy, since properties conventionally use dots and a naiveapikeywould have matched only the camel-cased spelling. - Values. A
PropertiesMasker.Transformermay rewrite a value the key name cannot judge.DANGEROUS_URL_VALUE_TRANSFORMERis the case that motivated the interface: a JDBC URL carries an account and password inside a value filed under a key called something likejdbcUrl, which is not sensitive by any name test. No key-name heuristic can reach it, and no value heuristic can replace key-name masking.
Transformers get first refusal. They are consulted in turn, and the first to claim a value decides it outright -- key-name masking is then skipped for that key entirely. The ordering is deliberate, and it hands a transformer real discretion: one may claim a value whose key is sensitive by name, rescuing it from wholesale replacement in order to disclose the part that is safe. Showing the scheme, host and database of a connection URL while concealing only the credential is more useful than
****, and a transformer is entitled to make that call.The flip side is that a transformer can reveal what key-name masking would have hidden, so the judgement rests with whoever writes one.
DANGEROUS_URL_VALUE_TRANSFORMERdeclines to exercise the liberty: asked about a value whose key is already sensitive, it returns false and lets whole-value masking proceed, on the grounds that a key namedfoo.passwordtells you nothing about what else its value might carry. That is its own policy, not a rule of this class.What it does not do
This reduces exposure. It does not eliminate it, and should not be described as though it did.
- Masking is not redaction of context. The output still shows which keys are set, and for a URL still shows the scheme, host, port and path. That is the point -- those answer the questions a dump is asked -- but it is disclosure, and a host name can itself be sensitive.
- The name heuristics are a denylist, and a value can hide a secret where no test
reaches. Both limits belong to the policy rather than to this class; they are
set out in
MaskUtils.
The stronger control is therefore
restrictToPrefix, which omits every key outside the prefix from the output rather than merely declining to mask within it. A dump restricted to one library's own keys cannot leak another application's properties at all, whatever they are named, and the heuristics above then serve as defence in depth over a surface small enough to reason about. Prefer it where the audience for the dump is known.Mechanics
An instance is immutable once constructed: the transformer set is copied, and the prefix is final. The substring sets it consults are published on
MaskUtilsand are unmodifiable there, because a caller able to empty them could disable masking for the whole process.shouldMaskValue(java.lang.String)is public and overridable, and aPropertiesMasker.Transformeris handed the masker that is calling it, so a subclass that redefines what counts as sensitive redefines it for the transformers too -- though only for key names: a transformer consulting the URL parameter sets directly, asDANGEROUS_URL_VALUE_TRANSFORMERdoes throughMaskUtils, is not reached by such an override. - Key names. A key whose name contains one of
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interfacePropertiesMasker.Transformer
-
Field Summary
Fields Modifier and Type Field Description static PropertiesMasker.TransformerDANGEROUS_URL_VALUE_TRANSFORMERBringsMaskUtils.maskUrlCredentials(java.lang.String)into aPropertiesdump, so that a connection URL filed under an innocuous key is not disclosed whole.static PropertiesMaskerDEFAULT
-
Constructor Summary
Constructors Constructor Description PropertiesMasker()PropertiesMasker(java.util.Set<PropertiesMasker.Transformer> transformers)PropertiesMasker(java.util.Set<PropertiesMasker.Transformer> transformers, java.lang.String restrictToPrefix)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.Propertiesmasked(java.util.Properties raw)booleanshouldMaskValue(java.lang.String key)
-
-
-
Field Detail
-
DANGEROUS_URL_VALUE_TRANSFORMER
public static final PropertiesMasker.Transformer DANGEROUS_URL_VALUE_TRANSFORMER
BringsMaskUtils.maskUrlCredentials(java.lang.String)into aPropertiesdump, so that a connection URL filed under an innocuous key is not disclosed whole. What it conceals and what it retains are described there; what belongs here is when it declines.It claims a value only when masking actually changed it, so a URL carrying no credentials is left to the ordinary path rather than passing silently through a transformer. And it declines any key that is sensitive by name, forgoing the discretion described above: a key named
foo.passwordsays nothing about what else its value might carry, so partially revealing it is a worse answer than masking it entirely. That is this transformer's policy, not a rule of the class.
-
DEFAULT
public static final PropertiesMasker DEFAULT
-
-
Constructor Detail
-
PropertiesMasker
public PropertiesMasker(java.util.Set<PropertiesMasker.Transformer> transformers, java.lang.String restrictToPrefix)
-
PropertiesMasker
public PropertiesMasker(java.util.Set<PropertiesMasker.Transformer> transformers)
-
PropertiesMasker
public PropertiesMasker()
-
-