Programs must not allow mathematical operations to exceed the integer ranges provided by their primitive integer data types. According to The Java Language Specification (JLS), §4.2.2, "Integer Operations" [JLS 2015]:

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 insufficient memory to perform the conversion.

The integral types in Java, representation, and inclusive ranges are shown in the following table taken from the JLS, §4.2.1, "Integral Types and Values" [JLS 2015]:

Type

Representation

Inclusive Range

byte

8-bit signed two's-complement

−128 to 127

short

16-bit signed two's-complement

−32,768 to 32,767

int

32-bit signed two's-complement

−2,147,483,648 to 2,147,483,647

long

64-bit signed two's-complement

−9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

char

16-bit unsigned integers representing UTF-16 code units

\u0000 to \uffff (0 to 65,535)

The following table shows the integer overflow behavior of the integral operators.

Operator

Overflow


Operator

Overflow


Operator

Overflow


Operator

Overflow

+

Yes


-=

Yes


<<

No


<

No

-

Yes


*=

Yes


>>

No


>

No

*

Yes


/=

Yes


&

No


>=

No

/

Yes


%=

No


\

No


<=

No

%

No


<<=

No


^

No


==

No

++

Yes


>>=

No


~

No


!=

No

--

Yes


&=

No


!

No

=

No


|=

No


Unary +

No

+=

Yes


^=

No


Unary -

Yes

Because the ranges of Java types are not symmetric (the negation of each minimum value is one more than each maximum value), even operations such as unary negation can overflow if applied to a minimum value. Because the java.lang.math.abs() method returns the absolute value of any number, it can also overflow if given the minimum int or long as an argument.

Comparison of Compliant Techniques

Following are the three main techniques for detecting unintended integer overflow:

  • Precondition testing. Check the inputs to each arithmetic operator to ensure that overflow cannot occur. Throw an ArithmeticException when the operation would overflow if it were performed; otherwise, perform the operation.
  • Upcasting. Cast the inputs to the next larger primitive integer type and perform the arithmetic in the larger size. Check each intermediate result for overflow of the original smaller type and throw an ArithmeticException if the range check fails. Note that the range check must be performed after each arithmetic operation; larger expressions without per-operation bounds checking can overflow the larger type. Downcast the final result to the original smaller type before assigning to a variable of the original smaller type. This approach cannot be used for type long because long is already the largest primitive integer type.
  • BigInteger. Convert the inputs into objects of type BigInteger and perform all arithmetic using BigInteger methods. Type BigInteger is the standard arbitrary-precision integer type provided by the Java standard libraries. The arithmetic operations implemented as methods of this type cannot overflow; instead, they produce the numerically correct result. Consequently, compliant code performs only a single range check just before converting the final result to the original smaller type and throws an ArithmeticException if the final result is outside the range of the original smaller type.

The precondition testing technique requires different precondition tests for each arithmetic operation. This approach can be somewhat more difficult to implement and to audit than either of the other two approaches.

The upcast technique is the preferred approach when applicable. The checks it requires are simpler than those of the previous technique; it is substantially more efficient than using BigInteger. Unfortunately, it cannot be applied to operations involving type long, as there is no bigger type to upcast to.

The BigInteger technique is conceptually the simplest of the three techniques because arithmetic operations on BigInteger cannot overflow. However, it requires the use of method calls for each operation in place of primitive arithmetic operators, which can obscure the intended meaning of the code. Operations on objects of type BigInteger can also be significantly less efficient than operations on the original primitive integer type.

Precondition Testing

The following code example shows the necessary precondition checks required for each arithmetic operation on arguments of type int. The checks for the other integral types are analogous. These methods throw an exception when an integer overflow would otherwise occur; any other conforming error handling is also acceptable. Since ArithmeticException inherits from RuntimeException, we do not need to declare it in a throws clause.

static final int safeAdd(int left, int right) {
  if (right > 0 ? left > Integer.MAX_VALUE - right
                : left < Integer.MIN_VALUE - right) {
    throw new ArithmeticException("Integer overflow");
  }
  return left + right;
}

static final int safeSubtract(int left, int right) {
  if (right > 0 ? left < Integer.MIN_VALUE + right 
                : left > Integer.MAX_VALUE + right) {
    throw new ArithmeticException("Integer overflow");
  }
  return left - right;
}

static final int safeMultiply(int left, int right) {
  if (right > 0 ? left > Integer.MAX_VALUE/right
                  || left < Integer.MIN_VALUE/right 
                : (right < -1 ? left > Integer.MIN_VALUE/right 
                                || left < Integer.MAX_VALUE/right
                              : right == -1 
                                && left == Integer.MIN_VALUE) ) {
    throw new ArithmeticException("Integer overflow");
  }
  return left * right;
}

