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