Page History

The C++ Standard ISO/IEC 14882-2003 Nontrivial C++ programs are generally divided into multiple translation units that are later linked together to form an executable. To support such a model, C++ restricts named object definitions to ensure that linking will behave deterministically by requiring a single definition for an object across all translation units. This model is called the One Definition Rule (ODR) (Section 3.2) states that

No translation unit shall contain more than one definition of any variable, function, class type, enumeration type or template.

Furthermore, paragraph 3 of said section states that, which is defined by the C++ Standard, [basic.def.odr], paragraph 4 [ISO/IEC 14882-2014], as:

Every program shall contain exactly one definition of every non-inline function or object variable that is used in odr-used in that program; no diagnostic required.

Although it is possible to check that the ODR is complied with (see [Quinlan 06]), as of October 2006 we are not aware of any compilers that fully enforce the rule or even issue a diagnostic. The EDG C++ Front End diagnoses a subset of violations of the ODR when compiling in export mode (a mode where the C++ export feature is enabled). As the paper by Quinlan et al. shows, failing to enforce the ODR enables a virtual function pointer attack, known as the VPTR exploit. This is where an object's virtual function table is corrupted so that calling a virtual function on the object results in malicious code being executed. See the paper by Quinlan et al. for more details.

Non-Compliant Code Example

This example is taken from the paper by Quinlan et al. referenced in the introduction to this rule.

The definition can appear explicitly in the program, it can be found in the standard or a user-defined library, or (when appropriate) it is implicitly defined. An inline function shall be defined in every translation unit in which it is odr-used.

The most common approach to multi-translation unit compilation involves declarations residing in a header file that is subsequently made available to a source file via #include. These declarations are often also definitions, such as class and function template definitions. This is allowed by an exception defined in paragraph 6, which reads in part:

There can be more than one definition of a class type, enumeration type, inline function with external linkage, class template, non-static function template, static data member of a class template, member function of a class template, or template specialization for which some template parameters are not specified in a program provided that each definition appears in a different translation unit, and provided the definitions satisfy the following requirements. Given such an entity named D defined in more than one translation unit, then...

If the definitions of D satisfy all these requirements, then the program shall behave as if there were a single definition of D. If the definitions of D do not satisfy these requirements, then the behavior is undefined.

The requirements specified by paragraph 6 essentially state that that two definitions must be identical (not simply equivalent). Consequently, a definition introduced in two separate translation units by an #include directive generally will not violate the ODR due to the definitions being identical in both translation units.

However, it is possible to violate the ODR of a definition introduced via #include using block language linkage specifications, vendor-specific language extensions, etc. A more likely scenario for ODR violations are accidental definitions of differing objects in different translation units.

Do not violate the One Definition Rule; violations result in undefined behavior.

Noncompliant Code Example

In this noncompliant code example, two different translation units define a class of the same name with differing definitions. While the two definitions are functionally equivalent (they both define a class named S with a single, public, nonstatic data member int a), they are not defined using the same sequence of tokens. This is a violation of the ODR and results in undefined behavior.Base abstract class (Base.h)

class Base {
public:// a.cpp
struct S {
  int  virtual ~Base () {}a;
};
 
// b.cpp
class S {
public:
    virtual void run () = 0;
int a;
};

Compliant Solution

The compliant solution depends on programmer intent. If the programmer intended for the same class definition to be visible in both translation units because of common usage, the solution is to use a header file to introduce the object into both translation units, as shown in this compliant solution:Innocuous module (Module.cpp)

# include "Base// S.h"

classstruct Derived: public Base {
public:S {
    Derived () {buf_[0] = 'a';}
    void run () {buf_[0] = 'z';}
    char buf_[1];
};

void runModule () {
    Derived a, b;
    Base *pa = &a, *pb = &b;
    pb->run ();  // Expect b.buf_[0] == 'z'
    pa->run ();  // Expect a.buf_[0] == 'z'
}
int a;
};
 
// a.cpp
#include "S.h"
 
// b.cpp
#include "S.h"

If the ODR violation was a result of accidental name collision, the solution is to ensure both class definitions are unique, as in this compliant solution:

// a.cpp
namespace {
struct S {
  int a;
};
}
 
// b.cpp
namespace {
class S {
public:
  int a;
};
}

Alternatively, the classes could be given distinct names in each translation unit to avoid violating the ODR.

Noncompliant Code Example

In this noncompliant code example, a class definition is introduced into two translation units using #include. However, one of the translation units uses a common, implementation-defined #pragma to specify structure field alignment requirements. Consequently, the two class definitions may have differing layouts in each translation unit, which is a violation of the ODR.Malicious module (Attacker.cpp)

# include "Base// s.h"

class Attacker: public Basestruct S {
public: void run () {char c;
  int a;
};
 
void     init_s(S &s);
 
// vtable is overwritten
        // do malicious things here
        // ...
    }
}

class Derived: public Base {  // Class violating ODR
public:
    void run s.cpp
#include "s.h"
 
void init_s(S &s); {
  s.c = 'a';
  s.a = 12;
}
 
// a.cpp
#pragma pack(push, 1)
#include "s.h"
#pragma pack(pop)
 
void f() {
  S s;
     buf_[0] = 'z';  // Looks normal, but ...
        Attacker x;  // Instantiate to get a vtable to inject
        *((unsigned *)(buf_ + 12)) = *((const unsigned *)(&x));
    }
    char buf_[16];  // Buffer used to overwrite vtable
};

Derived d;  // Instantiate to get malicious Derived

If the attacker module can be introduced into the system so that the linker chooses it in preference to the "proper" class defined in Module.cpp (which can usually be achieved by putting the attacker module before the innocuous module in the list of modules to be linked, or in the shared library path), then it is possible to corrupt the virtual function table. The attacker derived class contains a buffer that overlays the vtable and its run method injects the malicious code into the appropriate place in the vtable. (This is dependent on the architecture of the system running the code.)

Compliant Solution

...

init_s(s);
}

Implementation Details

It is possible for the above noncompliant code example to result in a.cpp allocating space for an object with a different size than expected by init_s() in s.cpp. When translating s.cpp, the layout of the structure may include padding bytes between the c and a data members. When translating a.cpp, the layout of the structure may remove those padding bytes as a result of the #pragma pack directive, and so the object passed to init_s() may be smaller than expected. As a result, when init_s() initializes the data members of s, it may result in a buffer overrun.

For more information on the behavior of #pragma pack, see the vendor documentation for your implementation, such as Microsoft Visual Studio or GCC.

Compliant Solution

In this compliant solution, the implementation-defined structure member alignment directive is removed, ensuring that all definitions of S do not violate the ODR:

// s.h
struct S {
  char c;
  int a;
};
 
void init_s(S &s);
 
// s.cpp
#include "s.h"
 
void init_s(S &s); {
  s.c = 'a';
  s.a = 12;
}
 
// a.cpp
#include "s.h"
 
void f() {
  S s;
  init_s(s);
}

struct S {
  TCHAR Buffer[1024];
};

Risk Assessment

Failing to obey the ODR allows the VPTR exploit, which could lead to an attacker being able to execute arbitrary code. However, note that the attacker must have access to the system running the code to introduce the malicious class.

Automated Detection

Related Vulnerabilities

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

Related Guidelines

Bibliography

...

...

...