=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_div_round_up_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_div_round_up_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_div_round_up_TYPE() calculates I<a> / I<b> + (I<a> % I<b> != 0).
I.e. it computes the quotient of I<a> and I<b> rounding any remainder towards
positive infinity.

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-2022 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