Page History

Mutable classes are those which when instantiated, provide a reference such that the contents of the class can be altered anytime. It is important to provide means for creating copies of mutable class instances so as to allow safe passing in and returning of class objects when used within method argumentsallow code external to the class to alter their instance or class fields. Provide means for creating copies of mutable classes so that disposable instances of such classes can be passed to untrusted code. This functionality is useful when methods in other classes must create copies of the particular class instance (see OBJ06-J. Defensively copy mutable inputs and mutable internal components and OBJ05-J. Do not return references to private mutable class members for additional details).

Mutable classes must provide either a copy constructor or a public static factory method that returns a copy of an instance. Alternatively, final classes may advertise their copy functionality by overriding the clone() method of java.lang.Object. Use of the clone() method is secure only for final classes; nonfinal classes must not take this approach.

Trusted callers can be trusted to use the provided copy functionality to make defensive copies before passing object instances to untrusted code. Untrusted callers cannot be trusted to make such defensive copies. Consequently, providing copy functionality does not obviate the need for making defensive copies of inputs received from untrusted code or outputs returned to untrusted code.

Noncompliant Code Example

In this noncompliant code example, MutableClass uses a mutable Date object. If the caller changes the instance of the Date object (like incrementing the month), the class implementation no longer remains consistent with its old state. Both, the constructor as well as the getDate method are susceptible to abuse. This also defies attempts to implement thread safety. field date of type Date. Class Date is also a mutable class. The example is noncompliant because the MutableClass objects lack copy functionality.

public final class MutableClass {
  private Date date;

  public MutableClass(Date d) {
    this.date = d;
  }

  public void setDate(Date d) {
    this.date = d;
  }

  public Date getDate() {
    return date;
  }
}

When a trusted caller passes an instance of MutableClass to untrusted code, and the untrusted code modifies that instance (perhaps by incrementing the month or changing the timezone), the object's state can be made inconsistent with respect to its previous state. Similar problems can arise in the presence of multiple threads, even in the absence of untrusted code.

Compliant Solution (Copy Constructor)

This compliant solution uses a copy constructor that initializes a MutableClass instance when an argument of the same type (or subtype) is passed to it:

public final class MutableClass { // Copy constructor
  private final Date d;
	 date;

  public MutableClass(MutableClass mc)  {
    this.date = new Date(mc.date.getTime());
  }

  public MutableClass(Date d) {
    this.ddate = new Date(d.getTime());  // Make defensive copy
  }
	
  public Date getDate() {
    return d;	(Date) date.clone(); // Copy and return
  }
}

This code also violates OBJ37-J. Do not return references to private data

Compliant Solution

approach is useful when the instance fields are declared final. Callers request a copy by invoking the copy constructor with an existing MutableClass instance as its argument.

Compliant Solution (Public Static Factory Method)

This compliant solution exports a public static factory method getInstance() that creates and returns a copy of a given MutableClass object instance:

class MutableClass {
  private final Date date;

  private MutableClass(Date d) { // Noninstantiable and nonsubclassable
    this.date = new Date(d.getTime());  // Make defensive copy
  }

  public Date getDate() {
    return (Date) date.clone(); // Copy and return
  }

  public static MutableClass getInstance(MutableClass mc)  {
    return new MutableClass(mc.getDate());
  }
}

This approach is useful when the instance fields are declared final.

Compliant Solution (clone())

This compliant solution provides the needed copy functionality by declaring MutableClass to be final, implementing the Cloneable interface, and providing an Object.clone() method that performs a deep copy of the object:Always provide mechanisms to create copies of the instances of a mutable class. This compliant solution implements the Cloneable interface and overrides the clone method to create a deep copy of both the object and the mutable Date object. Since using clone() independently only produces a shallow copy and still leaves the class mutable, it is advised to also copy all the referenced mutable objects that are passed in or returned from any method.

public final class CloneClassMutableClass implements Cloneable {
  private Date ddate;
	
  public CloneClassMutableClass(Date d) {
    this.ddate = new Date(d.getTime());
  }

  public Date getDate() {
    return (Date) date.clone();
  }

   //copy-in public void setDate(Date d) {
    this.date = (Date) d.clone();
  }

  public Object clone() throws CloneNotSupportedException {
    final CloneClassMutableClass cloned = (CloneClassMutableClass) super.clone();
    cloned.ddate = (Date)d date.clone();  // Manually copy mutable Date object
    return cloned;
  }
}

Note that the clone() method must manually clone the Date object. This step is usually unnecessary when the object contains only primitive fields or fields that refer to immutable objects. However, when the fields contain data such as unique identifiers or object creation times, the clone() method must calculate and assign appropriate new values for such fields [Bloch 2008].

