Page History

Integer conversions, both implicit and explicit (using a cast), must be guaranteed not to result in lost or misinterpreted data. This rule is particularly true for integer values that originate from untrusted sources and are used in any of the following ways:

• as an array index
• in Integer operands of any pointer arithmetic
• as a length or size of an object
• as the bound of an array (for example, a loop counter)
• , including array indexing
• The assignment expression for the declaration of a variable length array
• The postfix expression preceding square brackets [] or the expression in square brackets [] of a subscripted designation of an element of an array object
• Function arguments of type size_t or rsize_t (for example, as an argument to a memory allocation function
• in security-critical code

The only integer type conversions that are guaranteed to be safe for all data values and all possible conforming implementations are conversions of an integral value to a wider type of the same signedness. C99 Section 6.3.1.3 says

• )

This rule also applies to arguments passed to the following library functions that are converted to unsigned char:

• memset()
• memset_s()
• fprintf() and related functions (For the length modifier c, if no l length modifier is present, the int argument is converted to an unsigned char, and the resulting character is written.)
• fputc()
• ungetc()
• memchr()

and to arguments to the following library functions that are converted to char:

• strchr()
• strrchr()
• All of the functions listed in <ctype.h>

The only integer type conversions that are guaranteed to be safe for all data values and all possible conforming implementations are conversions of an integral value to a wider type of the same signedness.

The C Standard, subclause 6.3.1.3 [ISO/IEC 9899:2024], says

When a value with integer type is converted to another integer type other than _Bool, if the value can be represented by the new type, it is unchanged.

Otherwise, if the new type is unsigned, the value is converted by repeatedly adding or subtracting one more than the maximum value that can be represented in the new type until the value is in the range of the new type.

Otherwise, the new type is signed and the value cannot be represented in it; either the result is implementation

When a value with integer type is converted to another integer type other than _Bool, if the value can be represented by the new type, it is unchanged.

Otherwise, if the new type is unsigned, the value is converted by repeatedly adding or subtracting one more than the maximum value that can be represented in the new type until the value is in the range of the new type.

Otherwise, the new type is signed and the value cannot be represented in it; either the result is implementation-defined or an implementation-defined signal is raised.

Typically, converting an integer to a smaller type results in truncation of the high-order bits.

Noncompliant Code Example (Unsigned to Signed)

Type range errors, including loss of data (truncation) and loss of sign (sign errors), can occur when converting from a value of an unsigned integer type to a value of a signed integer type. The following This noncompliant code example results in a truncation error on most implementations.:

#include <limits.h>
 
void func(void) {
  unsigned long int ulu_a = ULONG_MAX;
  signed char sc;
  sc = (signed char)ulu_a; /* castCast eliminates warning */
  /* ... */
}

Compliant Solution (Unsigned to Signed)

Validate ranges when converting from an unsigned type to a signed type. The following code, for example, can be used when converting from This compliant solution can be used to convert a value of unsigned long int type to a value of signed char .type:

#include <limits.h>
 
void func(void) {
  unsigned long int ulu_a = ULONG_MAX;
  signed char sc;
  if (ulu_a <= SCHAR_MAX) {
    sc = (signed char)ulu_a;  /* use cast to eliminateCast eliminates warning */
  }
 else {
    /* handleHandle error condition */
  }
}

Noncompliant Code Example (Signed to Unsigned)

Type range errors, including loss of data (truncation) and loss of sign (sign errors), can occur when converting when converting from a value of a signed type to a value of an unsigned type. The following This noncompliant code example results in a loss of signnegative number being misinterpreted as a large positive number.

#include <limits.h>

void func(signed int si) = INT_MIN;
unsigned{
  /* Cast eliminates warning */
  unsigned int ui = (unsigned int)si;

  /* cast eliminates warning... */
}

/* ... */

func(INT_MIN);

Compliant Solution (Signed to Unsigned)

Validate ranges when converting from a signed type to an unsigned type. The following code, for example, can be used when converting from signed int to unsigned int.This compliant solution converts a value of a signed int type to a value of an unsigned int type:

#include <limits.h>

