README
1safe_iop - a safe integer operation library for C
2Chris Hutchinson <portmaster_AT_BSDforge.com>
3Will Drewry <redpig@dataspill.org>
4
5= Copyright and Licensing
6Copyright 2008-2021, Chris Hutchinson <portmaster_AT_BSDforge.com>
7Copyright 2007-2008, Will Drewry <redpig@dataspill.org>
8Some portions copyright 2008 Google Inc
9Released into the public domain with no warranty and no guarantees
10
11= Introduction
12
13Unsafe integer operations are a major cause of software defects even in
14modern day software. C is the underlying language for most high level
15languages (Ruby, Python, Java, etc) in addition to being in widespread
16general use. C is a preferred language for high performance programming
17and is often used for media file parsing and manipulation.
18
19Integer overflows occur when the calculated integer requires more storage
20from the computing platform than is available. If a number is too large,
21not all of its information can be stored. This has dangerous side effects.
22For a detailed and thorough discussion on integer overflows, please check
23out CERT's website on Secure Coding[1] and even Wikipedia[2].
24
25[1] https://www.securecoding.cert.org/confluence/display/seccode/CERT+C+Secure+Coding+Standard
26[2] http://en.wikipedia.org/wiki/Integer_overflow
27
28= Requirements
29
30safe_iop was designed explicitly with GNU GCC in mind and has only been
31tested with it. Your mileage may vary. Please let me know if it works for
32you with different compilers or on different platforms, and I'll update
33the Compatibility section below!
34
35In addition, your system must supply limits.h and assert.h for safe_iop
36to function as expected. It is possible to remove the dependence on both,
37but it breaks general portability.
38
39= Usage
40
41safe_iop comes in two pieces, safe_iop.h and safe_iop.c. safe_iop.h
42provides extensive macros for performing safe integer operations quickly
43and easily. safe_iop.c contains some testing code to make sure the package
44works on your system and a preliminary format string interface, safe_iopf.
45safe_iopf is not for the faint of heart as it is currently under development.
46The remainder of this document will focus on safe_iop.h.
47
48In order to use safe_iop, you will need to place safe_iop.h in your
49compiler's include path either by copying it somewhere like /usr/include,
50using an include flag -I/opt/safe_iop/include, or whatever other way you
51prefer. You will then need to include the header in the source file you
52will use the functions from.
53E.g., #include <safe_iop.h>
54
55safe_iop provides macros which check the validity of a given integer
56operation. It supports the following operations:
57- multiplication: safe_mul()
58- division: safe_div()
59- addition: safe_add()
60- subtraction: safe_sub()
61
62All of these macros take a result pointer, or NULL, as the first argument.
63The subsequent argument should be the two values to operate on. They then
64return true or false depending on if the operation is safe or not.
65(If NULL is given, a true or false value will be returned.)
66
67 uint32_t a = 100, b = 200, c = 0;
68 if (safe_mul(&c, a, b)) printf("c is %u\n", c);
69
70In addition, there are versions of these functions for multiple sequential
71operations:
72
73 uint32_t a = 100, b = 200, c = 300, d = 0;
74 if (safe_mul3(&d, a, b, c)) printf("d is %u\n", d);
75
76safe_<op>3-5() are all available.
77
78It is important to note that if the types of integers passed to safe_iop
79do not match, the operation will return false (0) with -DNDEBUG defined.
80If it is not defined, assert() is called and the program will abort if
81these mismatch is seen!
82
83For example,
84 uint32_t a = 100, c = 0;
85 uint8_t b = 20;
86 if (safe_add(&c, a, b)) /* I will return false! */
87
88Examples can be found in the examples/ directory.
89
90== safe_iopf
91
92If you'd like to use the format string function, do so at your own peril :-)
93If you like it and would like to send me a patch to make it awesome, I'd
94appreciate it! To use, just include the c file in your build, or build
95the shared library and link it to your app:
96 make so # or make dylib for OS X
97 ...
98 gcc yourapp.c ... -lsafe_iop
99
100More to come!
101
102= Compatibility
103
104Tests pass on the following platforms:
105
106- OS X Tiger, x86, GNU GCC 4.0.1
107- OS X Leopard, x86, GNU GCC 4.0.1
108- GNU/Linux, x86, GNU GCC 4.0.3
109- GNU/Linux, x86_64, GNU GCC 4.0.3
110- OpenBSD, VAX, GNU GCC 2.95.3
111- OpenBSD, sparc, GNU GCC 2.95.3
112- OpenBSD, alpha, GNU GCC 3.3.5
113- OpenBSD, sparc, GNU GCC 2.95.3
114- OpenBSD, macppc, GNU GCC 3.3.5
115- OpenBSD, arm, GNU GCC 3.3.5
116~ OpenBSD, sparc64, GNU GCC 3.3.5 [1]
117
118[1] For sparc64, there is an optimization bug which causes tests to fail if
119 -O<level> exceeds 1.
120
121= Credit where credit is do
122
123- The functions used in this library were largely drawn from the examples
124 provided in CERT's secure coding standard.
125- Thanks to peter@valchev.net for reviews, comments, enthusiasm, and
126 multiple platform tests!
127- Thanks to taviso@sdf.lonestar.org for the pointing out stupid API
128 decisions and cross-checking my logic.
129
130= Changes
131
132The changes and todo list can be found in include/safe_iop.h
133
134= Contributions, corrections, suggestions, flames . . .
135
136Please drop me an email if I'm doing something completely stupid, you
137love using the library, you have a patch or recommendation, or for whatever
138other reason. I hope this software helps out a bit!
139
README.md
1safe_iop - a safe integer operation library for C
2```
3Chris Hutchinson <portmaster_AT_BSDforge.com>
4Will Drewry <redpig@dataspill.org>
5```
6Copyright and Licensing
7```
8Copyright 2008-2021, Chris Hutchinson <portmaster_AT_BSDforge.com>
9Copyright 2007-2008, Will Drewry <redpig@dataspill.org>
10Some portions copyright 2008 Google Inc
11Released into the public domain with no warranty and no guarantees
12```
13Introduction
14---
15Unsafe integer operations are a major cause of software defects even in
16modern day software. C is the underlying language for most high level
17languages (Ruby, Python, Java, etc) in addition to being in widespread
18general use. C is a preferred language for high performance programming
19and is often used for media file parsing and manipulation.
20
21Integer overflows occur when the calculated integer requires more storage
22from the computing platform than is available. If a number is too large,
23not all of its information can be stored. This has dangerous side effects.
24For a detailed and thorough discussion on integer overflows, please check
25out CERT's website on Secure Coding[1] and even Wikipedia[2].
26
27[1] https://www.securecoding.cert.org/confluence/display/seccode/CERT+C+Secure+Coding+Standard
28
29[2] http://en.wikipedia.org/wiki/Integer_overflow
30
31Requirements
32---
33safe_iop was designed explicitly with GNU GCC in mind and has only been
34tested with it. Your mileage may vary. Please let me know if it works for
35you with different compilers or on different platforms, and I'll update
36the Compatibility section below!
37
38In addition, your system must supply limits.h and assert.h for safe_iop
39to function as expected. It is possible to remove the dependence on both,
40but it breaks general portability.
41
42Usage
43---
44`safe_iop` comes in two pieces, `safe_iop.h` and `safe_iop.c`. `safe_iop.h`
45provides extensive macros for performing safe integer operations quickly
46and easily. `safe_iop.c` contains some testing code to make sure the package
47works on your system and a preliminary format string interface, safe_iopf.
48`safe_iopf` is not for the faint of heart as it is currently under development.
49The remainder of this document will focus on `safe_iop.h`.
50
51In order to use `safe_iop`, you will need to place `safe_iop.h` in your
52compiler's include path either by copying it somewhere like `/usr/include`,
53using an include flag `-I/opt/safe_iop/include`, or whatever other way you
54prefer. You will then need to include the header in the source file you
55will use the functions from.
56E.g., `#include <safe_iop.h>`
57
58safe_iop provides macros which check the validity of a given integer
59operation. It supports the following operations:
60
61- `multiplication: safe_mul()`
62- `division: safe_div()`
63- `addition: safe_add()`
64- `subtraction: safe_sub()`
65
66All of these macros take a result pointer, or NULL, as the first argument.
67The subsequent argument should be the two values to operate on. They then
68return true or false depending on if the operation is safe or not.
69(If NULL is given, a true or false value will be returned.)
70```
71 uint32_t a = 100, b = 200, c = 0;
72 if (safe_mul(&c, a, b)) printf("c is %u\n", c);
73```
74In addition, there are versions of these functions for multiple sequential
75operations:
76```
77 uint32_t a = 100, b = 200, c = 300, d = 0;
78 if (safe_mul3(&d, a, b, c)) printf("d is %u\n", d);
79```
80`safe_<op>3-5()` are all available.
81
82It is important to note that if the types of integers passed to safe_iop
83do not match, the operation will return false `(0)` with `-DNDEBUG` defined.
84If it is not defined, `assert()` is called and the program will abort if
85these mismatch is seen!
86
87For example,
88```
89 uint32_t a = 100, c = 0;
90 uint8_t b = 20;
91 if (safe_add(&c, a, b)) /* I will return false! */
92```
93Examples can be found in the `examples/` directory.
94
95safe_iopf
96---
97If you'd like to use the format string function, do so at your own peril :-)
98If you like it and would like to send me a patch to make it awesome, I'd
99appreciate it! To use, just include the c file in your build, or build
100the shared library and link it to your app:
101 make so # or make dylib for OS X
102```
103 ...
104 gcc yourapp.c ... -lsafe_iop
105```
106More to come!
107
108Compatibility
109---
110Tests pass on the following platforms:
111
112- OS X Tiger, x86, GNU GCC 4.0.1
113- OS X Leopard, x86, GNU GCC 4.0.1
114- GNU/Linux, x86, GNU GCC 4.0.3
115- GNU/Linux, x86_64, GNU GCC 4.0.3
116- OpenBSD, VAX, GNU GCC 2.95.3
117- OpenBSD, sparc, GNU GCC 2.95.3
118- OpenBSD, alpha, GNU GCC 3.3.5
119- OpenBSD, sparc, GNU GCC 2.95.3
120- OpenBSD, macppc, GNU GCC 3.3.5
121- OpenBSD, arm, GNU GCC 3.3.5
122~ OpenBSD, sparc64, GNU GCC 3.3.5 [1]
123
124[1] For sparc64, there is an optimization bug which causes tests to fail if
125 `-O<level> exceeds 1`.
126
127Credit where credit is do
128---
129- The functions used in this library were largely drawn from the examples
130 provided in CERT's secure coding standard.
131- Thanks to peter@valchev.net for reviews, comments, enthusiasm, and
132 multiple platform tests!
133- Thanks to taviso@sdf.lonestar.org for the pointing out stupid API
134 decisions and cross-checking my logic.
135
136Changes
137---
138The changes and todo list can be found in `include/safe_iop.h`
139
140Contributions, corrections, suggestions, flames . . .
141---
142Please drop me an email if I'm doing something completely stupid, you
143love using the library, you have a patch or recommendation, or for whatever
144other reason. I hope this software helps out a bit!
145