doc: document the internal integer overflow helpers

Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16930)

diff --git a/doc/internal/man3/OSSL_SAFE_MATH_SIGNED.pod b/doc/internal/man3/OSSL_SAFE_MATH_SIGNED.pod
new file mode 100644 (file)
index 0000000..43f9ab3
--- /dev/null
+++ b/doc/internal/man3/OSSL_SAFE_MATH_SIGNED.pod
@@ -0,0 +1,104 @@
+=pod
+
+=head1 NAME
+
+OSSL_SAFE_MATH_SIGNED, OSSL_SAFE_MATH_UNSIGNED,
+safe_add_TYPE, safe_sub_TYPE, safe_mul_TYPE, safe_div_TYPE, safe_mod_TYPE,
+safe_neg_TYPE
+- create helper functions to safely perform non-overflowing integer operations
+
+=head1 SYNOPSIS
+
+=for openssl generic
+
+ #include "internal/safe_math.h"
+
+ OSSL_SAFE_MATH_SIGNED(NAME, TYPE)
+ OSSL_SAFE_MATH_UNSIGNED(NAME, TYPE)
+
+ TYPE safe_add_TYPE(TYPE a, TYPE b, int *err);
+ TYPE safe_sub_TYPE(TYPE a, TYPE b, int *err);
+ TYPE safe_mul_TYPE(TYPE a, TYPE b, int *err);
+ TYPE safe_div_TYPE(TYPE a, TYPE b, int *err);
+ TYPE safe_mod_TYPE(TYPE a, TYPE b, int *err);
+ TYPE safe_muldiv_TYPE(TYPE a, TYPE b, TYPE c, int *err);
+ TYPE safe_neg_TYPE(TYPE a, int *err);
+ TYPE safe_abs_TYPE(TYPE a, int *err);
+
+=head1 DESCRIPTION
+
+Define helper functions to assist with handling integer overflow detection.
+All of these functions perform an arithmetic operation on its arguments and
+return the result of the operation.  If the operation cannot be
+correctly represented, the error I<err> flag is set.  No behaviour that is
+undefined as per the C standard will take place.
+
+OSSL_SAFE_MATH_SIGNED() creates helper functions for the B<I<TYPE>> with the
+suffix B<I<NAME>>.
+
+OSSL_SAFE_MATH_UNSIGNED() creates helper functions for the B<I<TYPE>> with the
+suffix B<I<NAME>>.
+
+safe_add_TYPE() adds the two arguments I<a> and I<b> together.
+
+safe_sub_TYPE() subtracts I<b> from I<a>.
+
+safe_mul_TYPE() multiplies the two arguments I<a> and I<b> together.
+
+safe_div_TYPE() divides I<a> by I<b>.
+
+safe_mod_TYPE() calculates the remainder when I<a> is divided by I<b>.
+
+safe_muldiv_TYPE() multiplies I<a> and I<b> together and divides the
+result by I<c>.
+
+safe_neg_TYPE() calculates the negation of I<a>.
+
+safe_abs_TYPE() calculates the absolute value of I<a>.
+
+=head1 NOTES
+
+The safe_muldiv_TYPE() function is not perfect.  There exist inputs where
+a valid result could be computed with infinite length integers but this
+function returns an error condition.  Such instances should, however,
+be rare in practice.  The converse is not true.  An invalid result will
+always be flagged as an error.
+
+=head1 RETURN VALUES
+
+All these functions return the result of the operation, if the operation
+is well defined.  They return an arbitrary value if not.
+
+=head1 EXAMPLES
+
+This example is of a function that computes the size of a record that
+has a four byte element count which is followed by that many elements.
+It returns zero on overflow.
+
+ OSSL_SAFE_MATH_UNSIGNED(sizet, size_t, SIZE_MAX)
+
+ size_t compute_record_size(uint32_t n)
+ {
+    int err = 0;
+    size_t result, product;
+
+    product = safe_mul_sizet(n, sizeof(struct widget), &err);
+    result = safe_add_sizet(product, sizeof(n), &err);
+
+    return err ? 0 : result;
+ }
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.1.
+
+=head1 COPYRIGHT
+
+Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut