1=pod
2
3=head1 NAME
4
5OSSL_SAFE_MATH_SIGNED, OSSL_SAFE_MATH_UNSIGNED,
6safe_add_TYPE, safe_sub_TYPE, safe_mul_TYPE, safe_div_TYPE, safe_mod_TYPE,
7safe_div_round_up_TYPE, safe_neg_TYPE
8- create helper functions to safely perform non-overflowing integer operations
9
10=head1 SYNOPSIS
11
12=for openssl generic
13
14 #include "internal/safe_math.h"
15
16 OSSL_SAFE_MATH_SIGNED(NAME, TYPE)
17 OSSL_SAFE_MATH_UNSIGNED(NAME, TYPE)
18
19 TYPE safe_add_TYPE(TYPE a, TYPE b, int *err);
20 TYPE safe_sub_TYPE(TYPE a, TYPE b, int *err);
21 TYPE safe_mul_TYPE(TYPE a, TYPE b, int *err);
22 TYPE safe_div_TYPE(TYPE a, TYPE b, int *err);
23 TYPE safe_mod_TYPE(TYPE a, TYPE b, int *err);
24 TYPE safe_div_round_up_TYPE(TYPE a, TYPE b, int *err);
25 TYPE safe_muldiv_TYPE(TYPE a, TYPE b, TYPE c, int *err);
26 TYPE safe_neg_TYPE(TYPE a, int *err);
27 TYPE safe_abs_TYPE(TYPE a, int *err);
28
29=head1 DESCRIPTION
30
31Define helper functions to assist with handling integer overflow detection.
32All of these functions perform an arithmetic operation on its arguments and
33return the result of the operation.  If the operation cannot be
34correctly represented, the error I<err> flag is set.  No behaviour that is
35undefined as per the C standard will take place.
36
37OSSL_SAFE_MATH_SIGNED() creates helper functions for the B<I<TYPE>> with the
38suffix B<I<NAME>>.
39
40OSSL_SAFE_MATH_UNSIGNED() creates helper functions for the B<I<TYPE>> with the
41suffix B<I<NAME>>.
42
43safe_add_TYPE() adds the two arguments I<a> and I<b> together.
44
45safe_sub_TYPE() subtracts I<b> from I<a>.
46
47safe_mul_TYPE() multiplies the two arguments I<a> and I<b> together.
48
49safe_div_TYPE() divides I<a> by I<b>.
50
51safe_mod_TYPE() calculates the remainder when I<a> is divided by I<b>.
52
53safe_div_round_up_TYPE() calculates I<a> / I<b> + (I<a> % I<b> != 0).
54I.e. it computes the quotient of I<a> and I<b> rounding any remainder towards
55positive infinity.
56
57safe_muldiv_TYPE() multiplies I<a> and I<b> together and divides the
58result by I<c>.
59
60safe_neg_TYPE() calculates the negation of I<a>.
61
62safe_abs_TYPE() calculates the absolute value of I<a>.
63
64=head1 NOTES
65
66The safe_muldiv_TYPE() function is not perfect.  There exist inputs where
67a valid result could be computed with infinite length integers but this
68function returns an error condition.  Such instances should, however,
69be rare in practice.  The converse is not true.  An invalid result will
70always be flagged as an error.
71
72=head1 RETURN VALUES
73
74All these functions return the result of the operation, if the operation
75is well defined.  They return an arbitrary value if not.
76
77=head1 EXAMPLES
78
79This example is of a function that computes the size of a record that
80has a four byte element count which is followed by that many elements.
81It returns zero on overflow.
82
83 OSSL_SAFE_MATH_UNSIGNED(sizet, size_t, SIZE_MAX)
84
85 size_t compute_record_size(uint32_t n)
86 {
87    int err = 0;
88    size_t result, product;
89
90    product = safe_mul_sizet(n, sizeof(struct widget), &err);
91    result = safe_add_sizet(product, sizeof(n), &err);
92
93    return err ? 0 : result;
94 }
95
96=head1 HISTORY
97
98The functions described here were all added in OpenSSL 3.1.
99
100=head1 COPYRIGHT
101
102Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
103
104Licensed under the Apache License 2.0 (the "License").  You may not use
105this file except in compliance with the License.  You can obtain a copy
106in the file LICENSE in the source distribution or at
107L<https://www.openssl.org/source/license.html>.
108
109=cut
110