Class ByNameInstantiationUtils
- java.lang.Object
-
- com.mchange.v2.reflect.ByNameInstantiationUtils
-
public final class ByNameInstantiationUtils extends java.lang.Object
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classByNameInstantiationUtils.WarnedA record that a warning aboutfqcn's absence from the whitelist has already been emitted, under the configurationpcfg.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringENFORCE_WHITELIST_KEY
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static voidcheckWarnThrowForInstantiateByNameGated(java.lang.String fqcn, PropertiesConfig pcfg)Equivalent tocheckWarnThrowForInstantiateByNameGated(String,PropertiesConfig,Set)with no record of prior warnings, so that a non-whitelisted name warns on every call.static voidcheckWarnThrowForInstantiateByNameGated(java.lang.String fqcn, PropertiesConfig pcfg, java.util.Set<ByNameInstantiationUtils.Warned> optionalAlreadyWarned)In some contexts, instantiation by name doesn't happen in a single step.static WhitelistInfocurrentWhitelistInfo(PropertiesConfig pcfg)static java.lang.StringgetWhitelistBaseKey()static java.lang.ObjectinstantiateByNameGated(java.lang.String fqcn, PropertiesConfig pcfg)static java.lang.ObjectinstantiateByNameUngated(java.lang.String fqcn)Instantiates fqcn without consulting the whitelist at all.static java.lang.ObjectinstantiateByNameUngated(java.lang.String fqcn, java.lang.Class<?> preloaded)AsinstantiateByNameUngated(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.static booleanisEnforcingWhitelist(PropertiesConfig pcfg)
-
-
-
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.ClassNotFoundExceptionjava.lang.NoSuchMethodExceptionjava.lang.InstantiationExceptionjava.lang.IllegalAccessExceptionjava.lang.IllegalArgumentExceptionjava.lang.reflect.InvocationTargetExceptionInstantiationNotPermittedException
-
checkWarnThrowForInstantiateByNameGated
public static void checkWarnThrowForInstantiateByNameGated(java.lang.String fqcn, PropertiesConfig pcfg, java.util.Set<ByNameInstantiationUtils.Warned> optionalAlreadyWarned) throws InstantiationNotPermittedExceptionIn 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 proposedpcfg- the configuration from which the whitelist and the enforcement flag are drawn, in addition to the sealed System properties snapshot. May benull, in which case only the snapshot is consulted.optionalAlreadyWarned- may benull. 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 — aDataSourcere-checking on every connection checkout, say — should pass one, or the warning becomes a flood. Passnullto 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
pcfgas well as onfqcn, so that a configuration change which might have changed the whitelist warns afresh. Be aware of what that means in practice:PropertiesConfigimplementations do not generally overrideequals(..), so suppression ordinarily lasts only for as long as the caller hands in the samePropertiesConfiginstance. 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- iffqcnis 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)
-
checkWarnThrowForInstantiateByNameGated
public static void checkWarnThrowForInstantiateByNameGated(java.lang.String fqcn, PropertiesConfig pcfg) throws InstantiationNotPermittedExceptionEquivalent tocheckWarnThrowForInstantiateByNameGated(String,PropertiesConfig,Set)with no record of prior warnings, so that a non-whitelisted name warns on every call. Appropriate for gates reached once per object, or once per configuration load. A gate reached once per operation — per connection checkout, per request — should prefer the three-argument form.
-
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.InvocationTargetExceptionInstantiates 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 asinstantiateByNameGated(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 anInstantiationNotPermittedExceptionconverts 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.ClassNotFoundExceptionjava.lang.NoSuchMethodExceptionjava.lang.InstantiationExceptionjava.lang.IllegalAccessExceptionjava.lang.IllegalArgumentExceptionjava.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.IllegalArgumentExceptionAsinstantiateByNameUngated(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.ClassNotFoundExceptionjava.lang.NoSuchMethodExceptionjava.lang.InstantiationExceptionjava.lang.IllegalAccessExceptionjava.lang.IllegalArgumentExceptionjava.lang.reflect.InvocationTargetException
-
currentWhitelistInfo
public static WhitelistInfo currentWhitelistInfo(PropertiesConfig pcfg)
-
isEnforcingWhitelist
public static boolean isEnforcingWhitelist(PropertiesConfig pcfg)
-
getWhitelistBaseKey
public static java.lang.String getWhitelistBaseKey()
-
-