Class InstantiationNotPermittedException

  • All Implemented Interfaces:
    java.io.Serializable

    public final class InstantiationNotPermittedException
    extends java.lang.Exception
    Signals 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 any Class.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 ClassNotFoundException or 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 through ByNameInstantiationUtils.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 only getRefused(), while a diagnostic dump may want the whole getWhitelistInfo().

    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 Throwable is 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 driverClass into a SQLException handed to application code, with this exception as its cause. SQLException is 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 a NotSerializableException naming 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. readObject re-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 — treating getWhitelist() as authority to proceed, say — would turn a diagnostic into a security decision made from attacker-supplied bytes. Don't.

    See Also:
    ByNameInstantiationUtils.checkWarnThrowForInstantiateByNameGated(String,com.mchange.v2.cfg.PropertiesConfig,Set), ByNameInstantiationUtils.instantiateByNameGated(java.lang.String, com.mchange.v2.cfg.PropertiesConfig), Serialized Form
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getRefused()
      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.
      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.
      • Methods inherited from class java.lang.Throwable

        addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • 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, for Throwable.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 for getWhitelistInfo() 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, so null is 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, or null. 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 - if refused or whitelistInfo is null.
    • 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 WhitelistManager applies: 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 by getWhitelistInfo().

        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.