Class ByNameInstantiationUtils


  • public final class ByNameInstantiationUtils
    extends java.lang.Object
    • Field Detail

      • ENFORCE_WHITELIST_KEY

        public static final java.lang.String ENFORCE_WHITELIST_KEY
    • Method Detail

      • instantiateByNameGated

        public static java.lang.Object instantiateByNameGated​(java.lang.String fqcn,
                                                              PropertiesConfig pcfg)
                                                       throws java.lang.ClassNotFoundException,
                                                              java.lang.NoSuchMethodException,
                                                              java.lang.InstantiationException,
                                                              java.lang.IllegalAccessException,
                                                              java.lang.IllegalArgumentException,
                                                              java.lang.reflect.InvocationTargetException,
                                                              InstantiationNotPermittedException
        Throws:
        java.lang.ClassNotFoundException
        java.lang.NoSuchMethodException
        java.lang.InstantiationException
        java.lang.IllegalAccessException
        java.lang.IllegalArgumentException
        java.lang.reflect.InvocationTargetException
        InstantiationNotPermittedException
      • checkWarnThrowForInstantiateByNameGated

        public static void checkWarnThrowForInstantiateByNameGated​(java.lang.String fqcn,
                                                                   PropertiesConfig pcfg,
                                                                   java.util.Set<ByNameInstantiationUtils.Warned> optionalAlreadyWarned)
                                                            throws InstantiationNotPermittedException
        In some contexts, instantiation by name doesn't happen in a single step. This does all the whitelist-checking and warning we want to support, and throws if we would not permit the operation. You can safely instantiateByNameUngated(...) if this function succeeds.

        Note that the check is a check of the name, so it is also the right gate in front of a mere Class.forName(..). Loading a class runs its static initializers, so a load by an untrusted name is already an execution of untrusted code, whether or not an instance is ever constructed.

        Parameters:
        fqcn - the fully-qualified class name whose by-name use is proposed
        pcfg - the configuration from which the whitelist and the enforcement flag are drawn, in addition to the sealed System properties snapshot. May be null, in which case only the snapshot is consulted.
        optionalAlreadyWarned - may be null. When non-null, a caller-owned mutable set in which this method records the (fqcn, pcfg) pairs it has warned about, and which it consults to suppress a warning it has already emitted. Callers that reach this gate repeatedly for the same class — a DataSource re-checking on every connection checkout, say — should pass one, or the warning becomes a flood. Pass null to warn every time.

        The set is both read and written here, and is not internally synchronized, so a caller that shares it between threads must guard it. Passing a set owned by a lock already held at the call site is the simplest approach.

        Suppression is keyed on pcfg as well as on fqcn, so that a configuration change which might have changed the whitelist warns afresh. Be aware of what that means in practice: PropertiesConfig implementations do not generally override equals(..), so suppression ordinarily lasts only for as long as the caller hands in the same PropertiesConfig instance. A caller that builds a fresh config for each call will see no suppression at all, and will grow the set without bound. Callers wanting suppression should hold a stable reference — which is what a library-wide config accessor ordinarily returns.

        Only the warn-and-continue path consults this set. When whitelist enforcement is on, a non-whitelisted name throws every time, as it must.

        Throws:
        InstantiationNotPermittedException - if fqcn is not whitelisted and whitelist enforcement is in effect. Note that enforcement defaults to off for now, so an unwhitelisted name ordinarily warns rather than throwing. That default is expected to change in a future release.
        See Also:
        checkWarnThrowForInstantiateByNameGated(String,PropertiesConfig), instantiateByNameUngated(java.lang.String)
      • instantiateByNameUngated

        public static java.lang.Object instantiateByNameUngated​(java.lang.String fqcn)
                                                         throws java.lang.ClassNotFoundException,
                                                                java.lang.NoSuchMethodException,
                                                                java.lang.InstantiationException,
                                                                java.lang.IllegalAccessException,
                                                                java.lang.IllegalArgumentException,
                                                                java.lang.reflect.InvocationTargetException
        Instantiates fqcn without consulting the whitelist at all. This is the bypass, and the whole point of the whitelist is that most by-name instantiation should not use it.

        It is appropriate only where the name cannot have been influenced by anything outside the application's control. In practice that means one of two things:

        • the name is fixed in the code -- a literal or a compile-time constant -- so there is nothing for a whitelist to decide; or
        • the name has already been passed through checkWarnThrowForInstantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig, java.util.Set<com.mchange.v2.reflect.ByNameInstantiationUtils.Warned>), which performs the whole check and throws if the operation would not be permitted. Instantiating after that call returns normally is exactly as gated as instantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig) would have been.
        • the name was read from deployment configuration at the point of use -- a PropertiesConfig or System property lookup -- so the party who chose it is the same party who would have had to whitelist it. Gating there would only ask the configurer to authorize themselves.

          Note this turns on where the value in hand came from, not on whether a property of that name exists. A class name that is settable in configuration may also reach you as a property of a deserialized or dereferenced object, and at the point of instantiation the two are indistinguishable. If the value was carried on an object rather than read directly from configuration, it must be gated.

        A name that reached you from a deserialized object, a dereferenced JNDI Reference, or any other channel an attacker might influence belongs in instantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig) instead. Reaching for this method to quiet an InstantiationNotPermittedException converts a refusal into the vulnerability the refusal existed to prevent; the fix for that exception is to add the class to the whitelist.

        Throws:
        java.lang.ClassNotFoundException
        java.lang.NoSuchMethodException
        java.lang.InstantiationException
        java.lang.IllegalAccessException
        java.lang.IllegalArgumentException
        java.lang.reflect.InvocationTargetException
      • instantiateByNameUngated

        public static java.lang.Object instantiateByNameUngated​(java.lang.String fqcn,
                                                                java.lang.Class<?> preloaded)
                                                         throws java.lang.ClassNotFoundException,
                                                                java.lang.NoSuchMethodException,
                                                                java.lang.InstantiationException,
                                                                java.lang.IllegalAccessException,
                                                                java.lang.IllegalArgumentException,
                                                                java.lang.reflect.InvocationTargetException,
                                                                java.lang.IllegalArgumentException
        As instantiateByNameUngated(String), and subject to the same caution about when bypassing the whitelist is legitimate, but instantiating a Class already in hand rather than resolving fqcn afresh.

        Which Class object is used matters. A caller that loaded the class through some other ClassLoader -- a thread context ClassLoader, say, consulted because Class.forName had already failed -- holds a Class that a fresh Class.forName here could not find. This instantiates the Class it is given.

        The two arguments must agree: preloaded.getName() must equal fqcn, and an IllegalArgumentException is thrown if it does not. Passing the name separately is not redundant -- it is what lets the caller gate on the same name it is about to instantiate, via checkWarnThrowForInstantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig, java.util.Set<com.mchange.v2.reflect.ByNameInstantiationUtils.Warned>), before calling this.

        Throws:
        java.lang.ClassNotFoundException
        java.lang.NoSuchMethodException
        java.lang.InstantiationException
        java.lang.IllegalAccessException
        java.lang.IllegalArgumentException
        java.lang.reflect.InvocationTargetException
      • isEnforcingWhitelist

        public static boolean isEnforcingWhitelist​(PropertiesConfig pcfg)
      • getWhitelistBaseKey

        public static java.lang.String getWhitelistBaseKey()