static final int safeDivide(int left, int right) {
  if ((left == Integer.MIN_VALUE) && (right == -1)) {
    throw new ArithmeticException("Integer overflow");
  }
  return left / right;
}

static final int safeNegate(int a) {
  if (a == Integer.MIN_VALUE) {
    throw new ArithmeticException("Integer overflow");
  }
  return -a;
}
static final int safeAbs(int a) {
  if (a == Integer.MIN_VALUE) {
    throw new ArithmeticException("Integer overflow");
  }
  return Math.abs(a);
}

These method calls are likely to be inlined by most just-in-time (JIT) systems.

These checks can be simplified when the original type is char. Because the range of type char includes only positive values, all comparisons with negative values may be omitted.

Noncompliant Code Example

Either operation in this noncompliant code example could result in an overflow. When overflow occurs, the result will be incorrect.

public static int multAccum(int oldAcc, int newVal, int scale) {
  // May result in overflow
  return oldAcc + (newVal * scale);
}

Compliant Solution (Precondition Testing)

This compliant solution uses the safeAdd() and safeMultiply() methods defined in the "Precondition Testing" section to perform secure integral operations or throw ArithmeticException on overflow:

public static int multAccum(int oldAcc, int newVal, int scale) {
  return safeAdd(oldAcc, safeMultiply(newVal, scale));
}

Compliant Solution (Java 8, Math.*Exact())

This compliant solution uses the addExact() and multiplyExact() methods defined in the Math class. These methods were added to Java as part of the Java 8 release, and they also either return a mathematically correct value or throw ArithmeticException. The Math class also provides SubtractExact() and negateExact() but does not provide any methods for safe division or absolute value.

public static int multAccum(int oldAcc, int newVal, int scale) {
  return Math.addExact(oldAcc, Math.multiplyExact(newVal, scale));
}

Compliant Solution (Upcasting)

This compliant solution shows the implementation of a method for checking whether a value of type long falls within the representable range of an int using the upcasting technique. The implementations of range checks for the smaller primitive integer types are similar.

public static long intRangeCheck(long value) {
  if ((value < Integer.MIN_VALUE) || (value > Integer.MAX_VALUE)) {
    throw new ArithmeticException("Integer overflow");
  }
  return value;
}

public static int multAccum(int oldAcc, int newVal, int scale) {
  final long res = intRangeCheck(
   ((long) oldAcc) + intRangeCheck((long) newVal * (long) scale)
  );
  return (int) res; // Safe downcast
}

Note that this approach cannot be applied to values of type long because long is the largest primitive integral type. Use the BigInteger technique instead when the original variables are of type long.

Compliant Solution (BigInteger)

This compliant solution uses the BigInteger technique to detect overflow:

private static final BigInteger bigMaxInt = 
  BigInteger.valueOf(Integer.MAX_VALUE);
private static final BigInteger bigMinInt =    
  BigInteger.valueOf(Integer.MIN_VALUE);

public static BigInteger intRangeCheck(BigInteger val) {
  if (val.compareTo(bigMaxInt) == 1 ||
      val.compareTo(bigMinInt) == -1) {
    throw new ArithmeticException("Integer overflow");
  }
  return val;
}

public static int multAccum(int oldAcc, int newVal, int scale) {
  BigInteger product =
    BigInteger.valueOf(newVal).multiply(BigInteger.valueOf(scale));
  BigInteger res = 
    intRangeCheck(BigInteger.valueOf(oldAcc).add(product));
  return res.intValue(); // Safe conversion
}

Noncompliant Code Example (AtomicInteger)

Operations on objects of type AtomicInteger suffer from the same overflow issues as other integer types. The solutions are generally similar to the solutions already presented; however, concurrency issues add additional complications. First, potential issues with time-of-check, time-of-use (TOCTOU) must be avoided (see VNA02-J. Ensure that compound operations on shared variables are atomic for more information). Second, use of an AtomicInteger creates happens-before relationships between the various threads that access it. Consequently, changes to the number of accesses or order of accesses can alter the execution of the overall program. In such cases, you must either choose to accept the altered execution or carefully craft your implementation to preserve the exact number of accesses and order of accesses to the AtomicInteger.

This noncompliant code example uses an AtomicInteger, which is part of the concurrency utilities. The concurrency utilities lack integer overflow checks.

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

  //...
  public final void nextItem() {
    itemsInInventory.getAndIncrement();
  }
}

