Class InstantiationNotPermittedException
- java.lang.Object
-
- java.lang.Throwable
-
- java.lang.Exception
-
- com.mchange.v2.reflect.InstantiationNotPermittedException
-
- All Implemented Interfaces:
java.io.Serializable
public final class InstantiationNotPermittedException extends java.lang.ExceptionSignals that the by-name use of a class was refused because its name is not in the effective whitelist, and whitelist enforcement is in effect.This is a policy refusal, not a failure to find or construct a class. Nothing was loaded.
ByNameInstantiationUtils.checkWarnThrowForInstantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig, java.util.Set<com.mchange.v2.reflect.ByNameInstantiationUtils.Warned>)decides on the name alone, ahead of anyClass.forName(..), precisely because 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.Code that catches this alongside
ClassNotFoundExceptionor the reflective construction exceptions should distinguish it from them. Those report a class that is missing or broken, which is a mistake to be corrected; this reports a name that was understood and declined. In particular, responding by retrying throughByNameInstantiationUtils.instantiateByNameUngated(java.lang.String)would reintroduce exactly the hazard the whitelist exists to close.Note that enforcement is off by default as of this writing, so an unwhitelisted name ordinarily provokes a warning and proceeds, rather than raising this. A handler for this exception is therefore handling a configuration an operator has explicitly opted into — and a default that is expected to change in a future release.
Why it carries the whitelist rather than describing it
A refusal is only actionable if its recipient can say what was refused, and against what. All of that could have gone into
Throwable.getMessage(), but a whitelist of any size buries the one sentence that tells an operator what to do, and the full list is wanted far less often than it would be produced. So the message states the refusal, and the particulars are carried as structure, for each handler to report as much of as it needs: a log line may want onlygetRefused(), while a diagnostic dump may want the wholegetWhitelistInfo().Serialization, and why it is worth the trouble
Java serialization has been a long-running source of security trouble, and this library reaches for it reluctantly. It is supported deliberately here, because a
Throwableis serializable whether or not its author thinks about it, and carrying fields on one that cannot be serialized does not produce a slightly degraded exception — it destroys the exception.Consider how this one travels. c3p0 wraps a refused
driverClassinto aSQLExceptionhanded to application code, with this exception as its cause.SQLExceptionis serializable, and exception cause chains cross process boundaries routinely: JMX, RMI, a remote invocation in an application server, some logging appenders. Serializing a chain serializes every link, so one non-serializable member fails the whole write with aNotSerializableExceptionnaming an implementation class the operator never heard of. The refusal they needed to read would be replaced by an unrelated I/O error, in exactly the remote, hard-to-reproduce setting where a clear message is worth most. That is the failure this support exists to prevent, and it was observed before the support was added, not imagined.The serialized form is written explicitly and carries its own version short, so that fields may be added later without silently misreading streams written by an earlier release; an unrecognized version is refused rather than guessed at.
readObjectre-runs the constructor's own validation, because the fields below are required and a stream would otherwise be a way to manufacture an instance the constructor refuses — the serialized form can represent a null that no caller can pass.Being well-formed is not being trustworthy. Deserialization bypasses constructors, so a deserialized instance is only ever a report of a refusal, never evidence of one: a forged or tampered stream can name any class and claim any whitelist. That is acceptable only because nothing consults this object to decide anything. The gate (
ByNameInstantiationUtils.checkWarnThrowForInstantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig, java.util.Set<com.mchange.v2.reflect.ByNameInstantiationUtils.Warned>)) resolves the whitelist itself, from live configuration, every time it is asked; this exception merely describes a decision already taken elsewhere. Code that ever begins to trust what it reads from one of these — treatinggetWhitelist()as authority to proceed, say — would turn a diagnostic into a security decision made from attacker-supplied bytes. Don't.
-
-
Constructor Summary
Constructors Constructor Description InstantiationNotPermittedException(java.lang.String message, java.lang.String refused, WhitelistInfo whitelistInfo)Equivalent toInstantiationNotPermittedException(String,String,WhitelistInfo,Throwable)with no cause, which is the ordinary case: the name was refused before anything was attempted, so there is nothing underlying to report.InstantiationNotPermittedException(java.lang.String message, java.lang.String refused, WhitelistInfo whitelistInfo, java.lang.Throwable cause)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.StringgetRefused()The fully-qualified class name whose by-name use was refused.java.util.Set<java.lang.String>getWhitelist()The whitelist against which the refused name was tested.WhitelistInfogetWhitelistInfo()The whole record of the whitelist resolution that produced this refusal: the effective whitelist, the configuration keys it was computed from, and which family of keys governed — the main whitelist and its subkeys, an override whitelist, a deprecated key, or none at all.
-
-
-
Constructor Detail
-
InstantiationNotPermittedException
public InstantiationNotPermittedException(java.lang.String message, java.lang.String refused, WhitelistInfo whitelistInfo, java.lang.Throwable cause)- Parameters:
message- a description of the refusal, forThrowable.getMessage(). Callers are encouraged to state what was refused and that enforcement was in effect, and to leave the whitelist itself out, so that a handler can reach forgetWhitelistInfo()when it wants that detail and is not made to log it when it does not.refused- the fully-qualified class name that was refused. Required: a refusal that cannot say what it refused is not actionable, sonullis rejected rather than carried.whitelistInfo- the whitelist resolution that refused it. Required, for the same reason and one more — callers compose messages directly from it, so it is guaranteed here rather than guarded at every use.cause- an underlying cause, ornull. A whitelist refusal ordinarily has none, since nothing was attempted; a cause here would describe a failure of the resolution itself rather than of any instantiation.- Throws:
java.lang.IllegalArgumentException- ifrefusedorwhitelistInfoisnull.
-
InstantiationNotPermittedException
public InstantiationNotPermittedException(java.lang.String message, java.lang.String refused, WhitelistInfo whitelistInfo)Equivalent toInstantiationNotPermittedException(String,String,WhitelistInfo,Throwable)with no cause, which is the ordinary case: the name was refused before anything was attempted, so there is nothing underlying to report.
-
-
Method Detail
-
getRefused
public java.lang.String getRefused()
The fully-qualified class name whose by-name use was refused.This is the name as it was supplied — the thing an operator must whitelist, or correct — and not a loaded
Class, since nothing was loaded.- Returns:
- the refused name, never
null.
-
getWhitelist
public java.util.Set<java.lang.String> getWhitelist()
The whitelist against which the refused name was tested.This is the effective whitelist at the moment of refusal, not the raw union of whatever the configuration keys name. It has already been narrowed by every rule
WhitelistManagerapplies: the intersection of System properties against the supplied configuration, the intersection of a deprecated key against the supported ones, the removal of a*that is not a whitelist's sole element, and any[]veto. So a name's absence here is the reason for the refusal even where some configuration key does list it, and the explanation of why lies in the keys reported bygetWhitelistInfo().The returned set is unmodifiable.
- Returns:
- the effective whitelist, never
null. It may be empty, which is a whitelist that denies everything rather than an absent one; a refusal always records what it was refused against, so there is no absent case to distinguish. - See Also:
WhitelistInfo.getWhitelist()
-
getWhitelistInfo
public WhitelistInfo getWhitelistInfo()
The whole record of the whitelist resolution that produced this refusal: the effective whitelist, the configuration keys it was computed from, and which family of keys governed — the main whitelist and its subkeys, an override whitelist, a deprecated key, or none at all.This is the accessor to prefer for diagnostics.
getWhitelist()answers only what the whitelist contained, which says nothing about where it came from; and where a whitelist is surprising, the contributing keys are usually the answer, since any subkey may add to it and either source may narrow it.WhitelistInfo.toString()renders all of that as a single line, and is embedded verbatim in messages elsewhere in this library and in c3p0, so prefer it to assembling your own rendering.- Returns:
- the resolution record, never
null. A handler may read it, and read through it, without guarding: c3p0 composes a SQLException message straight from this, and an NPE raised in the catch handler of a security gate would replace the refusal with an unrelated failure.
-
-