...

While this statement is true, arithmetic operations in the Java platform require as much caution as in C and C++. Integer operations can result in overflow because Java does not provide any indication of overflow conditions and silently wraps. While integer overflows in vulnerable C and C++ programs may result in execution of arbitrary code, in Java, wrapped values typically result in incorrect computations and unanticipated outcomes.

Wiki MarkupAccording to the Java Language Specification \[[JLS 2005|AA. Bibliography#JLS 05]\], section Specification Section 4.2.2 "Integer Operations"

The built-in integer operators do not indicate overflow or underflow in any way. Integer operators can throw a NullPointerException if unboxing conversion of a null reference is required. Other than that, the only integer operators that can throw an exception are the integer divide operator / and the integer remainder operator %, which throw an ArithmeticException if the right-hand operand is zero, and the increment and decrement operators ++ and -- which can throw an OutOfMemoryError if boxing conversion is required and there is not sufficient memory available to perform the conversion.

The integral types in Java are byte, short, int, and long, whose values are 8-bit, 16-bit, 32-bit and 64-bit signed two’s-complement integers, respectively, and char, whose values are 16-bit unsigned integers representing UTF-16 code units.

Wiki MarkupAccording to the Java Language Specification \[[JLS 2005|AA. Bibliography#JLS 05]\], section Specification Section 4.2.1 "Integral Types and Values," , the values of the integral types are integers in the following ranges:

• For byte, from –128 to 127, inclusive
• For short, from –32768 to 32767, inclusive
• For int, from –2147483648 to 2147483647, inclusive
• For long, from –9223372036854775808 to 9223372036854775807, inclusive
• For char, from '\u0000' to '\uffff' inclusive, that is, from 0 to 65535

The table shown below enlists the operators that can lead to overflows:below shows the integer overflow behavior of the integral operators.

FailingFailure to account for integer overflow has resulted in failures inof real systems, for instance, when implementing the {{compareTo()}} method. The meaning of the return value of the {{compareTo()}} method doesis notdefined careonly aboutin the magnitudeterms of theits operandssign butand onlywhether about the signit is zero; the magnitude of the return value is irrelevant. Consequently, an apparent --- but incorrect --- optimization would isbe to simply subtract the operands and return the result. For nonpositive operandsoperands of opposite sign, this can result in integer overflow; andthus violation ofviolating the {{compareTo()}} contract \[[Bloch 2008, item 12|AA. Bibliography#Bloch 08]\].

Addition

Addition (as with all arithmetic operations) in Java is performed on signed numbers only as ; unsigned numbers are unsupported. One exception is the unsigned char type. Performing arithmetic operations that use operands of type char is strongly discouraged.

Noncompliant Code Example

In this noncompliant code example, the result of the addition can overflow.

public int do_operation(int a, int b){
  // May result in overflow 
  int temp = a + b;
  return temp;
}

If When the result of the addition is greater than the maximum value or less than the minimum value outside the range that can be represented as an int, then the variable temp will contain an erroneous result. This does not apply to shorter types Shorter types, such as byte and short, avoid this problem because the operands are promoted to an type int before the operation is carried out in cases where the value may not be representable. The compiler language disallows storing the result of such an operation operations in a variable variables of type types shorter than an type int.

Compliant Solution (Bounds Checking)

Explicitly check the range of the operands of each arithmetic operation and operations; throw an ArithmeticException on when overflow . When performing operations on values of type int, the arithmetic can be performed using variables of type long. For performing arithmetic operations on numbers of type long, the BigInteger Class must be used.

Because a variable of the long type is guaranteed to hold the result of an addition, subtraction or multiplication of values of type int, the result can be assigned to such a variable, and if the result is in the integer range, we can simply downcast it to a value of type int.

Compliant Solution (Use long and Downcast)

would occur.

Compliant Solution (Use a larger type and downcast)

For all integral types other than long, the next larger integral type can represent the result of any one integral operations. For example, operations on values of type int, can be performed using type long. Thus, we can perform an operation using the larger type and range-check before downcasting to the original type. Note, however, that this guarantee holds only for a single arithmetic operation; larger expressions without per-operation bounds checks may overflow the larger type.

Because type long is the largest primitive integral type, the only alternative is to perform arithmetic operations using the BigInteger class, range-check as above and then convert the result back to type long.

This compliant solution converts two variables of type int to type long, performs the addition of the long values, and range checks the result before converting back to type int using a range-checking method. The range-checking method determines whether its input can be represented by type int. If so, it returns the downcast result; otherwise it throws an ArithmeticExceptionThis compliant solution uses a variable of type long to store the result of the addition and proceeds to range check its value.
If the value cannot be represented in a variable of type int, it throws an ArithmeticException. Otherwise, it down casts the result to a value of type int.

public int adddo_operation(int a, int b) throws ArithmeticException {
   long temp = return intRangeCheck((long) a + (long) b);
}

// Either perform a ifsafe (tempdowncast > Integerto int, or throw ArithmeticException
public static int intRangeCheck(long val) throws ArithmeticException {
   if (val > Integer.MAX_VALUE || tempval < Integer.MIN_VALUE) {
     throw new ArithmeticException("Out of range");
   }
   return (int)tempval; // Value within range; candowncast performis the additionsafe
}

Compliant Solution (Bounds Checking)

This compliant solution range checks the operand values to ensure that the result does not overflow.

...

public int add(int a, int b) throws ArithmeticException {
  if (((a > 0) && (b > 0) && (a > (Integer.MAX_VALUE - b))) 
   || ((a < 0) && (b < 0) && (a < (Integer.MIN_VALUE - b)))) {
     throw new ArithmeticException("Not in range");
}
else {
  return a + b;  // Value within range so addition can be performed
}

Compliant Solution (Use BigInteger Class)

This compliant solution uses the BigInteger class as a wrapper to test for the overflow.

public booleanlong overflowdo_operation(long a, long b) throws ArithmeticException {
  BigInteger ba = new BigInteger(Stringreturn longRangeCheck(BigInteger.valueOf(a));
  BigInteger bb = new BigInteger(String.add(BigInteger.valueOf(b));
}

public long longRangeCheck(BigInteger br = ba.add(bb);val) throws ArithmeticException {
  returnif (brval.compareTo(BigInteger.valueOf(Long.MAX_VALUE)) == 1 ||
          brval.compareTo(BigInteger.valueOf(Long.MIN_VALUE)) == -1);
}

public long do_operation(long a, long b) throws ArithmeticException {
  if(overflow(a,b)) {
    throw new ArithmeticException("Not in range" {
    throw new ArithmeticException("Out of range for long");
  }
  // Within range; safely perform the addition
  return a + bval.longValue();
}

With use of the BigInteger class, integer overflows are eliminated. However, due to increased performance costs, it should be used only when other methods are not appropriate.

Subtraction

Care must be taken while performing the subtraction operation as well because overflows (or underflows) are possible.

Noncompliant Code Example

In this noncompliant code example, the subtraction operation may overflow negatively when a Subtraction overflows when the first operand is a negative integer and b the second operand is a large positive integer such that their sum difference is not representable as a value of type int. It can Subtraction also overflow overflows when a the first operand is positive and b the second operand is negative and their sum difference is not representable as a value of type int.

public int do_operation(int a, int b) {
  int temp = a - b;
  // Could result in overflow
  return temp;
}

Compliant Solution (Use Long)

This compliant solution suggests explicit range checking before performing the subtraction.

public int do_operation(int a,int b) {
  long temp = (long)a - (long)b;
  if(temp < Integer.MIN_VALUE || temp > Integer.MAX_VALUE) {
    throw new ArithmeticException("Not in range");
  }
  return (int) temp;
}

Compliant Solution (Bounds Checking)

This compliant solution uses range checking to ensure that the result will not overflow.

public int do_operation(int a, int b) throws ArithmeticException {
  if(b > 0 ? a < Integer.MIN_VALUE + b : a > Integer.MAX_VALUE + b ) {
    throw new ArithmeticException("Not in range");
  }
  return a - b;  // Value within range; can perform the addition
}

Compliant Solution (Use BigInteger Class)

The BigInteger class can be used as a overflow-test wrapper as shown in this compliant solution.

public boolean underflow(long a, long b) {
  BigInteger ba = new BigInteger(String.valueOf(a));
  BigInteger bb = new BigInteger(String.valueOf(b));
  BigInteger br = ba.subtract(bb);
  return (br.compareTo(BigInteger.valueOf(Long.MAX_VALUE)) == 1 ||
          br.compareTo(BigInteger.valueOf(Long.MIN_VALUE)) == -1);
}

public long do_operation(long a, long b) throws ArithmeticException {
  if(underflow(a,b)) {
    throw new ArithmeticException("Not in range");
  }
  // Within range; safely perform the subtraction
  return a - b;
}

Multiplication

This noncompliant code example can result in a signed integer overflow during the multiplication of the signed operands a and b. If this behavior is unanticipated, the resulting value may lead to undefined behavior.

Noncompliant Code Example

int a, b, result
//do stuff
result = a * b; // May result in overflow

Compliant Solution

Because the size of the type long (64 bits) is twice the size of the type int (32 bits), the multiplication should be performed using a variable of type long. If the product is in the range of the int type, it can be safely downcast to a value of type int.

int a, b, result;
long temp = (long) a * (long)b;
if(temp > Integer.MAX_VALUE || temp < Integer.MIN_VALUE) {
  throw new ArithmeticException("Not in range"); // Overflow
}
result = (int) temp; // Value within range, safe to downcast

Even though a and b are sign extended as a result of casting to long, their product is guaranteed to fit in a variable of type long.

Division

Although Java throws a java.lang.ArithmeticException for division by zero, the same issue as with C/C++ manifests, while dividing the Integer.MIN_VALUE by -1. It produces Integer.MIN_VALUE unexpectedly (as the result is -(Integer.MIN_VALUE) = Integer.MAX_VALUE + 1)).

Noncompliant Code Example

This noncompliant code example divides a and b without checking the range of the result.

int a;
int b;
int result;
result = a/b;

Compliant Solution

This compliant solution handles the special case of Integer.MIN_VALUE and -1 being used as the dividend and divisor, respectively.

if(a == Integer.MIN_VALUE && b == -1) {
  throw new ArithmeticException("Not in range"); // May be Integer.MIN_VALUE and -1
}
result = a/b; // Safe operation

Remainder Operator

The remainder operator in Java has the following behavior for corner cases:

• If the modulo of Integer.MIN_VALUE with -1 is taken the result is always 0.

• If the right-hand operand is zero, then the integer remainder operator % will throw an ArithmeticException.

• The sign of the remainder is always the same as that of the dividend. For example, -3 % -2 results in the value -1. This behavior can sometimes be deceptive.

Refer to guideline INT02-J. Do not assume a positive remainder when using the remainder operator for more details.

Unary Negation

If Integer.MIN_VALUE is negated, the same value Integer.MIN_VALUE is obtained. Range checking is important in this case as well.

Noncompliant Code Example

This noncompliant code example tries to negate the result without checking whether it is Integer.MIN_VALUE.

int temp = -result;

Compliant Solution

This compliant solution explicitly checks whether the input is Integer.MIN_VALUE and throws an exception if it is; otherwise, it negates the result.

if(result == Integer.MIN_VALUE) {
  throw new ArithmeticException("Not in range");
}
temp = -result;

Absolute Value

A related pitfall is the use of the Math.abs() method that takes a parameter of type int and returns its absolute value. Because of the asymmetry between the representation of negative and positive integer values (Integer.MAX_VALUE is 2147483647 and Integer.MIN_VALUE is -2147483648, which means there is one more negative integer than positive integers), there is no equivalent positive value (+2147483648) for Integer.MIN_VALUE.

Shifting

The shift operation in Java has the following properties:

• The right shift is an arithmetic shift.

• The types boolean, float and double cannot use the bit shifting operators.

• If the value to be shifted is of type int, only the five lowest-order bits of the right-hand operand are used as the shift distance. That is, the shift distance is the value of the right-hand operand masked by 31 (0x1F). This results in a value modulo 31, inclusive.

• Wiki Markup
  When the value to be shifted (left-operand) is of type {{long}}, only the last 6 bits of the right-hand operand are used to perform the shift. The shift distance is the value of the right-hand operand masked by 63 (0x3D) \[[JLS 2003|AA. Bibliography#JLS 03]\]. (That is to say, the shift value is always between 0 and 63. If the shift value is greater than 64, then the shift is {{value % 64}}.)

Refer to guideline INT05-J. Use shift operators correctly for further details about the behavior of the shift operators.

Noncompliant Code Example

This noncompliant code example attempts to shift the value {{i}} of type {{int}} until, after 32 iterations, the value becomes 0. Unfortunately, this loop never terminates because an attempt to shift a value of type {{int}} by 32 bits results in the original value rather than the value 0 \[[Bloch 2005|AA. Bibliography#Bloch 05]\]. 

int i = 0;
while ((-1 << i) != 0)
  i++;

Compliant Solution

This compliant solution initially sets the value val to -1 and repeatedly shifts the value by one place on each successive iteration.

for (int val = -1; val != 0; val <<= 1) { /* ... */ }

Noncompliant Code Example (Concurrent Code)

This noncompliant code example uses an AtomicInteger which is part of the concurrency utilities. The concurrency utilities do not enforce checks for integer overflow.

class InventoryManager {
  private final AtomicInteger itemsInInventory = new AtomicInteger(100);

  //...
  public final void returnItem() {
    itemsInInventory++;
  }
} 

Consequently, itemsInInventory may wrap around to Integer.MIN_VALUE after the increment operation.

Noncompliant Code Example (Concurrent Code—TOCTOU Condition in Check)

This noncompliant code example install a check for integer overflow; however, there is a time-of-check-time-of-use vulnerability between the check and the increment operation.

class InventoryManager {
  private volatile int itemsInInventory = 100;

  // ...

  public final void returnItem() {
    if (itemsInInventory == Integer.MAX_VALUE) {
      throw new IllegalStateException("Out of bounds");
    }
    itemsInInventory++;
  }
}

Compliant Solution (java.util.concurrent.atomic classes)

The java.util.concurrent utilities can be used to atomically manipulate a shared variable. This compliant solution defines intemsInInventory as a java.util.concurrent.atomic.AtomicInteger variable, allowing composite operations to be performed atomically.

class InventoryManager {
  private final AtomicInteger itemsInInventory = new AtomicInteger(100);

  public final void returnItem() {
    while (true) {
      int old = itemsInInventory.get();
      if (old == Integer.MAX_VALUE) {
        throw new IllegalStateException("Out of bounds");
      }
      int next = old + 1; // Increment
      if (itemsInInventory.compareAndSet(old, next)) {
        break;
      }
    } // end while
  } // end removeItem()
} 

The {{compareAndSet()}} method takes two arguments, the expected value of a variable when the method is invoked and the updated value. This compliant solution uses this method to atomically set the value of {{itemsInInventory}} to the updated value if and only if the current value equals the expected value \[[API 2006|AA. Bibliography#API 06]\]. The while loop ensures that the {{removeItem()}} method succeeds in decrementing the most recent value of {{itemsInInventory}} as long as the inventory count is greater than {{MIN_INVENTORY}}. Refer to guideline [VNA02-J. Ensure that compound operations on shared variables are atomic] for more details.

Exceptions

INT00-EX1: Depending on the functionality, integer overflow may be benign. For instance, the Object.hashcode() method may return all representable values of type int.

Risk Assessment

Note that the "Use a larger type and downcast" approach suffices to avoid overflow for subtraction.

Multiplication

Multiplication overflows whenever the sum of the number of bits required to represent its operands is larger than the number of bits in the result type. Once again, the "Use a larger type and downcast" approach suffices to avoid overflow.

Division

Although Java throws a java.lang.ArithmeticException for division by zero, it fails to do so when dividing Integer.MIN_VALUE by -1. Rather, Java produces Integer.MIN_VALUE in this case, because the result is -(Integer.MIN_VALUE) = Integer.MAX_VALUE + 1)) which overflows to Integer.MIN_VALUE; this may surprise many programmers.

Once again, the "Use a larger type and downcast" approach suffices to avoid overflow. In some cases, checking for the specific case above may be more efficient.

Remainder Operator

The Java remainder operator does not present overflow issues. However, it has the following behavior for corner cases:

• When the modulo of Integer.MIN_VALUE with -1 is taken, the result is always 0.

• When the right-hand operand is zero, the integer remainder operator % will throw an ArithmeticException.

• The sign of the remainder is always the same as that of the dividend. For example, -3 % -2 results in the value -1. This behavior may be unexpected.

Refer to guideline INT02-J. Do not assume a positive remainder when using the remainder operator for more details.

Unary Negation

The result of negating Integer.MIN_VALUE is Integer.MIN_VALUE, because -Integer.MIN_VALUE is logically equivalent to Integer.MAX_VALUE+1 which overflows to Integer.MIN_VALUE.

Once again, the "Use a larger type and downcast" approach suffices to avoid overflow. In some cases, checking for the specific case above may be more efficient.

Absolute Value

A related pitfall is the use of the Math.abs() method that takes a parameter of type int and returns its absolute value. Because of the asymmetry between the representation of negative and positive integer values (Integer.MAX_VALUE is 2147483647 and Integer.MIN_VALUE is -2147483648, which means there is one more negative integer than positive integers), there is no equivalent positive value (+2147483648) for Integer.MIN_VALUE. Thus, the Math.abs() returns Integer.MIN_VALUE when the value of its argument is Integer.MIN_VALUE; this may surprise many programmers.

Once again, the "Use a larger type and downcast" approach suffices to avoid overflow. In some cases, checking for the specific case above may be more efficient.

Shifting

The shift operation in Java has the following properties:

• The right shift is an arithmetic shift.

• The types boolean, float and double cannot use the bit shifting operators.

• If the value to be shifted is of type int, only the five lowest-order bits of the right-hand operand are used as the shift distance. That is, the shift distance is the value of the right-hand operand masked by 31 (0x1F). This results in a value modulo 31, inclusive.

• Wiki Markup
  When the value to be shifted (left-operand) is of type {{long}}, only the last 6 bits of the right-hand operand are used to perform the shift. The shift distance is the value of the right-hand operand masked by 63 (0x3D) \[[JLS 2003|AA. Bibliography#JLS 03]\]. (That is to say, the shift value is always between 0 and 63. If the shift value is greater than 64, then the shift is {{value % 64}}.)

Refer to guideline INT05-J. Use shift operators correctly for further details about the behavior of the shift operators.

Noncompliant Code Example

This noncompliant code example attempts to shift the value {{i}} of type {{int}} until, after 32 iterations, the value becomes 0. Unfortunately, this loop never terminates because an attempt to shift a value of type {{int}} by 32 bits results in the original value rather than the value 0 \[[Bloch 2005|AA. Bibliography#Bloch 05]\]. 

int i = 0;
while ((-1 << i) != 0)
  i++;

Compliant Solution

This compliant solution initially sets the value val to -1 and repeatedly shifts the value by one place on each successive iteration.

for (int val = -1; val != 0; val <<= 1) { /* ... */ }

Noncompliant Code Example (Concurrent Code)

This noncompliant code example uses an AtomicInteger which is part of the concurrency utilities. The concurrency utilities do not enforce checks for integer overflow.

class InventoryManager {
  private final AtomicInteger itemsInInventory = new AtomicInteger(100);

  //...
  public final void returnItem() {
    itemsInInventory++;
  }
} 

Consequently, itemsInInventory may wrap around to Integer.MIN_VALUE after the increment operation.

Noncompliant Code Example (Concurrent Code—TOCTOU Condition in Check)

This noncompliant code example installs a check for integer overflow; however, there is a time-of-check-time-of-use vulnerability between the check and the increment operation.

class InventoryManager {
  private volatile int itemsInInventory = 100;

  // ...

  public final void returnItem() {
    if (itemsInInventory == Integer.MAX_VALUE) {
      throw new IllegalStateException("Out of bounds");
    }
    itemsInInventory++;
  }
}

Compliant Solution (java.util.concurrent.atomic classes)

The java.util.concurrent utilities can be used to atomically manipulate a shared variable. This compliant solution defines itemsInInventory as a java.util.concurrent.atomic.AtomicInteger variable, allowing composite operations to be performed atomically.

class InventoryManager {
  private final AtomicInteger itemsInInventory = new AtomicInteger(100);

  public final void returnItem() {
    while (true) {
      int old = itemsInInventory.get();
      if (old == Integer.MAX_VALUE) {
        throw new IllegalStateException("Out of bounds");
      }
      int next = old + 1; // Increment
      if (itemsInInventory.compareAndSet(old, next)) {
        break;
      }
    } // end while
  } // end removeItem()
} 

The {{compareAndSet()}} method takes two arguments, the expected value of a variable when the method is invoked and the updated value. This compliant solution uses this method to atomically set the value of {{itemsInInventory}} to the updated value if and only if the current value equals the expected value \[[API 2006|AA. Bibliography#API 06]\]. The while loop ensures that the {{removeItem()}} method succeeds in decrementing the most recent value of {{itemsInInventory}} as long as the inventory count is greater than {{MIN_INVENTORY}}. Refer to guideline [VNA02-J. Ensure that compound operations on shared variables are atomic] for more details.

Exceptions

INT00-EX1: Depending on circumstances, integer overflow may be benign. For instance, the Object.hashcode() method may return all representable values of type int; further, many algorithms for computing hashcodes intentionally allow overflow to occur.

INT00-EX2: The added complexity and cost of programmer-written overflow checks may exceed their value for all but the most-critical code. In such cases, consider the alternative of treating integral values as though they are tainted data, using appropriate range checks as the notional "sanitizing" code. These range checks should ensure that incoming values cannot cause integer overflow. Note that sound determination of allowable ranges may require deep understanding of the details of the code protected by the range checks; this is non-trivial.

Risk Assessment

Failure to perform appropriate range checking can lead to integer overflows, which may cause Failure to perform explicit range checking can lead to integer overflows causing unexpected program control flow or unanticipated program behavior.

Automated Detection

TODOAutomated detection of integer operations that may potentially overflow is straightforward. Automatic determination of which potential overflows are true errors and which are intended by the programmer is infeasible. Heuristic warnings may be helpful.

Related Vulnerabilities

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

Other Languages

This guideline appears in the C Secure Coding Standard as INT32-C. Ensure that operations on signed integers do not result in overflow.

This guideline appears in the C++ Secure Coding Standard as INT32-CPP. Ensure that operations on signed integers do not result in overflow.

Bibliography

\[[SCG 2007|AA. Bibliography#SCG 07]\] Introduction
\[[JLSBloch 20032005|AA. Bibliography#JLSBibliography#Bloch 0305]\] 4.2.2 Integer Operations and 15.22 Bitwise and Logical Operators
Puzzle 27: Shifty i's\[[TutorialsSCG 20082007|AA. Bibliography#TutorialsBibliography#SCG 0807]\] Primitive Data TypesIntroduction
\[[SeacordJLS 20052003|AA. Bibliography#SeacordBibliography#JLS 0503]\] Chapter 5. Integers
\[[Bloch 2005|AA. Bibliography#Bloch 05]\] Puzzle 27: Shifty i's4.2.2 Integer Operations and 15.22 Bitwise and Logical Operators
\[[MITRE 2009|AA. Bibliography#MITRE 09]\] [CWE ID 682|http://cwe.mitre.org/data/definitions/682.html] "Incorrect Calculation", [CWE ID 190|http://cwe.mitre.org/data/definitions/190.html] "Integer Overflow or Wraparound", [CWE ID 191|http://cwe.mitre.org/data/definitions/191.html]  "Integer Underflow (Wrap or Wraparound)"
\[[Seacord 2005|AA. Bibliography#Seacord 05]\] Chapter 5. Integers
\[[Tutorials 2008|AA. Bibliography#Tutorials 08]\] Primitive Data Types

...

06. Integers (INT)      06. Integers (INT)      INT01-J. Range check before casting integers to narrower types