Class MaskUtils


  • public final class MaskUtils
    extends java.lang.Object
    The 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 on Properties, so a caller holding a single String can reach it. PropertiesMasker is this same policy applied across a whole Properties, 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 a Properties to 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 pass matching bypass or compass is 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. key and user are substrings of a wide variety of useful-to-debug configuration. user would mask user.home and user.dir, which are exactly what someone debugging a file: config source or a HOCON ${user.home} substitution needs to see. Hence the narrow compounds (apikey, accesskey). We don't consider user sensitive, and don't mask it here (although users are welcome to override public boolean shouldMaskValue(String key) in our sibling PropertiesMasker to 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.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String lowercaseLettersDigitsOnly​(java.lang.String s)  
      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 like jdbcUrl, matching no sensitive substring, while its value may carry an account and password in either of two places.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • 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 by PropertiesMasker.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. See maskUrlCredentials(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. See maskUrlCredentials(java.lang.String).
    • 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 like jdbcUrl, 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.git is 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 is jdbc and 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.
      • lowercaseLettersDigitsOnly

        public static java.lang.String lowercaseLettersDigitsOnly​(java.lang.String s)