Consequently, itemsInInventory can wrap around to Integer.MIN_VALUE when the nextItem() method is invoked when itemsInInventory == Integer.MAX_VALUE.

Compliant Solution (AtomicInteger)

This compliant solution uses the get() and compareAndSet() methods provided by AtomicInteger to guarantee successful manipulation of the shared value of itemsInInventory. This solution has the following characteristics:

  • The number and order of accesses to itemsInInventory remain unchanged from the noncompliant code example.
  • All operations on the value of itemsInInventory are performed on a temporary local copy of its value.
  • The overflow check in this example is performed in inline code rather than encapsulated in a method call. This is an acceptable alternative implementation. The choice of method call versus inline code should be made according to your organization's standards and needs.
class InventoryManager {
  private final AtomicInteger itemsInInventory =
      new AtomicInteger(100);

  public final void nextItem() {
    while (true) {
      int old = itemsInInventory.get();
      if (old == Integer.MAX_VALUE) {
        throw new ArithmeticException("Integer overflow");
      }
      int next = old + 1; // Increment
      if (itemsInInventory.compareAndSet(old, next)) {
        break;
      }
    } // End while
  } // End nextItem()
}

The two arguments to the compareAndSet() method are the expected value of the variable when the method is invoked and the intended new value. The variable's value is updated only when the current value and the expected value are equal [API 2006] (refer to VNA02-J. Ensure that compound operations on shared variables are atomic for more details).

Exceptions

NUM00-J-EX0: Depending on circumstances, integer overflow could be benign. For example, many algorithms for computing hash codes use modular arithmetic, intentionally allowing overflow to occur. Such benign uses must be carefully documented.

NUM00-J-EX1: Prevention of integer overflow is unnecessary for numeric fields that undergo bitwise operations and not arithmetic operations (see NUM01-J. Do not perform bitwise and arithmetic operations on the same data for more information).

Risk Assessment

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

Rule

Severity

Likelihood

Remediation Cost

Priority

Level

NUM00-J

Medium

Unlikely

Medium

P4

L3

Automated Detection

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

Tool
Version
Checker
Description
CodeSonar
8.1p0

JAVA.MATH.ABSRAND
JAVA.ARITH.OFLOW

Abs on random (Java)
Cast: int Computation to long (Java)

Coverity7.5

BAD_SHIFT
OVERFLOW_BEFORE_WIDEN

Implemented
Parasoft Jtest
2024.1
CERT.NUM00.ICO
CERT.NUM00.BSA
CERT.NUM00.CACO
Avoid calculations which result in overflow or NaN
Do not use an integer outside the range of [0, 31] as the amount of a shift
Avoid using compound assignment operators in cases which may cause overflow

Related Guidelines

SEI CERT C Coding Standard

INT32-C. Ensure that operations on signed integers do not result in overflow

ISO/IEC TR 24772:2010

Wrap-around Error [XYY]

MITRE CWE

CWE-682, Incorrect Calculation
CWE-190, Integer Overflow or Wraparound
CWE-191, Integer Underflow (Wrap or Wraparound)

Android Implementation Details

Mezzofanti for Android contained an integer overflow that prevented the use of a big SD card. Mezzofanti contained an expression:

(int) StatFs.getAvailableBlocks() * (int) StatFs.getBlockSize() 

to calculate the available memory in an SD card, which could result in a negative value when the available memory is larger than Integer.MAX_VALUE. Note that these methods are deprecated in API level 18 and replaced by getAvailableBlocksLong() and getBlockSizeLong().

Bibliography



