Page History

Enumerations in C++ come in two forms: scoped enumerations in which the underlying type is fixed and unscoped enumerations in which the underlying type may or may not be 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 7:Standard, [dcl.enum], in paragraph 8 [ISO/IEC 14882-2020]:

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

The C++ Standard, [expr.static.

...

cast], paragraph 10, states the following:

A value of integral

...

or enumeration type

...

can be explicitly converted to a complete enumeration type. If the enumeration type has a fixed underlying type, the value is first converted to that type by integral conversion, if necessary, and then to the enumeration type. If the enumeration type does not have a fixed underlying type, the value is unchanged if

...

the original value is

...

within the range of the enumeration values (9.7.1), and otherwise, the behavior is undefined. 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 (7.3.10), 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 dynamically checking of the enumeration type. Otherwise, the value is unspecified.Therefore, 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 checking must be done performed before the conversioncast expression.

Noncompliant Code Example (Bounds

...

Checking)

This noncompliant code example is 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 EnumType are [0..3], so if a value outside of that range were passed to f(), the cast to EnumType would result in an unspecified value, and using that value within the if statement results in unspecified behavior.

enum enum_typeEnumType {
  First,
  E_ASecond,
  E_BThird
};

intvoid f(int_var = -1;
enum_type enum_varintVar) {
  EnumType enumVar = static_cast<enum_type>(int_varcast<EnumType>(intVar);

  if (enum_varenumVar < E_A First || enumVar > Third) {
    // handleHandle error
  }
}

Compliant Solution (Bounds

...

Checking)

This compliant solution checks for an out-of-bounds condition before that the value can be represented by the enumeration type before performing the conversion to guarantee there is no unspecified resultthe conversion does not result in an unspecified value. It does this by restricting the converted value to one for which there is a specific enumerator value.

enum enum_typeEnumType {
  First,
  E_ASecond,
  E_BThird
};

intvoid f(int_var = -1;

intVar) {
  if (int_varintVar < E_AFirst || int_varintVar > E_BThird) {
    // handleHandle error
  }

enum_type enum_var  EnumType enumVar = static_cast<enum_type>(int_varcast<EnumType>(intVar);
}

Noncompliant Code Example (Switch statement)

Compliant Solution (Scoped Enumeration)

This compliant solution uses a scoped enumeration, which has a fixed underlying int type by default, allowing any value from the parameter to be converted into a valid enumeration value. It does not restrict the converted value to one for which there is a specific enumerator value, but it could do so as shown in the previous compliant solutionThis noncompliant code may result in a truncation of the value of int_var when converted to type enum_type resulting in execution of either case E_A or E_B instead of the default case.

enum class enum_typeEnumType {
  E_AFirst,
  E_B
};

int int_var = 5Second,
  Third
};

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

Compliant Solution (Switch statement)

EnumType enumVar = static_cast<EnumType>(intVar);
}

Compliant Solution (Fixed Unscoped Enumeration)

Similar to the previous compliant solution, this compliant solution uses an unscoped enumeration but provides a fixed underlying int type allowing any value from the parameter to be converted to a valid enumeration valueThis compliant solution checks for an out-of-bounds condition before the conversion to guarantee that there is no unspecified values, and therefore, no truncation.

enum EnumType : int {
  First,
  Secondstd::cout << "case A" << std::endl;
enum enum_type {
  E_A,
  E_BThird
};

int int_var = 5;

if (int_var < E_A || int_var > E_Bvoid f(int intVar) {
  //EnumType 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 falue E_G produces an unspecified result.

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

for(enum_type enum_var = E_A; enum_var <= E_G; enum_var = static_cast<enum_var>(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
}

Risk Assessment

enumVar = static_cast<EnumType>(intVar);
}

Although similar to the previous compliant solution, this compliant solution differs from the noncompliant code example in the way the enumerator values are expressed in code and which implicit conversions are allowed. The previous compliant solution requires a nested name specifier to identify the enumerator (for example, EnumType::First) and will not implicitly convert the enumerator value to int. As with the noncompliant code example, this compliant solution does not allow a nested name specifier and will implicitly convert the enumerator value to int.

Risk Assessment

It is possible for unspecified values to result in a buffer overflow, leading to 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, etc.Automated detection should be possible for most cases, but might not be able to know if the value is guaranteed to be in-rangeHowever, because enumerators are rarely used for indexing into arrays or other forms of pointer arithmetic, it is more likely that this scenario will result in data integrity violations rather than arbitrary code execution.

References

Automated Detection

Related Vulnerabilities

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

Bibliography

...

Image Added Image Added Image Added Wiki Markup\[[Becker 09|AA. Bibliography#Becker 09]\] Section 7.2, "Enumeration declarations"