lib/libcrypto/man/BN_set_flags.3

   1 .\"     $OpenBSD: BN_set_flags.3,v 1.1 2017/01/30 01:29:31 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: January 30 2017 $
  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 in
  51 .Xr BN_div 3 ,
  52 on the exponent
  53 .Fa p
  54 in
  55 .Xr BN_mod_exp 3 ,
  56 or on the divisor
  57 .Fa a
  58 or the modulus
  59 .Fa n
  60 in
  61 .Xr BN_mod_inverse 3 ,
  62 these functions prefer algorithms with an execution time independent
  63 of the respective numbers, to avoid exposing sensitive information
  64 to timing attacks.
  65 .Pp
  66 If this flag is set on the exponent
  67 .Fa p
  68 in
  69 .Xr BN_exp 3
  70 or if the modulus
  71 .Fa m
  72 is even for
  73 .Xr BN_mod_exp 3 ,
  74 an error occurs.
  75 .Pp
  76 Various functions automatically set this flag on sensitive data.
  77 For example, the default implementations of
  78 .Xr DH_generate_key 3 ,
  79 .Xr DSA_generate_key 3 ,
  80 and
  81 .Xr RSA_generate_key_ex 3
  82 set it on the generated private key.
  83 .It Dv BN_FLG_MALLOCED
  84 If this flag is set,
  85 .Xr BN_free 3
  86 and
  87 .Xr BN_clear_free 3
  88 will not only clear and free the components of
  89 .Fa b ,
  90 but also
  91 .Fa b
  92 itself.
  93 This flag is set internally by
  94 .Xr BN_new 3 .
  95 Setting it manually on an existing
  96 .Vt BIGNUM
  97 object is usually a bad idea and can cause calls to
  98 .Xr free 3
  99 with bogus arguments.
 100 .It Dv BN_FLG_STATIC_DATA
 101 If this flag is set,
 102 .Xr BN_clear_free 3
 103 will neither clear nor free the memory used for storing the number.
 104 Consequently, setting it manually on an existing
 105 .Vt BIGNUM
 106 object is usually a terrible idea that can cause both disclosure
 107 of secret data and memory leaks.
 108 This flag is automatically set on the constant
 109 .Vt BIGNUM
 110 objects returned by
 111 .Xr BN_value_one 3
 112 and by the functions documented in
 113 .Xr BN_get0_nist_prime_521 3 .
 114 .El
 115 .Pp
 116 .Fn BN_get_flags
 117 interpretes
 118 .Fa flags
 119 as a bitmask and returns those of the given flags that are set in
 120 .Fa b ,
 121 OR'ed together, or 0 if none of the given
 122 .Fa flags
 123 is set.
 124 The
 125 .Fa flags
 126 argument has the same syntax as for
 127 .Fn BN_set_flags .
 128 .Pp
 129 These functions are currently implemented as macros, but they are
 130 likely to become real functions in the future when the
 131 .Vt BIGNUM
 132 data type will be made opaque.
 133 .Sh RETURN VALUES
 134 .Fn BN_get_flags
 135 returns zero or more of the above constants, OR'ed together.
 136 .Sh SEE ALSO
 137 .Xr BN_mod_exp 3 ,
 138 .Xr BN_mod_inverse 3 ,
 139 .Xr BN_new 3 ,
 140 .Xr BN_with_flags 3
 141 .Sh CAVEATS
 142 No public interface exists to clear a flag once it is set.
 143 So think twice before using
 144 .Fn BN_set_flags .