Skip to end of metadata
Go to start of metadata

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 by the C++ 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, the values of the enumeration are the values 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 M. 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 for out-of-range values, checking must be performed before the cast expression.

Noncompliant Code Example (Bounds Checking)

This noncompliant code example attempts to check whether a given value is within the range of acceptable enumeration values. However, it is doing so after casting 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 EnumType {
  First,
  Second,
  Third
};

void f(int intVar) {
  EnumType enumVar = static_cast<EnumType>(intVar);

  if (enumVar < First || enumVar > Third) {
    // Handle error
  }
}

Compliant Solution (Bounds Checking)

This compliant solution checks that the value can be represented by the enumeration type before performing the conversion to guarantee the 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 EnumType {
  First,
  Second,
  Third
};

void f(int intVar) {
  if (intVar < First || intVar > Third) {
    // Handle error
  }
  EnumType enumVar = static_cast<EnumType>(intVar);
}


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 solution.

enum class EnumType {
  First,
  Second,
  Third
};

void f(int intVar) {
  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 value.

enum EnumType : int {
  First,
  Second,
  Third
};

void f(int intVar) {
  EnumType 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 the execution of arbitrary code by an attacker. However, 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.

Rule

Severity

Likelihood

Remediation Cost

Priority

Level

INT50-CPP

Medium

Unlikely

Medium

P4

L3

Automated Detection

Tool

Version

Checker

Description

Axivion Bauhaus Suite

7.2.0

CertC++-INT50
CodeSonar
6.2p0

LANG.CAST.COERCE

LANG.CAST.VALUE

Coercion Alters Value

Cast Alters Value

Helix QAC

2021.2

C++3013
Parasoft C/C++test

2021.2

CERT_CPP-INT50-a

An expression with enum underlying type shall only have values corresponding to the enumerators of the enumeration

PRQA QA-C++

4.4

3013
PVS-Studio

7.16

V1016

Related Vulnerabilities

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

Bibliography

[Becker 2009]Section 7.2, "Enumeration Declarations"
[ISO/IEC 14882-2020]

Subclause 5.2.9, "Static Cast"
Subclause 7.2, "Enumeration Declarations"



9 Comments

  1. C++17 is going to make this somewhat more dangerous, btw. [expr.static.cast]p10 has changed to state that the behavior is undefined rather than the value is unspecified.

  2. In the first non-compliant example, the enumType, according to en.cppreference.com, the underlying type is "int" , hence both the intVal and the enumType are of the same type. Why is it that the does not have values corresponding to the enumerators of the enumeration?

    1. The underlying type of an enum is not necessarily int, as is explained in the introduction.

  3. I cannot find "introduction" from this page about enum:https://en.cppreference.com/w/cpp/language/enum

    Perhaps you are referring to this following description? 

    "Values of unscoped enumeration type are implicitly-convertible to integral types. If the underlying type is not fixed, the value is convertible to the first type from the following list able to hold their entire value range: intunsigned intlongunsigned longlong long, or unsigned long long. If the underlying type is fixed, the values can be converted to their promoted underlying type."  

    I still don't see that the underlying type of an enum is not necessarily int. Hint please.

    1. I meant the introduction to this rule.

    1. Can you clarify what you mean by giving a concrete example of a full C++ program that has surprising behavior because of this?

  4. FYI, the excerpt from the standard is pretty stale (as Aaron Ballman mentioned in 2017 it's now UB).

    Also, C++20 fixed what I suspect was a defect in the C++17 math.  If you do the math using the excerpt above (equivalently c++17 § 10.2 paragraph 8):

    enum Big{A=-128}; // |emax| = 128 => bmax = 255 => range is -256..255 (for c++17, but not c++20)
    enum Small{B=-128, C=-127}; // -128..127



    I don't think it was intended that Big's range would be bigger than Small's.

    It might be useful to update this page with the C++20 version, see § 9.7.1 paragraph 8.  The new text is easier to understand too.

    1. David:
      Sorry for the delay. I've updated the standard excerpts to C++20 as you suggest. I have no idea what the intention was wrt the range of Big vs Small...that is a question for WG21.