OBJ11-J. Defensively copy private mutable class members before returning their references

Returning references to internal mutable members of a class can compromise an application's security, both by breaking encapsulation and also by providing the opportunity to corrupt the internal state of the class (whether accidentally or maliciously). Performing a defensive copy before returning a reference to mutable internal state ensures that the caller can modify only the copy; he cannot modify the original internal state.

Pugh [[Pugh 2009]] cites a vulnerability discovered by the Findbugs static analysis tool in the early betas of jdk 1.7. The class sun.security.x509.InvalidityDateExtension returned a Date instance through a public accessor, without creating defensive copies.

Noncompliant Code Example (Mutable Member Containing Immutable Objects)

In this noncompliant code example, class ReturnRef contains a private Hashtable instance field. The hash table stores immutable data of sensitive nature (SSN numbers). A getter method getValues() gives the caller access to the hash table by returning a reference to it. An untrusted caller can use the getter method to gain access to the hashtable; consequently, hashtable entries can be maliciously added, removed or replaced.

class ReturnRef {
  // Internal state, may contain sensitive data
  private Hashtable<Integer,String> ht = new Hashtable<Integer,String>(); 
 
  private ReturnRef() {
    ht.put(1, "123-45-6666");
  }
 
  public Hashtable<Integer,String> getValues(){ 
    return ht;
  }
 
  public static void main(String[] args) {
    ReturnRef rr = new ReturnRef();
    Hashtable<Integer, String> ht1 = rr.getValues(); // Prints sensitive data 123-45-6666
    ht1.remove(1); // Untrusted caller can remove entries
    Hashtable<Integer, String> ht2 = rr.getValues(); // Now prints null, original entry is removed
  }	
}

Compliant Solution (Shallow Copying)

Make defensive copies of private internal mutable object state. For mutable fields that contain immutable data, a shallow copy is sufficient. Fields that refer to mutable data generally require a deep copy (see below).

This compliant solution creates and returns a shallow copy of the hash table containing immutable SSN numbers. As a result, any attempts to modify the original hash table are ineffective.

class ReturnRef {
// ...
  private Hashtable<Integer,String> getValues(){
    return (Hashtable<Integer, String>)ht.clone(); // shallow copy
  }

  public static void main(String[] args) {
    ReturnRef rr = new ReturnRef();
    Hashtable<Integer,String> ht1 = rr.getValues(); // prints non sensitive data
    ht1.remove(1); // untrusted caller can remove entries only from the copy
    Hashtable<Integer,String> ht2 = rr.getValues(); // prints non sensitive data     
  }
}

When a hash table contains references to mutable data such as a series of Date objects, each of those objects must also be copied by using a copy constructor or method. For further details, refer to guidelines FIO00-J. Defensively copy mutable inputs and mutable internal components and OBJ10-J. Provide mutable classes with copy functionality to allow passing instances to untrusted code safely. Note that the keys of a hash table need not be deep copied; shallow copying of the references suffices because a hash table's contract dictates that it cannot hold duplicate keys.

Noncompliant Code Example (Mutable Member)

This noncompliant code example shows a getDate() accessor method that returns the sole instance of the private Date object.

class MutableClass {
  private Date d;

  public MutableClass() {
    d = new Date();
  }

  public Date getDate() {
    return d;
  }
}

An untrusted caller can manipulate the instance because returning the reference exposes the internal mutable component beyond the trust boundaries of the class.

Compliant Solution (Shallow Copying Using clone() for Final Classes)

Defensive copies performed during execution of a constructor must avoid use of the clone() when the (non-system) class in question can be subclassed by untrusted code. This restriction prevents execution of a maliciously-crafted overriding of the clone() method.

Nevertheless, this compliant solution recommends returning a clone of the Date object from the getDate() accessor method. This is an acceptable solution because a malicious subclass cannot extending the internal mutable Date object; Date is a system class, the internal instance was locally constructed using the system class's constructor, so the operation is consequently safe.

