| Wiki Markup |
|---|
The singleton design pattern's intent is succinctly described by the seminal work of Gamma et al. \[[Gamma 95|AA. Java References#Gamma 95]\]: |
...
Ensure a class only has one instance, and provide a global point of access to it.
| Wiki Markup |
|---|
"Since there is only one Singleton instance, any instance fields of a Singleton will occur only once per class, just like {{static}} fields. Singletons often control access to resources such as database connections or sockets." \[[Fox 01|AA. Java References#Fox 01]\]. Other applications of singletons involve maintaining performance statistics, system monitoring and logging, implementing printer spoolers or as simple as ensuring that only one audio file plays at a time. |
...
Typically,
...
the
...
Singleton
...
pattern
...
uses
...
a
...
single
...
instance
...
of
...
a
...
class
...
that
...
encloses
...
a
...
private
...
static
...
instance
...
field.
...
The
...
instance
...
can
...
be
...
created
...
using
...
lazy
...
initialization
...
,
...
which
...
means
...
that
...
the
...
instance
...
is
...
not
...
created
...
when
...
the
...
class
...
loads
...
but
...
when
...
it
...
is
...
first
...
used.
...
Noncompliant
...
Code
...
Example
...
(nonprivate
...
constructor)
...
This
...
noncompliant
...
code
...
example
...
uses
...
a
...
nonprivate
...
constructor
...
for
...
instantiating
...
a
...
singleton.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} class MySingleton { private static MySingleton INSTANCE; protected MySingleton() { // private constructor prevents instantiation by untrusted callers INSTANCE = new MySingleton(); } public static synchronized MySingleton getInstance() { return INSTANCE; } } {code} |
A
...
malicious
...
subclass
...
may
...
extend
...
the
...
accessibility
...
of
...
the
...
constructor
...
from protected to public, allowing untrusted code to create multiple instances of the singleton. Also, the class field INSTANCE has not been declared as final.
Compliant Solution (private constructor)
This compliant solution reduces the accessibility of the constructor to private and initializes the field INSTANCE immediately, allowing it to be declared final.
| Code Block | ||
|---|---|---|
| ||
{{protected}} to {{public}}, allowing untrusted code to create multiple instances of the singleton. Also, the class field {{INSTANCE}} has not been declared as {{final}}. h2. Compliant Solution ({{private}} constructor) This compliant solution reduces the accessibility of the constructor to {{private}} and initializes the field {{INSTANCE}} immediately, allowing it to be declared {{final}}. {code:bgColor=#ccccff} class MySingleton { private static final MySingleton INSTANCE = new MySingleton(); private MySingleton() { // private constructor prevents instantiation by untrusted callers } public static synchronized MySingleton getInstance() { return INSTANCE; } } {code} h2. Noncompliant Code Example |
Noncompliant Code Example (visibility
...
across
...
threads)
...
When
...
the
...
getter
...
method
...
is
...
called
...
by
...
two
...
(or
...
more)
...
threads
...
simultaneously,
...
multiple
...
instances
...
of
...
the
...
Singleton
...
class
...
might
...
result
...
if
...
access
...
is
...
not
...
synchronized.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} class MySingleton { private static MySingleton INSTANCE; private MySingleton() { // private constructor prevents instantiation by untrusted callers } // Lazy initialization public static MySingleton getInstance() { // Not synchronized if (INSTANCE == null) { INSTANCE = new MySingleton(); } return INSTANCE; } } {code} h2. Noncompliant Code Example |
Noncompliant Code Example (inappropriate
...
synchronization)
...
Multiple
...
instances
...
can
...
be
...
created
...
even
...
if
...
the
...
singleton
...
construction
...
is
...
encapsulated
...
in
...
a
...
synchronized
...
block.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} public static MySingleton getInstance() { if (INSTANCE == null) { synchronized (MySingleton.class) { INSTANCE = new MySingleton(); } } return INSTANCE; } {code} |
This
...
is
...
because
...
two
...
or
...
more
...
threads
...
may
...
simultaneously
...
see
...
the
...
field
...
INSTANCE
...
as
...
null
...
in
...
the
...
if
...
condition
...
and
...
enter
...
the
...
synchronized
...
block
...
one
...
at
...
a
...
time.
...
Compliant
...
Solution
...
(1)
...
(
...
synchronized
...
method)
...
To
...
avoid
...
the
...
issue
...
of
...
multiple
...
threads
...
creating
...
more
...
than
...
one
...
instance
...
of
...
the
...
singleton,
...
make
...
getInstance()
...
a synchronized method.
| Code Block | ||
|---|---|---|
| ||
{{synchronized}} method. {code:bgColor=#ccccff} class MySingleton { private static MySingleton INSTANCE; private MySingleton() { // private constructor prevents instantiation by untrusted callers } // Lazy initialization public static synchronized MySingleton getInstance() { if (INSTANCE == null) { INSTANCE = new MySingleton(); } return INSTANCE; } } {code} h2. Compliant Solution |
Compliant Solution (2)
...
(double-checked
...
locking)
...
Another
...
solution
...
for
...
implementing
...
thread-safe
...
singletons
...
is
...
the
...
double-checked
...
locking
...
idiom.
| Code Block | ||
|---|---|---|
| ||
{code:bgColor=#ccccff} class MySingleton { private static volatile MySingleton INSTANCE; private MySingleton() { // private constructor prevents instantiation by untrusted callers } // Double-checked locking public static MySingleton getInstance() { if (INSTANCE == null) { synchronized (MySingleton.class) { if (INSTANCE == null) { INSTANCE = new MySingleton(); } } } return INSTANCE; } } {code} |
This
...
design
...
pattern
...
is
...
often
...
implemented
...
incorrectly.
...
Refer
...
to
...
...
...
...
...
...
...
...
...
...
...
...
for
...
more
...
details
...
on
...
the
...
double-checked
...
locking
...
idiom.
...
Noncompliant
...
Code
...
Example
...
(Serializable
...
singleton)
...
This
...
noncompliant
...
code
...
example
...
implements
...
the
...
java.io.Serializable
...
interface
...
which
...
allows
...
the
...
class
...
to
...
be
...
serializable.
...
Deserialization
...
of
...
the
...
class
...
implies
...
that
...
multiple
...
instances
...
of
...
the
...
singleton
...
can
...
be
...
created.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} class MySingleton implements Serializable { private static final long serialVersionUID = 6825273283542226860L; private static MySingleton INSTANCE; private MySingleton() { // private constructor prevents instantiation by untrusted callers } // Lazy initialization public static synchronized MySingleton getInstance() { if (INSTANCE == null) { INSTANCE = new MySingleton(); } return INSTANCE; } } {code} |
A
...
singleton's
...
constructor
...
cannot
...
install
...
any
...
checks
...
to
...
enforce
...
the
...
requirement
...
that
...
the
...
number
...
of
...
instances
...
be
...
limited
...
to
...
one
...
because
...
serialization
...
provides
...
a
...
mechanism
...
to
...
bypass
...
the
...
object's
...
constructor.
...
Compliant
...
Solution
...
(1)
...
(
...
readResolve
...
method)
...
It
...
is
...
recommended
...
that
...
stateful
...
singleton
...
classes
...
be
...
made
...
non-serializable.
...
As
...
a
...
precautionary
...
measure,
...
classes
...
that
...
are
...
serializable
...
must
...
never
...
save
...
a
...
reference
...
to
...
a
...
singleton
...
object
...
in
...
their
...
nontransient
...
or
...
nonstatic
...
instance
...
variables.
...
This
...
prevents
...
the
...
singleton
...
from
...
being
...
indirectly
...
serialized.
...
| Wiki Markup |
|---|
If making a singleton class serializable is indispensable, ensure that only one instance of the class exists by adding a {{readResolve()}} method which can be made to return the original instance. The phantom instance obtained after deserialization is left to the judgment of the garbage collector. \[[Bloch 08|AA. Java References#Bloch 08]\] |
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} private Object readResolve() { return INSTANCE; } {code} If the serializable singleton class has any other instance fields, they must be declared {{transient}} to be compliant (described later in the nontransient instance fields noncompliant code example). h2. Compliant Solution (2) ({{enum}} types) |
If the serializable singleton class has any other instance fields, they must be declared transient to be compliant (described later in the nontransient instance fields noncompliant code example).
Compliant Solution (2) (enum types)
| Wiki Markup |
|---|
Bloch \[[Bloch 08|AA. Java References#Bloch 08]\] suggests the use of an {{enum}} type as a replacement for traditional implementations. |
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} public enum MySingleton { INSTANCE; // Other methods } {code} |
Functionally,
...
this
...
approach
...
is
...
equivalent
...
to
...
commonplace
...
implementations
...
and
...
is
...
safer.
...
It
...
ensures
...
that
...
only
...
one
...
instance
...
of
...
the
...
object
...
exists
...
at
...
any
...
instant
...
and
...
also
...
provides
...
the
...
serialization
...
property
...
as
...
java.lang.Enum<E>
...
extends
...
java.io.Serializable.
Noncompliant Code Example (nontransient instance fields)
This serializable noncompliant code example uses a nontransient instance field str.
| Code Block | ||
|---|---|---|
| ||
}}. h2. Noncompliant Code Example (nontransient instance fields) This serializable noncompliant code example uses a nontransient instance field {{str}}. {code:bgColor=#FFcccc} class MySingleton implements Serializable { private static final long serialVersionUID = 2787342337386756967L; private static MySingleton INSTANCE; private String[] str = {"one", "two", "three"}; // nontransient instance field private MySingleton() { // private constructor prevents instantiation by untrusted callers } public void displayStr() { System.out.println(Arrays.toString(str)); } private Object readResolve() { return INSTANCE; } } {code} |
| Wiki Markup |
|---|
"If a singleton contains a nontransient object reference field, the contents of this field will be deserialized before the singletonâs {{readResolve}} method is run. This allows a carefully crafted stream to "steal" a reference to the originally deserialized singleton at the time the contents of the object reference field are deserialized." \[[Bloch 08|AA. Java References#Bloch 08]\]. |
...
Compliant
...
Solution
...
(1)
...
(transient
...
fields)
...
This
...
compliant
...
solution
...
declares
...
the
...
str
...
instance
...
field
...
as
...
transient
...
so
...
that
...
it
...
is
...
not
...
serialized.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} class MySingleton implements Serializable { // ... private transient String[] str = {"one", "two", "three"}; // nontransient field // ... } {code} h2. Compliant Solution |
Compliant Solution (2)
...
(
...
enum
...
types,
...
non-transient
...
fields)
...
This
...
compliant
...
solution
...
uses
...
the
...
enum
...
type
...
to
...
ensure
...
that
...
only
...
one
...
instance
...
of
...
the
...
singleton
...
exists
...
at
...
any
...
time.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} public enum MySingleton { INSTANCE; private String[] str = {"one", "two", "three"}; // nontransient field public void displayStr() { System.out.println(Arrays.toString(str)); } } {code} h2. Noncompliant Code Example |
Noncompliant Code Example (Cloneable
...
singleton)
...
It
...
is
...
also
...
possible
...
to
...
create
...
a
...
copy
...
of
...
the
...
singleton
...
by
...
cloning
...
it
...
using
...
the
...
object's
...
clone()
...
method
...
if
...
the
...
singleton
...
class
...
implements
...
java.lang.Cloneable
...
directly
...
or
...
through
...
inheritance.
...
This
...
noncompliant
...
code
...
example
...
shows
...
a
...
singleton
...
that
...
implements
...
the
...
java.lang.Cloneable
...
interface.
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} class MySingleton implements Cloneable { private static MySingleton INSTANCE; private MySingleton() { // private constructor prevents instantiation by untrusted callers } // Lazy initialization public static synchronized MySingleton getInstance() { if (INSTANCE == null) { INSTANCE = new MySingleton(); } return INSTANCE; } } {code} h2. Compliant Solution (override {{ |
Compliant Solution (override clone()
...
method)
...
Avoid
...
making
...
the
...
singleton
...
class
...
cloneable
...
by
...
not
...
implementing
...
the
...
Cloneable
...
interface
...
or
...
not
...
deriving
...
from
...
a
...
class
...
that
...
already
...
implements
...
it.
...
| Wiki Markup |
|---|
If the singleton class indirectly implements the {{Cloneable}} interface through inheritance, override the object's {{clone()}} method and throw a {{CloneNotSupportedException}} exception from within it \[[Daconta 03|AA. Java References#Daconta 03]\]. |
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} class MySingleton implements Cloneable { private static MySingleton INSTANCE; private MySingleton() { // private constructor prevents instantiation by untrusted callers } // Lazy initialization public static synchronized MySingleton getInstance() { if (INSTANCE == null) { INSTANCE = new MySingleton(); } return INSTANCE; } public Object clone() throws CloneNotSupportedException { throw new CloneNotSupportedException(); } } {code} See [ |
See MSC05-J.
...
...
...
...
...
for
...
more
...
details
...
about
...
restricting
...
the
...
clone()
...
method.
...
Noncompliant Code Example (garbage collection)
When the utility of a class is over, it is free to be garbage collected. This behavior can be troublesome when the program needs to maintain only one instance throughout its lifetime.
In this noncompliant code example, when ms1 goes out of scope, it can be garbage collected. Code that is outside the scope can create another instance of the singleton class though the requirement was to use only the original instance.
| Code Block | ||
|---|---|---|
| ||
{
MySingleton ms1 = MySingleton.getInstance();
// ...
}
MySingleton ms2 = MySingleton.getInstance();
|
Compliant Solution (prevent garbage collection)
| Wiki Markup |
|---|
This compliant solution takes into account the garbage collection issue described above. A class is not garbage collected until the {{ClassLoader}} object used to load it becomes eligible for garbage collection. An easier scheme to prevent the garbage collection is to ensure that there is a direct or indirect reference from a live thread to the singleton object that needs to be preserved. This compliant solution demonstrates this method ( |
...
based |
...
on \[[Patterns 02|AA. Java References#Patterns 02]\]). |
| Code Block | ||||
|---|---|---|---|---|
| =
| |||
} public class ObjectPreserver implements Runnable { privateMySingleton staticms1 ObjectPreserver lifeLine = new ObjectPreserver(= MySingleton.getInstance(); ObjectPreserver.preserveObject(ms1); // ... } MySingleton ms2 = (MySingleton) ObjectPreserver.getObject(); |
The ObjectPreserver class is shown below:
| Code Block |
|---|
public class ObjectPreserver implements Runnable { private static ObjectPreserver lifeLine = new ObjectPreserver(); // Neither this class, nor HashSet will be garbage collected. // // Neither this class, nor HashSet will be garbage collected. // References from HashSet to other objects will also exhibit this property private static HashSetHashMap<Integer,Object> protectedSetprotectedMap = new HashSetHashMap<Integer,Object>(); private ObjectPreserver() { new Thread(this).start(); // keeps the reference alive } public synchronized void run(){ try { wait(); } catch(InterruptedException e) { /* Forward to handler */ } } // Objects passed to this method will be preserved until // the unpreserveObject method is called public static void preserveObject(Object o) { protectedSetprotectedMap.addget(o0); } // Returns the same instance every time public static Object getObject() { return protectedMap.get(0); } // Unprotect the objects so that they can be garbage collected public static void unpreserveObject(Object o) { protectedSetprotectedMap.remove(o0); } } {code} To be fully compliant, it must be ensured that the class obeys the _Singleton_ pattern's design contract. It is unreasonable to use the class for anything else, for example, as a method to share global state. \[[Daconta 03|AA. Java References#Daconta 03]\] h2. Risk Assessment Using lazy initialization in a Singleton without synchronizing the {{getInstance()}} method may lead to creation of multiple instances and can as a result, violate the expected contract. || Rule || Severity || Likelihood || Remediation Cost || Priority || Level || | CON23- J | low | unlikely | medium | {color:green}{*}P2{*}{color} | {color:green}{*}L3{*}{color} | h3. Automated Detection TODO h3. Related Vulnerabilities Search for vulnerabilities resulting from the violation of this rule on the [CERT website|https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+CON32-J]. h2. References |
Risk Assessment
Using lazy initialization in a Singleton without synchronizing the getInstance() method may lead to creation of multiple instances and can as a result, violate the expected contract.
Rule | Severity | Likelihood | Remediation Cost | Priority | Level |
|---|---|---|---|---|---|
CON23- J | low | unlikely | medium | P2 | L3 |
Automated Detection
TODO
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
References
| Wiki Markup |
|---|
\[[JLS 05|AA. Java References#JLS 05]\] [Chapter 17, Threads and Locks|http://java.sun.com/docs/books/jls/third_edition/html/memory.html]
\[[Fox 01|AA. Java References#Fox 01]\] [When is a Singleton not a Singleton?|http://java.sun.com/developer/technicalArticles/Programming/singletons/]
\[[Daconta 03|AA. Java References#Daconta 03]\] Item 15: Avoiding Singleton Pitfalls;
\[[Darwin 04|AA. Java References#Darwin 04]\] 9.10 Enforcing the Singleton Pattern
\[[Gamma 95|AA. Java References#Gamma |
...
95]\] Singleton \[[ |
...
Patterns |
...
02|AA. Java |
...
References#Patterns |
...
02]\] |
...
Chapter |
...
5, Creational Patterns, Singleton \[[ |
...
Bloch |
...
08|AA. Java |
...
References#Bloch |
...
08]\] |
...
Item 3: "Enforce the singleton property with a private constructor or an enum type" and Item 77: "For instance control, prefer enum types to readResolve"
\[[MITRE 09|AA. Java References#MITRE 09]\] [CWE ID 543|http://cwe.mitre.org/data/definitions/543.html] "Use of Singleton Pattern in a Non-thread-safe Manner" |
...
CON22-J. Do not use incorrect forms of the double-checked locking idiom 11. Concurrency (CON) CON24-J. Use a unique channel to acquire locks on any file