Mutable classes that define a clone() method must be declared final to ensure that untrusted code cannot declare a subclass that overrides the clone() method to create a spurious instance. The clone() method should copy all internal mutable state as necessary—in this compliant example, the Date object.

When untrusted code can call accessor methods passing mutable arguments, create defensive copies of the arguments before they are stored in any instance fields (see OBJ06-J. Defensively copy mutable inputs and mutable internal components for additional information). When retrieving internal mutable state, make a defensive copy of that state before returning it to untrusted code (see OBJ05-J. Do not return references to private mutable class members for additional information).

Defensive copies would be unnecessary if untrusted code always invoked an object's clone() method on mutable state received from mutable classes and operated only on the cloned copy. Unfortunately, untrusted code has little incentive to do so, and malicious code has every incentive to misbehave. This compliant solution provides a clone() method to trusted code and also guarantees that the state of the object cannot be compromised when the accessor methods are called directly from untrusted code.

Compliant Solution (clone() with Final Members)

When a mutable class's instance fields are declared final and lack accessible copy methods, provide a clone() method, as shown in this compliant solution:

public final class MutableClass implements Cloneable {
  private final Date date; // final field

  public  return cloned;MutableClass(Date d) {
    this.date = new Date(d.getTime());  // Copy in
  }
	
  public Date getDate() {
    return (Date)d date.clone(); //copy Copy and return
  }

  public Object clone() {
    Date d = (Date) date.clone();
    MutableClass cloned = new MutableClass(d);
    return cloned;
  }
}

Callers can use the clone() method to At times, a class is labeled final with no accessible copy methods. Callers can then obtain an instance of the class, such a mutable class. The clone() method must create a new instance with of the final member class and copy the original state and subsequently proceed to use it. Similarly, mutable objects obtained must also be copied when necessary.

\[[SCG 07|AA. Java References#SCG 07]\] provides some very useful tips: 

If a class is final and does not provide an accessible method for acquiring a copy of it, callers can resort to performing a manual copy. This involves retrieving state from an instance of that class, and then creating a new instance with the retrieved state. Mutable state retrieved during this process must likewise be copied if necessary. Performing such a manual copy can be fragile. If the class evolves to include additional state in the future, then manual copies may not include that state.

Risk Assessment

Creating a mutable class without a clone method may result in the data of the class becoming corrupted.

Automated Detection

TODO

Related Vulnerabilities

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

References

\[[API 06|AA. Java References#API 06]\] [method clone()|http://java.sun.com/javase/6/docs/api/java/lang/Object.html#clone()]
\[[Security 06|AA. Java References#Security 06]\]
\[[SCG 07|AA. Java References#SCG 07]\] Guideline 2-2 Support copy functionality for a mutable class
\[[Bloch 08|AA. Java References#Bloch 08]\] Item 39: Make defensive copies when needed
\[[MITRE 09|AA. Java References#MITRE 09]\] [CWE ID 374|http://cwe.mitre.org/data/definitions/374.html] "Mutable Objects Passed by Reference", [CWE ID 375|http://cwe.mitre.org/data/definitions/375.html] "Passing Mutable Objects to an Untrusted Method"

The new instance is necessary because there might not be an accessible copy method available in the member class. If the member class evolves in the future, it is critical to include the new state in the manual copy. Finally, the clone() method must create and return a new instance of the enclosing class (MutableClass) using the newly created member instance (d) [SCG 2009].

Mutable classes that define a clone() method must be declared final.

Compliant Solution (Unmodifiable Date Wrapper)

If cloning or copying a mutable object is infeasible or expensive, one alternative is to create an immutable view class. This class overrides mutable methods to throw an exception, protecting the mutable class.

class UnmodifiableDateView extends Date {
  private Date date;

  public UnmodifiableDateView(Date date) {
    this.date = date;
  }

  public void setTime(long date) {
    throw new UnsupportedOperationException();
  }

  // Override all other mutator methods to throw UnsupportedOperationException
}

public final class MutableClass {
  private Date date;

  public MutableClass(Date d) {
    this.date = d;
  }

  public void setDate(Date d) {
    this.date = (Date) d.clone();
  }

  public UnmodifiableDateView getDate() {
    return new UnmodifiableDateView(date);
  }
}

Exceptions

OBJ04-J-EX0: Sensitive classes should not be cloneable, per OBJ07-J. Sensitive classes must not let themselves be copied.

Risk Assessment

Creating a mutable class without providing copy functionality can result in the data of its instance becoming corrupted when the instance is passed to untrusted code.

Automated Detection

Sound automated detection is infeasible in the general case. Heuristic approaches could be useful.

Related Guidelines

Bibliography

...

Image Added Image Added Image AddedOBJ35-J. Use checked collections against external code      07. Object Orientation (OBJ)      OBJ37-J. Do not return references to private data