Class MaskUtils
- java.lang.Object
-
- com.mchange.v2.util.MaskUtils
-
public final class MaskUtils extends java.lang.ObjectThe policy of value masking, held apart from any one place it is applied: which names are taken to be sensitive, and how a credential carried inside a URL is concealed. Stateless, and with no dependence onProperties, so a caller holding a single String can reach it.PropertiesMaskeris this same policy applied across a wholeProperties, and carries the account of why masking is wanted at all.The separation earns its keep because the places that most need masking are not all property dumps. A
toString()that reports a JDBC URL, an exception message naming the URL that failed to parse, a log line reporting a JNDI environment -- each holds one value and wants one answer, and should not have to assemble aPropertiesto get it.The asymmetry that licenses heuristics
The two ways of being wrong cost very different amounts. Masking something harmless costs one diagnostic value. Failing to mask a credential discloses it, to everyone who ever reads the log, with no way to recall it. So the substring tests here are deliberately loose, and
passmatchingbypassorcompassis an accepted price rather than a defect.Loose, but not unbounded, because the opposite failure is real too: a masker that returned
******for everything would disclose nothing and be worthless. The retentions are as much a part of the contract as the maskings. Two are worth naming, because the obvious substrings would have destroyed them.keyanduserare substrings of a wide variety of useful-to-debug configuration.userwould maskuser.homeanduser.dir, which are exactly what someone debugging afile:config source or a HOCON${user.home}substitution needs to see. Hence the narrow compounds (apikey,accesskey). We don't considerusersensitive, and don't mask it here (although users are welcome to overridepublic boolean shouldMaskValue(String key)in our siblingPropertiesMaskerto mask anything they wish).What we do not do
- A secret in a URL path is out of reach. A Slack webhook is
https://hooks.slack.com/services/T000/B000/XXXX-- the credential is a path segment, not userinfo and not a parameter. Masking paths wholesale would destroy the diagnostic value of every JDBC URL, so such values are caught only when their key name gives them away, which is a judgement this class cannot make from the value alone. - Name heuristics are a denylist. A credential under a name containing no sensitive substring is disclosed. Nothing here can know otherwise.
- A secret in a URL path is out of reach. A Slack webhook is
-
-
Field Summary
Fields Modifier and Type Field Description static java.util.Set<java.lang.String>DEFAULT_MASKABLE_LOWERCASE_SUBSTRINGSNames containing any of these, normalized, are taken to name a secret.static java.util.Set<java.lang.String>DEFAULT_MASKABLE_LOWERCASE_URL_PARAM_EXACT_NAMESURL parameter names matched WHOLE rather than as substrings, for credential parameters whose names are too short to be safe substrings.static java.util.Set<java.lang.String>DEFAULT_MASKABLE_LOWERCASE_URL_PARAM_SUBSTRINGSAs above, but tested against URL parameter names.static java.lang.StringMASK
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.StringlowercaseLettersDigitsOnly(java.lang.String s)static java.lang.StringmaskUrlCredentials(java.lang.String value)Masks credentials carried inside a URL-shaped value, which key-name tests cannot reach: a JDBC URL lives under a key called something likejdbcUrl, matching no sensitive substring, while its value may carry an account and password in either of two places.
-
-
-
Field Detail
-
DEFAULT_MASKABLE_LOWERCASE_SUBSTRINGS
public static final java.util.Set<java.lang.String> DEFAULT_MASKABLE_LOWERCASE_SUBSTRINGS
Names containing any of these, normalized, are taken to name a secret. Tested against configuration keys byPropertiesMasker.shouldMaskValue(java.lang.String). Unmodifiable, because a caller able to empty it could disable masking for the whole process.
-
DEFAULT_MASKABLE_LOWERCASE_URL_PARAM_SUBSTRINGS
public static final java.util.Set<java.lang.String> DEFAULT_MASKABLE_LOWERCASE_URL_PARAM_SUBSTRINGS
As above, but tested against URL parameter names. SeemaskUrlCredentials(java.lang.String).
-
DEFAULT_MASKABLE_LOWERCASE_URL_PARAM_EXACT_NAMES
public static final java.util.Set<java.lang.String> DEFAULT_MASKABLE_LOWERCASE_URL_PARAM_EXACT_NAMES
URL parameter names matched WHOLE rather than as substrings, for credential parameters whose names are too short to be safe substrings. SeemaskUrlCredentials(java.lang.String).
-
MASK
public static final java.lang.String MASK
- See Also:
- Constant Field Values
-
-
Method Detail
-
maskUrlCredentials
public static java.lang.String maskUrlCredentials(java.lang.String value)
Masks credentials carried inside a URL-shaped value, which key-name tests cannot reach: a JDBC URL lives under a key called something likejdbcUrl, matching no sensitive substring, while its value may carry an account and password in either of two places.- userinfo --
scheme://user:password@host:port/path - parameters --
scheme://host/db?user=u&password=p, and the;-separated form SQL Server-style drivers use, which carries its parameters directly after the authority with no?at all.
A value is URL-shaped if it begins with a scheme, and an authority is not required. Parameters do not need one, and most embedded databases put their credentials exactly there --
jdbc:h2:mem:db;USER=sa;PASSWORD=x,jdbc:derby:memory:db;user=app;password=x,jdbc:hsqldb:file:/db;user=SA;password=x. Testing for//asks after the authority and concludes from its absence that there is nothing to read, which is wrong for every one of those.Everything not itself a secret is retained: the scheme, host, port, path, every parameter name, the fragment, and the structure throughout. A masked userinfo still shows whether a password accompanied the account, because "was a password supplied here" is usually the question being asked of a dump -- and shows the account itself where one did:
mickey:******for a two-component userinfo,******for a one-component one.The single-component form is masked whole on purpose, although accounts are not otherwise masked. Position is what distinguishes an account from a secret in a userinfo, and with one component there is nothing to distinguish: a bare userinfo is sometimes a bearer token rather than a username --
https://TOKEN@github.com/org/repo.gitis how a personal access token is embedded in a git remote. Masking an account costs one diagnostic; disclosing a token cannot be undone.This is deliberately NOT built on
URI. A JDBC URL is opaque to it -- the scheme isjdbcand the remainder is the scheme-specific part -- so getUserInfo(), getHost() and getQuery() all return null for precisely the values that most need masking.- Returns:
- the value with any embedded credentials masked, or null if the value carries no scheme and so is not URL-shaped at all. A URL with nothing to mask comes back unchanged and equal to the input, which is how a caller tells "declined" from "nothing needed". Never throws: a malformed URL is treated as prose.
- userinfo --
-
lowercaseLettersDigitsOnly
public static java.lang.String lowercaseLettersDigitsOnly(java.lang.String s)
-
-