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