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.2. 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