lib/libcrypto/man/BN_set_flags.3

   1 .\"     $OpenBSD: BN_set_flags.3,v 1.3 2018/04/29 15:58:21 schwarze 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 29 2018 $
  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
  38 enables the given
  39 .Fa flags
  40 on
  41 .Fa b .
  42 The
  43 .Fa flags
  44 argument can contain zero or more of the following constants OR'ed
  45 together:
  46 .Bl -tag -width Ds
  47 .It Dv BN_FLG_CONSTTIME
  48 If this flag is set on the divident
  49 .Fa a
  50 or the divisor
  51 .Fa d
  52 in
  53 .Xr BN_div 3 ,
  54 on the exponent
  55 .Fa p
  56 in
  57 .Xr BN_mod_exp 3 ,
  58 or on the divisor
  59 .Fa a
  60 or the modulus
  61 .Fa n
  62 in
  63 .Xr BN_mod_inverse 3 ,
  64 these functions select algorithms with an execution time independent
  65 of the respective numbers, to avoid exposing sensitive information
  66 to timing side-channel attacks.
  67 .Pp
  68 This flag is off by default for
  69 .Vt BIGNUM
  70 objects created with
  71 .Xr BN_new 3 .
  72 .It Dv BN_FLG_MALLOCED
  73 If this flag is set,
  74 .Xr BN_free 3
  75 and
  76 .Xr BN_clear_free 3
  77 will not only clear and free the components of
  78 .Fa b ,
  79 but also
  80 .Fa b
  81 itself.
  82 This flag is set internally by
  83 .Xr BN_new 3 .
  84 Setting it manually on an existing
  85 .Vt BIGNUM
  86 object is usually a bad idea and can cause calls to
  87 .Xr free 3
  88 with bogus arguments.
  89 .It Dv BN_FLG_STATIC_DATA
  90 If this flag is set,
  91 .Xr BN_clear_free 3
  92 will neither clear nor free the memory used for storing the number.
  93 Consequently, setting it manually on an existing
  94 .Vt BIGNUM
  95 object is usually a terrible idea that can cause both disclosure
  96 of secret data and memory leaks.
  97 This flag is automatically set on the constant
  98 .Vt BIGNUM
  99 objects returned by
 100 .Xr BN_value_one 3
 101 and by the functions documented in
 102 .Xr BN_get0_nist_prime_521 3 .
 103 .El
 104 .Pp
 105 .Fn BN_get_flags
 106 interpretes
 107 .Fa flags
 108 as a bitmask and returns those of the given flags that are set in
 109 .Fa b ,
 110 OR'ed together, or 0 if none of the given
 111 .Fa flags
 112 is set.
 113 The
 114 .Fa flags
 115 argument has the same syntax as for
 116 .Fn BN_set_flags .
 117 .Pp
 118 These functions are currently implemented as macros, but they are
 119 likely to become real functions in the future when the
 120 .Vt BIGNUM
 121 data type will be made opaque.
 122 .Sh RETURN VALUES
 123 .Fn BN_get_flags
 124 returns zero or more of the above constants, OR'ed together.
 125 .Sh SEE ALSO
 126 .Xr BN_mod_exp 3 ,
 127 .Xr BN_mod_inverse 3 ,
 128 .Xr BN_new 3 ,
 129 .Xr BN_with_flags 3
 130 .Sh HISTORY
 131 .Fn BN_set_flags
 132 and
 133 .Fn BN_get_flags
 134 first appeared in SSLeay 0.9.1 and have been available since
 135 .Ox 2.6 .
 136 .Sh CAVEATS
 137 No public interface exists to clear a flag once it is set.
 138 So think twice before using
 139 .Fn BN_set_flags .
 140 .Sh BUGS
 141 Even if the
 142 .Dv BN_FLG_CONSTTIME
 143 flag is set on
 144 .Fa a
 145 or
 146 .Fa b ,
 147 .Fn BN_gcd
 148 neither fails nor operates in constant time, potentially allowing
 149 timing side-channel attacks.
 150 .Pp
 151 Even if the
 152 .Dv BN_FLG_CONSTTIME
 153 flag is set on
 154 .Fa p ,
 155 if the modulus
 156 .Fa m
 157 is even,
 158 .Xr BN_mod_exp 3
 159 does not operate in constant time, potentially allowing
 160 timing side-channel attacks.
 161 .Pp
 162 If
 163 .Dv BN_FLG_CONSTTIME
 164 is set on
 165 .Fa p ,
 166 .Fn BN_exp
 167 fails instead of operating in constant time.