void func(signed int si) = INT_MIN;
{
  unsigned int ui;
  if ( (si < 0) ||{
 (si > UINT_MAX) ) {
  /* handleHandle error condition */
  }
 else {
    ui = (unsigned int)si;  /* castCast eliminates warning */
  }
  /* ... */
}

NOTE: While unsigned types can usually represent all positive values of the corresponding signed type, this relationship is not guaranteed by the C99 standard.

Noncompliant Code Example (Signed, Loss of Precision)

A loss of data (truncation) can occur when converting from a signed type to a signed type with less precision. The following code can result in truncation.

signed long int sl = LONG_MAX;
signed char sc = (signed char)sl; /* cast eliminates warning */

Compliant Solution (Signed, Loss of Precision)

Validate ranges when converting from a signed type to a signed type with less precision. The following code can be used, for example, to convert from a signed long int to a signed char.

/* ... */

func(INT_MIN + 1);

Subclause 6.2.5, paragraph 11, of the C Standard [ISO/IEC 9899:2024] provides the necessary guarantees to ensure this solution works on a conforming implementation:

The range of nonnegative values of a signed integer type is a subrange of the corresponding unsigned integer type, and the representation of the same value in each type is the same.

Noncompliant Code Example (Signed, Loss of Precision)

A loss of data (truncation) can occur when converting from a value of a signed integer type to a value of a signed type with less precision. This noncompliant code example results in a truncation error on most implementations:

#include <limits.h>

void func(void) {
  signed long int s_a

signed long int sl = LONG_MAX;
  signed char sc;
if (= (sl < SCHAR_MIN) || (sl > SCHAR_MAX) ) {signed char)s_a; /* Cast eliminates warning */
  /* handle error condition... */
}
else {
  sc = (signed char)sl; /* use cast to eliminate warning */

}

Conversions from signed types with greater precision to signed types with lesser precision require both the upper and lower bounds to be checked.

Noncompliant Code Example (Unsigned, Loss of Precision)

A loss of data (truncation) can occur when converting from an unsigned type to an unsigned type with less precision. The following code results in a truncation error on most implementations.

unsigned long int ul = ULONG_MAX;
unsigned char uc = (unsigned char)ul;  /* cast eliminates warning */

Compliant Solution (Unsigned, Loss of Precision)

Validate ranges when converting from an unsigned type to an unsigned type with lesser precision. The following code can be used, for example, to convert from an unsigned long int to an unsigned char.

unsigned long int ul = ULONG_MAX;
unsigned char uc;
if (ul > UCHAR_MAX) ) {
  /* handle error condition */
}
else {
  uc = (unsigned char)ul; /* use cast to eliminate warning */
}

Conversions from unsigned types with greater precision to unsigned types with lesser precision require only the upper bounds to be checked.

Exceptions

INT31-EX1: C99 defines minimum ranges for standard integer types. For example, the minimum range for an object of type unsigned short int is 0 to 65,535, while the minimum range for int is --32,767 to +32,767. This means that it is not always possible to represent all possible values of an unsigned short int as an int-. However, on the IA-32 architecture, for example, the actual integer range is from ---2,147,483,648 to +2,147,483,647, meaning that it is quite possible to represent all the values of an unsigned short int as an int for this architecture. As a result, it is not necessary to provide a test for this conversion on IA-32. It is not possible to make assumptions about conversions without knowing the precision of the underlying types. If these tests are not provided, assumptions concerning precision must be clearly documented, as the resulting code cannot be safely ported to a system where these assumptions are invalid. A good way to document these assumptions is by using static assertions (see DCL03-C. Use a static assertion to test the value of a constant expression).

Risk Assessment

Integer truncation errors can lead to buffer overflows and the execution of arbitrary code by an attacker.

Automated Detection

Fortify SCA Version 5.0 with CERT C Rule Pack can detect violations of this rule.

Compass/ROSE can detect violations of this rule. However, false warnings may be raised if limits.h is included.

The Coverity Prevent NEGATIVE_RETURNS and REVERSE_NEGATIVE checkers both can find violations of this rule. The NEGATIVE_RETURNS checker can find array accesses, loop bounds, and other expressions that may contain dangerous implied integer conversions that would result in unexpected behavior. The REVERSE_NEGATIVE checker can find instances where a negativity check occurs after the negative value has been used for something else. Coverity Prevent cannot discover all violations of this rule, so further verification is necessary.

Klocwork can detect violations of this rule with the PRECISION.LOSS checker.  See Klocwork Cross Reference

Related Vulnerabilities