protected Date getDate() {
  return (Date)d.clone();
}

This guideline also applies to arrays of primitive types. Because Java arrays are objects in their own right, when a caller receives a reference to an array, he can freely modify its contents. Creating a shallow copy of an arrays of primitive types provides a distinct array instance; although the caller can modify the returned array, he cannot affect the original array.

Classes that have public setter methods must follow the related advice found in guideline FIO00-J. Defensively copy mutable inputs and mutable internal components. Note that setter methods can (and usually should) perform input validation and sanitization before setting internal fields. On the other hand, returning references to internal objects may not require the caller to incorporate any of these defensive measures.

Noncompliant Code Example (Mutable Member Array)

In this noncompliant code example, the getDate() accessor method returns an array of Date objects.

class MutableClass {
  private Date[] date;

  public MutableClass() {
    for(int i = 0; i < 20; i++)
      date[i] = new Date();
    }

  public Date[] getDate() {
    return date; // or return date.clone()
  }
}

It fails to make a defensive copy of the array before returning it. Because the array contains references to Date objects that are themselves mutable, a shallow copy of the array (as discussed at the end of the previous compliant example) would be insufficient.

Compliant Solution (Deep Copying)

This compliant solution creates a deep copy of the date array and returns the copy rather than returning the internal date array.

class MutableClass {
  private Date[] date;

  public MutableClass() {
    for(int i = 0; i < 20; i++) {
      date[i] = new Date();
    }
  }

  public Date[] getDate() {
    Date[] dates = new Date[20];
    for(int i = 0; i < 20; i++) {
      dates[i] = (Date) date[i].clone();
    }
    return dates;
  }
}

Exceptions

OBJ11-EX1: According to Sun's Secure Coding Guidelines document [[SCG 2007]]

if a class merely serves as a container for mutable inputs or outputs (the class does not directly operate on them), it may not be necessary to create defensive copies. For example, arrays and the standard collection classes do not create copies of caller-provided values. If a copy is desired so updates to a value do not affect the corresponding value in the collection, the caller must create the copy before inserting it into the collection, or after receiving it from the collection.

OBJ11-EX2: If the performance of the copy method is within reasonable bounds and the class clearly documents its use, this guideline may be violated. (See guideline OBJ10-J. Provide mutable classes with copy functionality to allow passing instances to untrusted code safely.)

OBJ11-EX3: If the caller exposes an unmodifiable view of the object, it may not be required to defensively program the class to return copies of internal members. This decision should be made early in the design of the API. Note that if some other code wants to use this class in the future, it must also expose unmodifiable views. (See guideline SEC14-J. Provide sensitive mutable classes with unmodifiable wrappers.)

Risk Assessment

Returning references to internal object state (mutable or immutable) can render an application susceptible to information leaks and to corruption of its objects' states that consequently violates class invariants. Control flow can also be affected in some cases.

Automated Detection

Sound automated detection is infeasible; heuristic checks may be useful.

Related Vulnerabilities

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

Other Languages

This guideline appears in the C++ Secure Coding Standard as OOP35-CPP. Do not return references to private data.

Bibliography

[[API 2006]] method clone()
[[Bloch 2008]] Item 39: Make defensive copies when needed
[[Goetz 2006]] 3.2. Publication and Escape: Allowing Internal Mutable State to Escape
[[Gong 2003]] 9.4 Private Object State and Object Immutability
[[Haggar 2000]] Practical Java Praxis 64: Use clone for Immutable Objects When Passing or Receiving Object References to Mutable Objects
[[MITRE 2009]] CWE ID 375 "Passing Mutable Objects to an Untrusted Method"
[[SCG 2007]] Guideline 2-1 Create a copy of mutable inputs and outputs
[[Security 2006]]

OBJ10-J. Provide mutable classes with copy functionality to allow passing instances to untrusted code safely      Object Orientation (OBJ)      OBJ12-J. Use checked collections against external code