1.\" $OpenBSD: BN_set_flags.3,v 1.6 2023/04/27 07:22:22 tb Exp $ 2.\" 3.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 27 2023 $ 18.Dt BN_SET_FLAGS 3 19.Os 20.Sh NAME 21.Nm BN_set_flags , 22.Nm BN_get_flags 23.Nd enable and inspect flags on BIGNUM objects 24.Sh SYNOPSIS 25.In openssl/bn.h 26.Ft void 27.Fo BN_set_flags 28.Fa "BIGNUM *b" 29.Fa "int flags" 30.Fc 31.Ft int 32.Fo BN_get_flags 33.Fa "const BIGNUM *b" 34.Fa "int flags" 35.Fc 36.Sh DESCRIPTION 37.Fn BN_set_flags 38enables the given 39.Fa flags 40on 41.Fa b . 42The 43.Fa flags 44argument can contain zero or more of the following constants OR'ed 45together: 46.Bl -tag -width Ds 47.It Dv BN_FLG_CONSTTIME 48If this flag is set on the divident 49.Fa a 50or the divisor 51.Fa d 52in 53.Xr BN_div 3 , 54on the exponent 55.Fa p 56in 57.Xr BN_mod_exp 3 , 58or on the divisor 59.Fa a 60or the modulus 61.Fa n 62in 63.Xr BN_mod_inverse 3 , 64these functions select algorithms with an execution time independent 65of the respective numbers, to avoid exposing sensitive information 66to timing side-channel attacks. 67.Pp 68This flag is off by default for 69.Vt BIGNUM 70objects created with 71.Xr BN_new 3 . 72.It Dv BN_FLG_MALLOCED 73If this flag is set, 74.Xr BN_free 3 75and 76.Xr BN_clear_free 3 77will not only clear and free the components of 78.Fa b , 79but also 80.Fa b 81itself. 82This flag is set internally by 83.Xr BN_new 3 . 84Setting it manually on an existing 85.Vt BIGNUM 86object is usually a bad idea and can cause calls to 87.Xr free 3 88with bogus arguments. 89.It Dv BN_FLG_STATIC_DATA 90If this flag is set, 91.Xr BN_clear_free 3 92will neither clear nor free the memory used for storing the number. 93Consequently, setting it manually on an existing 94.Vt BIGNUM 95object is usually a terrible idea that can cause both disclosure 96of secret data and memory leaks. 97This flag is automatically set on the constant 98.Vt BIGNUM 99object returned by 100.Xr BN_value_one 3 . 101.El 102.Pp 103.Fn BN_get_flags 104interprets 105.Fa flags 106as a bitmask and returns those of the given flags that are set in 107.Fa b , 108OR'ed together, or 0 if none of the given 109.Fa flags 110is set. 111The 112.Fa flags 113argument has the same syntax as for 114.Fn BN_set_flags . 115.Sh RETURN VALUES 116.Fn BN_get_flags 117returns zero or more of the above constants, OR'ed together. 118.Sh SEE ALSO 119.Xr BN_mod_exp 3 , 120.Xr BN_mod_inverse 3 , 121.Xr BN_new 3 , 122.Xr BN_with_flags 3 123.Sh HISTORY 124.Fn BN_set_flags 125and 126.Fn BN_get_flags 127first appeared in SSLeay 0.9.1 and have been available since 128.Ox 2.6 . 129.Sh CAVEATS 130No public interface exists to clear a flag once it is set. 131So think twice before using 132.Fn BN_set_flags . 133.Sh BUGS 134Even if the 135.Dv BN_FLG_CONSTTIME 136flag is set on 137.Fa a 138or 139.Fa b , 140.Fn BN_gcd 141neither fails nor operates in constant time, potentially allowing 142timing side-channel attacks. 143.Pp 144Even if the 145.Dv BN_FLG_CONSTTIME 146flag is set on 147.Fa p , 148if the modulus 149.Fa m 150is even, 151.Xr BN_mod_exp 3 152does not operate in constant time, potentially allowing 153timing side-channel attacks. 154.Pp 155If 156.Dv BN_FLG_CONSTTIME 157is set on 158.Fa p , 159.Fn BN_exp 160fails instead of operating in constant time. 161