Page History

Enumerations in C++ come in two forms: scoped enumerations, where the underlying type is fixed, and unscoped enumerations where the underlying type is not fixed. The range of values that can be represented by either form of enumeration may include enumerator values not specified by the enumeration itself. The range of valid enumeration values for an enumeration type is defined as follows in by the C++ Working Draft, Section 7.2, paragraph 7Standard, [dcl.enum], paragraph 8 [ISO/IEC 14882-2014]:

For an enumeration whose underlying type is fixed, the values of the enumeration are the values of the underlying the underlying type. Otherwise, for an enumeration where emin e_min is the smallest enumerator and emax e_max is the largestthe largest, the values of the enumeration are the values in the range bmin b_min to bmax b_max, defined as follows: Let K be  be 1 for  for a two’s two’s complement representation and 0 for  for a one’s one’s complement or sign-magnitude representation. bmax  b_max is the smallest value greater than or equal to max(|emine_min| ? − K, |emaxe_max|) and equal to 2^M ? 2^M − 1, where where M is a non-negative integer. bmin b_min is zero if emin e_min is non-negative and ?−(bmax b_max + K) otherwise. The size of the of the smallest bit-field large enough to hold all the values of the enumeration type is max(M, 1) if bmin is zero b_min is zero and M + 1 otherwise. It is possible to define an enumeration that has values not defined by any of its enumeratorsits enumerators. If the enumerator-list is empty, the values of the enumeration are as if the enumeration had a single a single enumerator with value 0.

...

According to the C++ Standard, [expr.static.cast], paragraph 10,

A value of integral or enumeration type can be explicitly converted to an enumeration type

...

. The value is unchanged if the original value is within the range of the enumeration values (7.2). Otherwise, the resulting value is unspecified (and might not be in that range). A value of floating-point type can also be explicitly converted to an enumeration type. The resulting value is the same as converting the original value to the underlying type of the enumeration (4.9), and subsequently to the enumeration type.

To avoid operating on unspecified values, the arithmetic value being cast must be within the range of values the enumeration can represent. When checking unchanged if it is in the range of enumeration values of the enumeration type. Otherwise, the value is unspecified.To avoid unexpected behavior, the value being converted must be inside of the range of enumeration values. Furthermore, if it is necessary to check for out-of-range values dynamically, it must be done before the conversionperformed prior to the cast expression.

Noncompliant Code Example (Bounds Checking)

This noncompliant code example attempts to check for an out-of-bounds condition. Howeverwhether a given value is within the range of acceptable enumeration values. However, it is doing so after the conversion, so the result of the conversion is unspecified and the statement may have no effectcasting to the enumeration type, which may not be able to represent the given integer value. On a two's complement system, the valid range of values that can be represented by enum_type are: [0..3], so if a value outside of that range were passed to f(), the cast to enum_type would result in an unspecified value, and using that value within the if statement results in unspecified behavior.

enum enum_type {
  E_A,
  E_B,
  E_C
};

 
void f(int int_var) = -1;
{
  enum_type enum_var = static_cast<enum_type>(int_var);

  if (enum_var < E_A || enum_var > E_C) {
    // handleHandle error
  }
}

Compliant Solution (Bounds Checking)

This compliant solution checks for an out-of-bounds condition that the value is within the range of acceptable enumeration values before the conversion to guarantee there is no unspecified result. It further restricts the converted value to one for which there is a specific enumerator value.

enum enum_type {
  E_A,
  E_B,
  E_C
};

void f(int int_var) = -1;

{
  if (int_var < E_A || int_var > E_BC) {
    // handleHandle error
  }

enum_type enum_var = static_cast<enum_type>(int_var);

Noncompliant Code Example (Switch Statement)

...

enum_type

...

enum enum_type {
  E_A,
  E_B
};

int int_var = 5;

switch (static_cast<enum_type>(int_var)) {
  case E_A:
    // some action A
  case E_B:
    // some action B
  default:
    // handle error
;
}

Compliant Solution (

...

Scoped Enumeration)

This compliant solution checks for an out-of-bounds condition before the conversion to guarantee that there are no unspecified values and, consequently, no truncation.

std::cout << "case A" << std::endl;
enum enum_type {
  E_A,
  E_B
};

int int_var = 5;

if (int_var < E_A || int_var > E_B) {
  // handle error
}

switch (static_cast<enum_type>(int_var)) {
  case E_A:
    // some action A
  case E_B:
    // some action B
  default:
    // handle error
}

Noncompliant Code Example (For Loop)

This noncompliant code may result in an infinite loop instead of the expected behavior of looping through all enumeration values. The violation occurs at the end of the loop, when incrementing enum_var from the last valid value E_G produces an unspecified resultuses a scoped enumeration, which has a fixed underlying type of type int by default, allowing any value from the parameter to be converted into a valid enumeration value. It does not further restrict the converted value to one for which there is a specific enumerator value, but could do so by using the previous compliant solution.

enum class enum_type {
  E_A = 1,
  E_B,
  E_C,
  E_D,
  E_E,
  E_F,
  E_G
};

for(enum_type enumvoid f(int int_var) = E_A;{
  enum_var <= E_G;type enum_var = static_cast<enum_var>type>(enum_var+1)) {
  // some action
}

Implementation Details

GCC 4.4.3 compiles this into an infinite loop.

Compliant Solution (For Loop)

This compliant solution prevents any out-of-bounds arithmetic on the enumeration type.

enum enum_type {
  E_A = 1,
  E_B,
  E_C,
  E_D,
  E_E,
  E_F,
  E_G
};

for(int i = E_A; i <= E_G; i = i+1) {
  // some action
}
int_var);
}

Risk Assessment

Unexpected behavior can lead to a buffer overflow and the execution of arbitrary code by an attacker. This is most likely if the program in one case checks the value correctly and then fails to do so later. Such a situation could allow an attacker to avoid verification of a buffer's length, and so on.

...

Automated Detection

Related Vulnerabilities

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

Related Guidelines

Bibliography

INT18-CPP. Evaluate integer expressions in a larger size before comparing or assigning to that size      04. Integers (INT)      05. Floating Point Arithmetic (FLP)