Page History

...

Clients or callers are expected to know the exceptions that the underlying code can throw. For this reason, developers must sufficiently document all possible checked exceptions. Undeclared checked exceptions are a special class of exceptions that need diligent documentation. Security critical software must almost always make this contract explicit. Yet another difficulty in dealing with them is that sensitive exceptions cannot be sanitized before delivery, in the absence of a dedicated exception reporter. Ideally, undeclared checked exceptions should be avoided.

Noncompliant Code Example

This noncompliant code example uses the sun.misc.Unsafe class. All sun.* classes are undocumented because using them can cause portability and backward compatibility issues. This noncompliant code example is risky from this standpoint and by its capacity to throw undeclared checked exceptions.

...

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 even if it is not declared explicitly. On the contrary, the java.lang.reflect.Constructor.newInstance() method wraps any exceptions thrown from within the constructor into a checked exception called InvocationTargetException.

...

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

Prefer the method {{Constructor.newInstance()}} over {{Class.newInstance()}}. An alternative is to use the builder interface recommended by Bloch \[[Bloch 08|AA. Java References#Bloch 08]\]. 

...

For further details on implementing the builder pattern, refer to OBJ04-J. Do not allow partially initialized objects to be accessed. In the example described in that rule, 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 06|AA. Java References#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 this class is used \[[Roubtsov 03|AA. Java References#Roubtsov 03]\]. Simply, compiling against a class that declares the checked exception and supplying one at runtime that doesn't, also suffices. Similarly, a different compiler than {{javac}} might handle checked exceptions differently. Yet another way is to furtively use the {{sun.corba.Bridge}} class. All these methods are strongly discouraged.  

Compliant Solution

Refrain from employing code (legitimate or hostile) that is capable of throwing undeclared checked exceptions. If the source code can throw them, explicitly document the behavior. Finally, do not use deprecated methods such as Thread.stop().

Risk Assessment

Failure to document undeclared checked exceptions can result in checked exceptions that the caller is unprepared to handle. This violates the safety property.

Automated Detection

TODO

Related Vulnerabilities

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

References

\[[JLS 05|AA. Java References#JLS 05]\] Chapter 11: Exceptions
\[[Venners 03|AA. Java References#Venners 03]\] "Scalability of Checked Exceptions"
\[[Roubtsov 03|AA. Java References#Roubtsov 03]\]
\[[Schwarz 04|AA. Java References#Schwarz 04]\]
\[[Goetz 04b|AA. Java References#Goetz 04b]\]
\[[Bloch 08|AA. Java References#Bloch 08]\] Item 2: "Consider a builder when faced with many constructor parameters"
\[[MITRE 09|AA. Java References#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"

...