[CVE-2009-1376|http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-1376] results from a violation of this rule. In version 2.5.5 of Pidgin, an unsigned integer ({{offset}}) is set to the value of a 64-bit unsigned integer, which can lead to truncation \[[xorl 2009|http://xorl.wordpress.com/2009/05/28/cve-2009-1376-pidgin-msn-slp-integer-truncation/]\]. An attacker can execute arbitrary code by carefully choosing this value and causing a buffer overflow.

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

Other Languages

This rule appears in the C++ Secure Coding Standard as INT31-CPP. Ensure that integer conversions do not result in lost or misinterpreted data.

This rule appears in the Java Secure Coding Standard as INT30-J. Be careful while casting integers to narrower types.

References

\[[Dowd 06|AA. References#Dowd 06]\] Chapter 6, "C Language Issues" (Type Conversions, pp. 223-270)
\[[ISO/IEC 9899:1999|AA. References#ISO/IEC 9899-1999]\] 6.3, "Conversions"
\[[ISO/IEC PDTR 24772|AA. References#ISO/IEC PDTR 24772]\] "FLC Numeric Conversion Errors"
\[[MISRA 04|AA. References#MISRA 04]\] Rules 10.1, 10.3, 10.5, and 12.9
\[[MITRE 07|AA. References#MITRE 07]\] [CWE ID 192|http://cwe.mitre.org/data/definitions/192.html], "Integer Coercion Error," [CWE ID 197|http://cwe.mitre.org/data/definitions/197.html], "Numeric Truncation Error," and [CWE ID 681|http://cwe.mitre.org/data/definitions/681.html], "Incorrect Conversion between Numeric Types"
\[[Seacord 05a|AA. References#Seacord 05]\] Chapter 5, "Integers"
\[[Viega 05|AA. References#Viega 05]\] Section 5.2.9, "Truncation error," Section 5.2.10, "Sign extension error," Section 5.2.11, "Signed to unsigned conversion error," and Section 5.2.12, "Unsigned to signed conversion error"
\[[Warren 02|AA. References#Warren 02]\] Chapter 2, "Basics"
\[[xorl 2009|AA. References#xorl 2009]\] ["CVE-2009-1376: Pidgin MSN SLP Integer Truncation"|http://xorl.wordpress.com/2009/05/28/cve-2009-1376-pidgin-msn-slp-integer-truncation/]

Compliant Solution (Signed, Loss of Precision)

Validate ranges when converting from a signed type to a signed type with less precision. This compliant solution converts a value of a signed long int type to a value of a signed char type:

#include <limits.h>

void func(void) {
  signed long int s_a = LONG_MAX;
  signed char sc;
  if ((s_a < SCHAR_MIN) || (s_a > SCHAR_MAX)) {
    /* Handle error */
  } else {
    sc = (signed char)s_a; /* Use cast to eliminate warning */
  }
  /* ... */
}

Conversions from a value of a signed integer type to a value of a signed integer type with less precision requires that both the upper and lower bounds are checked.

Noncompliant Code Example (Unsigned, Loss of Precision)

A loss of data (truncation) can occur when converting from a value of an unsigned integer type to a value of an unsigned type with less precision. This noncompliant code example results in a truncation error on most implementations:

#include <limits.h>

void func(void) {
  unsigned long int u_a = ULONG_MAX;
  unsigned char uc = (unsigned char)u_a; /* Cast eliminates warning */
  /* ... */
}

Compliant Solution (Unsigned, Loss of Precision)

Validate ranges when converting a value of an unsigned integer type to a value of an unsigned integer type with less precision. This compliant solution converts a value of an unsigned long int type to a value of an unsigned char type:

#include <limits.h>

void func(void) {
  unsigned long int u_a = ULONG_MAX;
  unsigned char uc;
  if (u_a > UCHAR_MAX) {
    /* Handle error */
  } else {
    uc = (unsigned char)u_a; /* Cast eliminates warning */
  }
  /* ... */
}

Conversions from unsigned types with greater precision to unsigned types with less precision require only the upper bounds to be checked.

Noncompliant Code Example (time_t Return Value)

The time() function returns the value (time_t)(-1) to indicate that the calendar time is not available. The C Standard requires that the time_t type is only a real type capable of representing time. (The integer and real floating types are collectively called real types.) It is left to the implementor to decide the best real type to use to represent time. If time_t is implemented as an unsigned integer type with less precision than a signed int, the return value of time() will never compare equal to the integer literal -1.

#include <time.h>
 
void func(void) {
  time_t now = time(NULL);
  if (now != -1) {
    /* Continue processing */
  }
}

Compliant Solution (time_t Return Value)

To ensure the comparison is properly performed, the return value of time() should be compared against -1 cast to type time_t:

#include <time.h>
 
void func(void) {
  time_t now = time(NULL);
  if (now != (time_t)-1) {
    /* Continue processing */
  }
}

This solution is in accordance with INT18-C. Evaluate integer expressions in a larger size before comparing or assigning to that size. Note that (time_+t)-1 also complies with INT31-C-EX3.

Noncompliant Code Example (memset())

For historical reasons, certain C Standard functions accept an argument of type int and convert it to either unsigned char or plain char. This conversion can result in unexpected behavior if the value cannot be represented in the smaller type. The second argument to memset() is an example; it indicates what byte to store in the range of memory indicated by the first and third arguments.  If the second argument is outside the range of a signed char or plain char, then its higher order bits will typically be truncated. Consequently, this noncompliant solution unexpectedly sets all elements in the array to 0, rather than 4096:

#include <string.h>
#include <stddef.h>
 
int *init_memory(int *array, size_t n) {
  return memset(array, 4096, n); 
} 

Compliant Solution (memset())

In general, the memset() function should not be used to initialize an integer array unless it is to set or clear all the bits, as in this compliant solution:

#include <string.h>
#include <stddef.h>

int *init_memory(int *array, size_t n) {
  return memset(array, 0, n); 
} 

Exceptions

INT31-C-EX1: The C Standard defines minimum ranges for standard integer types. For example, the minimum range for an object of type unsigned short int is 0 to 65,535, whereas the minimum range for int is −32,767 to +32,767. Consequently, it is not always possible to represent all possible values of an unsigned short int as an int. However, on the IA-32 architecture, for example, the actual integer range is from −2,147,483,648 to +2,147,483,647, meaning that it is quite possible to represent all the values of an unsigned short int as an int for this architecture. As a result, it is not necessary to provide a test for this conversion on IA-32. It is not possible to make assumptions about conversions without knowing the precision of the underlying types. If these tests are not provided, assumptions concerning precision must be clearly documented, as the resulting code cannot be safely ported to a system where these assumptions are invalid. A good way to document these assumptions is to use static assertions. (See DCL03-C. Use a static assertion to test the value of a constant expression.)

INT31-C-EX2: Conversion from any integer type with a value between SCHAR_MIN and UCHAR_MAX to a character type is permitted provided the value represents a character and not an integer.

Conversions to unsigned character types are well defined by C to have modular behavior. A character's value is not misinterpreted by the loss of sign or conversion to a negative number. For example, the Euro symbol € is sometimes represented by bit pattern 0x80 which can have the numerical value 128 or −127 depending on the signedness of the type.

Conversions to signed character types are more problematic.

The C Standard, subclause 6.3.1.3, paragraph 3 [ISO/IEC 9899:2024], says, regarding conversions

Otherwise, the new type is signed and the value cannot be represented in it; either the result is implementation-defined or an implementation-defined signal is raised.

Furthermore, subclause 6.2.6.2, paragraph 2, says, regarding integer modifications

Each bit that is a value bit shall have the same value as the same bit in the object representation of the corresponding unsigned type. If the sign bit is zero, it shall not affect the resulting value. If the sign bit is one, it has value −(2N−1). There may or may not be any padding bits signed char shall not have any padding bits. 

Consequently, the standard allows for this code to trap:

int i = 128; /* 1000 0000 in binary */
assert(SCHAR_MAX == 127);
signed char c = i; /* can trap */

However, platforms where this code traps or produces an unexpected value are rare. According to The New C Standard: An Economic and Cultural Commentary by Derek Jones [Jones 2008],

Implementations with such trap representations are thought to have existed in the past. Your author was unable to locate any documents describing such processors.

INT31-C-EX3: The C Standard, subclause 7.29.2.5, paragraph 3 [ISO/IEC 9899:2024] says:

The time function returns the implementation’s best approximation to the current calendar time. The value (time_t)(-1) is returned if the calendar time is not available.

If time_t is an unsigned type, then the expression ((time_t) (-1)) is guaranteed to yield a large positive value.

Therefore, conversion of a negative compile-time constant to an unsigned value with the same or larger width is permitted by this rule. This exception does not apply to conversion of unsigned to signed values, nor does it apply if the resulting value would undergo truncation.

Risk Assessment

Integer truncation errors can lead to buffer overflows and the execution of arbitrary code by an attacker.

Automated Detection

* Coverity Prevent cannot discover all violations of this rule, so further verification is necessary.

Related Vulnerabilities

CVE-2009-1376 results from a violation of this rule. In version 2.5.5 of Pidgin, a size_t offset is set to the value of a 64-bit unsigned integer, which can lead to truncation [xorl 2009] on platforms where a size_t is implemented as a 32-bit unsigned integer. An attacker can execute arbitrary code by carefully choosing this value and causing a buffer overflow.

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

Related Guidelines

Key here (explains table format and definitions)

CERT-CWE Mapping Notes

Key here for mapping notes

CWE-195 and INT31-C

CWE-195 = Subset( CWE-192)

INT31-C = Union( CWE-195, list) where list =

• Unsigned-to-signed conversion error

• Truncation that does not change sign

CWE-197 and INT31-C

See CWE-197 and FLP34-C

CWE-194 and INT31-C

CWE-194 = Subset( CWE-192)

INT31-C = Union( CWE-194, list) where list =

• Integer conversion that truncates significant data, but without loss of sign

CWE-20 and INT31-C

See CWE-20 and ERR34-C

CWE-704 and INT31-C

CWE-704 = Union( INT31-C, list) where list =

• Improper type casts where either the source or target type is not an integral type

CWE-681 and INT31-C

CWE-681 = Union( INT31-C, FLP34-C)

Intersection( INT31-C, FLP34-C) = Ø

Bibliography

...

Image Added Image Added Image Removed      04. Integers (INT)      Image Modified