29 Comments

  1. Efstathios, this is starting to look good. Nice quote from SUN at the top. Does SUN's document there state anything about silent wrapping on integers?

    The title is way too long...suggest taking the BigInteger out of the title, BigInteger is part of the solution, not the problem.

    Please also clean up the formatting and language.

    Saying that a vul is "almost impossible to exploit" is dangerous. Java vulnerabilities are quite exploitable; they just aren't as easy to exploit as C/C++ (for the reasons you state). For instance, if a Java program is computing my bank account, I don't want any damn integer overflows! (smile)

    This rule should refer to INT32-C when comparing Java and C. It should also refer to INT32-CPP when comparing Java and C+, since these two rules are also about signed integer overflow in C and C+.

    Provide non-compliant code samples for addition and subtraction...they will ease the descriptions for compliant solutions. Three compliant solutions for each form is a good plan: one compliant solution that prevents overflow (before doing the operation), one solution that does the operation on longs, and one solution that uses BigInteger.

    If Integer.MIN_VALUE % -1 == 0, then % is actually safe wrt overflow, as 0 is the mathematically correct answer, and Java is indeed safer than C/C++ here.

    Where are the shift operations?

    Provide a 'Risk Assessment' section, a 'References' section (listing the SUN document linked above), and an 'Other Languages' section.

  2. I would like to see more details in the risk assesment. Integer overflows are a real problem in C because they are a prominent cause of buffer overflows. That does apply to Java when it is being used either directly or indirectly to guard native code, but rarely otherwise.

    Perhaps some examples could be added. It has been speculated that Comair had an integer overflow bug in December 2004 that had a major business impact. I could quite believe that integer overflows could easily cause an infinite loop leading to availability/DoS issues.

    I have never seen an exploitable vulnerability in Java caused by an integer overflow. I therefore feel that the risk assesment is inflated.

    IMO, a better solution to checking is to put up with the fugly code and use BigInteger. Only in area determined to be performance criticial should difficult bounded integer arithmetic be used.

    As well as operations that happen to have language syntax available, library methods should be considered. Notable is Math.abs has behaviour similar to unary minus (Math.abs(Integer.MIN_VALUE) == Integer.MIN_VALUE).

    1. Hi Thomas, thank you for your comment.

      I have pointed out in several areas that overflows are very hard to exploit in Java than C\C++ and have explained the reason. I have not claimed that they lead to vulnerabilities easily. I will modify the Risk Assesment section, to reflect this difference as you suggest.

       Regardless of how easy it is to exploit the overflow though, there is the problem of overflow in Java. Not only in  rare cases but there is this potential in any case of arithmetic operation. And overflows lead at least, in wrong results or undefined behavior.

       The guideline for overflows in general are to detect than to prevent so an explicit range checking would be prudent approach.

      Regards,

      Efstathios 

  3. Should the sentence:

    "Because of the asymmetry between the representation of negative and positive integer values (there is an extra minimum negative value -128), there is no equivalent positive value (+128) for Integer.MIN_VALUE."

    Actually be something like:

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

    References to -128 and +128 appear to be an error.

  4. There is a lot of material in this one rule. Should we consider breaking this into smaller pieces?

  5. This rule says that:

    Addition (as with all arithmetic operations) in Java is performed on signed numbers only as unsigned numbers are unsupported.

    This bothers me, because I understand that char is an unsigned type in Java. Isn't it possible to add two chars or a char and a short?

    1. Yes, we do have a guideline on those lines. However, it is still quite unusual to use char in arithmetic expressions. Perhaps I can change that to:

      Typically, addition (as with all arithmetic operations) ....

      Storing a signed value in a char is forbidden by INT04-J. Do not attempt to store signed values in the char integral type.

  6. This rule currently states:

    Explicitly check the range of each arithmetic operation and throw an ArithmeticException on overflow. When performing operations on values of type int or smaller, 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.

    Ignoring char for now, it seems to me that addition, subtraction, multiplication, and division of byte, short, operands always succeeds without overflow because these operands are first widened to type int by numeric promotion. These operations on int type can be safely performed as long, and long types as BigInteger.

    The obvious mistake in the rule is that arithmetic on small types needs to be performed using variables of type long. This is unnecessarily inefficient.

    1. When performing operations on values of type int or smaller, the arithmetic can be performed using variables of type long.

      I think the words "or smaller" should be eliminated because this condition applies only to int. Addition of two or more int values may overflow. This can be prevented by using long.

      1. I wouldn't worry about making a bunch of small changes to this rule; I'm fixing to overhaul it once I understand the topic better.

  7. i'm not sure i believe this test is for overflow is correct

      if( b > 0 ? a > Integer.MAX_VALUE - b : a < Integer.MIN_VALUE - b ) {
        throw new ArithmeticException("Not in range");
      }
      return a + b;  // Value within range so addition can be performed
    

    if b > 0 and a < 0 it is going to test if a (a negative number) is greater than Integer.MAX_VALUE - b (it is not) which evaluates to false

    if b > 0 and a > 0 it is going to perform the same test which also looks fine.

    if b < 0  and a > 0  it is going to test if  a < Integer.MIN_VALUE - b.  Since a is positive, this test will always fail and an exception will be thrown even though this should always succeed.

    if b < 0 and a < 0 then it is going to test if  a < Integer.MIN_VALUE - b which should be fine.

    I think we need to toss this solution and look more closely at the remaining solutions (or just copy from the C wiki for signed integer overflow).

    1. I agree that the addition is guaranteed to succeed when b > 0 and a < 0 and the example (rightly) does not throw an exception for this case. I am not sure what the problem is...(the test fails and the condition evaluates to false; the exception is not thrown)

      EDIT (in reply to your edit): In your case 3, b < 0 and a > 0:

      a < Integer.MIN_VALUE - b

      Suppose a is 5 and b is -5.

      5 < -large number -(-5)
      5 < -large number + 5
      5 < -still a large number (5 is not less than this negative large number)

      So the condition expression evaluates to false so the exception is not thrown.

  8. Note that the above integer overflow (precondition) check for + is almost the same as SafeInt class for C++ by LeBlanc.

  9. Fred Long and I just added INT00-EX2, observing that checking EVERY integer operation for overflow may be more trouble than it is worth – except for the most critical programs (or portions thereof). A possible alternative is to range-check inputs to portions of the code to ensure that overflow is impossible therein. We note that this is quite difficult in practice!

    This particular problem makes me wish I was writing the Ada Secure Coding Standard, as this whole issue would be a non-problem. The whole overflow check thing really belongs in the hands of the compiler, rather than the programmer.

    1. Here is a common integer vul in C:

      size_t x = /* comes from the user */
      struct foo* array = malloc(x * sizeof( struct foo));

      Clearly if an attacker can set the value of x, they can set it to so large a value that malloc() is bound to fail. But there is a more insidious vul; an attacker can set x such that the multiplication overflows, yet produces a small value. For instance if x = SIZE_MAX / sizeof(struct foo) + 1, then the product will be 1 * sizeof( struct foo), which malloc will prob succeed. Then you have an array that the program thinks is much larger than it actually is, and heap overflow is imminent.

      Which is to say that you have to be VERY careful and precise when doing your taint analysis.

    2. For the C standard, we focus on the following applications of integers as requiring overflow checks:

      • as an array index
      • in any pointer arithmetic
      • as a length or size of an object
      • as the bound of an array (for example, a loop counter)
      • as an argument to a memory allocation function
      • in security-critical code

      I'm sure the list of criteria for Java is different.

      You can write the Ada secure coding standard when you finish this one. 8^)

  10. The following is not quite enough for me to understand the example:

    Failure to account for integer overflow has resulted in failures of real systems, for instance, when implementing the compareTo() method. The meaning of the return value of the compareTo() method is defined only in terms of its sign and whether it is zero; the magnitude of the return value is irrelevant. Consequently, an apparent — but incorrect — optimization would be to subtract the operands and return the result. For operands of opposite sign, this can result in integer overflow; thus violating the compareTo() contract Bloch 2008, item 12.

    Can you turn this into a NCE/CS pair?

  11. "Performing arithmetic operations that use operands of type char is strongly discouraged."

    How discouraged? Should there be a guideline that requires occurrences to be diagnosed?

    Why is this comment in the "Addition" section, when it appears to apply to all arithmetic operations?

  12. Why are there two Bounds Checking Compliant Solutions for addition? What is the difference between the two?

  13. Major reorganization to clearly describe and demonstrate the three different compliant techniques. The section on pre-conditioning the inputs now shows each of the necessary checks. The other two approaches both demonstrate and discuss the location of their necessary checks.

    Still need to find a home for the prior content that is interesting, but has nothing to do with integer overflow.

  14. made changes to resolve JPCERT comments.

  15. We should get the following lines to compile:

    private static final BigInteger bigMaxInt = BigInteger.valueOf(Int.MAX_VALUE);
    private static final BigInteger bigMinInt = BigInteger.valueOf(Int.MIN_VALUE);
    
  16. 1. In NUM00-EX1, "Prevention of integer overflow is not necessary for numeric type...", its not about type but rather some value(data) with numeric type which is of our interest?

    2. What is "heuristic warnings" and how they are helpful?

    1. 1. You're right. I s/type/field/ in that exception.

      2. Heuristic warnings are generated by heuristic methods, which, by definition, are not guaranteed to be perfect...they may generate false positives & false negatives. IOW the text is saying we don't know a way to perfectly identify overflow vulnerabilities, but we can employ several imperfect methods.

  17. Is this something that can use Math.multiplyExact and Math.addExact (java 8) instead of these safe operations?

    1. Yes. I've added a Compliant Solution that address the *Exact() methods in the Math class.

  18. Is there a specific reason why many methods in the examples explicitly declare ArithmeticException to be thrown? E.g.

    static final int safeAdd(int left, int right)
    
                     throws ArithmeticException { ...

    Since ArithmeticException is a runtime exception there is no need to declare it in the throws clause. Item 62 of Effective Java actually advises against including unchecked exceptions in the method declaration.

    I tend to remove ArithmeticException from the method declarations' throw clause. Any opinions on this?

    1. I have removed the throws ArithmeticException declaration from the method signatures.