Page History

...

Clients or callers need to know which exceptions the underlying code can throw. Consequently, developers should – and developers of security critical software must — sufficiently document all possible unchecked and undeclared checked exceptions that can be thrown by a method.

Noncompliant Code Example

This noncompliant code example is insecure both because it can throw undeclared checked exceptions and also because it uses the sun.misc.Unsafe class. All sun.* classes are unsupported and undocumented because their use can cause portability and backward compatibility issues.

...

import java.io.IOException;
import java.lang.reflect.Field;
import sun.misc.Unsafe;

public class UnsafeCode {
  public static void main( String[] args ) throws SecurityException, NoSuchFieldException,
  IllegalArgumentException, IllegalAccessException {
    Field f = Unsafe.class.getDeclaredField("theUnsafe");
    field.setAccessible(true);
    Unsafe u =  (Unsafe) field.get(null);
    u.throwException(new IOException("No need to declare this checked exception"));
  }
}

Noncompliant Code Example

Any checked exception thrown by the default constructor of Class.newInstance() is propagated to the caller, even though Class.newInstance declares that it throws only InstantiationException and IllegalAccessException. This noncompliant code example demonstrates one way to use Class.newInstance to throw arbitrary exceptions, whether checked or unchecked.

...

public static void main(String[] args) {
  try {	
    BadNewInstance.undeclaredThrow(new IOException("Any checked exception"));
  } catch(Exception e) { 
    if (e instanceof IOException) {
      System.out.println("IOException occurred");
    } else if (e instanceof RuntimeException) {
      throw (RuntimeException) e;
    } else {
      //some other unknown checked exception
    }
  } 
} 

Compliant Solution

Use method {{Constructor.newInstance()}} rather than {{Class.newInstance()}}. The {{java.lang.reflect.Constructor.newInstance()}} method wraps any exceptions thrown from within the constructor into a checked exception called {{InvocationTargetException}}.   Use of the builder interface recommended by Bloch \[[Bloch 2008|AA. Bibliography#Bloch 08]\] is an acceptable alternative. 

...

For further details on implementing the builder pattern, refer to guideline OBJ05-J. Prevent access to partially initialized objects. In the example described in that guideline, the Currency.Builder class must implement the Builder interface highlighted in this recommendation.

Noncompliant Code Example

An unchecked cast of a generic type with parameterized exception declaration can also result in unexpected checked exceptions. The compiler complains unless the warnings are suppressed.

interface Thr<EXC extends Exception> {
  void fn() throws EXC;
}

public class UndeclaredGen {
  static void undeclaredThrow() throws RuntimeException {
    @SuppressWarnings("unchecked")  // Suppresses warnings  
    Thr<RuntimeException> thr = (Thr<RuntimeException>)(Thr)
      new Thr<IOException>() {
        public void fn() throws IOException {
          throw new IOException();
	}
      };
      thr.fn();
    }

  public static void main(String[] args) {
    undeclaredThrow();
  }
}

Noncompliant Code Example

According to the Java API \[[API 2006|AA. Bibliography#API 06]\], class {{Thread}} documentation 

...

It is also possible to disassemble a class, remove any declared checked exceptions and reassemble the class so that checked exceptions are thrown at runtime when the class is used \[[Roubtsov 2003|AA. Bibliography#Roubtsov 03]\]. Compiling against a class that declares the checked exception and supplying at runtime a class that lacks the declaration also suffices. Similarly, a compiler other than {{javac}} might handle checked exceptions differently. Undeclared checked exceptions can also be produced through crafted use of the {{sun.corba.Bridge}} class. All these methods are strongly discouraged.  

Compliant Solution

Refrain from employing code (whether legitimate or hostile) that can throw undeclared checked exceptions. When this is unavoidable, explicitly document the behavior. Finally, never use deprecated methods such as Thread.stop() (as required by MET15-J. Do not use deprecated or obsolete classes or methods).

Risk Assessment

Failure to document undeclared checked exceptions can result in checked exceptions that the caller is unprepared to handle, consequently violating the safety property.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this guideline on the CERT website.

Bibliography

\[[Bloch 2008|AA. Bibliography#Bloch 08]\] Item 2: "Consider a builder when faced with many constructor parameters"
\[[Goetz 2004b|AA. Bibliography#Goetz 04b]\]
\[[JLS 2005|AA. Bibliography#JLS 05]\] Chapter 11: Exceptions
\[[MITRE 2009|AA. Bibliography#MITRE 09]\] [CWE ID 703|http://cwe.mitre.org/data/definitions/703.html] "Failure to Handle Exceptional Conditions", [CWE ID 248|http://cwe.mitre.org/data/definitions/248.html] "Uncaught Exception"
\[[Roubtsov 2003|AA. Bibliography#Roubtsov 03]\]
\[[Schwarz 2004|AA. Bibliography#Schwarz 04]\]
\[[Venners 2003|AA. Bibliography#Venners 03]\] "Scalability of Checked Exceptions"

...