doc/man3/BN_BLINDING_new.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
   6 BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
   7 BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread,
   8 BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
   9 BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/bn.h>
  14
  15  BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
  16                               BIGNUM *mod);
  17  void BN_BLINDING_free(BN_BLINDING *b);
  18  int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
  19  int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
  20  int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
  21  int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
  22                             BN_CTX *ctx);
  23  int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
  24                            BN_CTX *ctx);
  25  int BN_BLINDING_is_current_thread(BN_BLINDING *b);
  26  void BN_BLINDING_set_current_thread(BN_BLINDING *b);
  27  int BN_BLINDING_lock(BN_BLINDING *b);
  28  int BN_BLINDING_unlock(BN_BLINDING *b);
  29  unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
  30  void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
  31  BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
  32                                        const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
  33                                        int (*bn_mod_exp)(BIGNUM *r,
  34                                                          const BIGNUM *a,
  35                                                          const BIGNUM *p,
  36                                                          const BIGNUM *m,
  37                                                          BN_CTX *ctx,
  38                                                          BN_MONT_CTX *m_ctx),
  39                                        BN_MONT_CTX *m_ctx);
  40
  41 =head1 DESCRIPTION
  42
  43 BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
  44 the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
  45
  46 BN_BLINDING_free() frees the B<BN_BLINDING> structure.
  47 If B<b> is NULL, nothing is done.
  48
  49 BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
  50 the B<A> and B<Ai> or, after specific number of uses and if the
  51 necessary parameters are set, by re-creating the blinding parameters.
  52
  53 BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
  54 If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
  55 returned in B<r> (this is useful if a B<RSA> object is shared among
  56 several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
  57 inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
  58 the inverse blinding.
  59
  60 BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
  61 functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
  62 with B<r> set to NULL.
  63
  64 BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
  65 structure is owned by the current thread. This is to help users
  66 provide proper locking if needed for multi-threaded use.
  67
  68 BN_BLINDING_set_current_thread() sets the current thread as the
  69 owner of the B<BN_BLINDING> structure.
  70
  71 BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
  72
  73 BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
  74
  75 BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
  76 there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
  77 B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
  78 automatic update of the B<BN_BLINDING> parameters after each use
  79 and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
  80 of the B<BN_BLINDING> parameters after a fixed number of uses (currently
  81 32). In newly allocated B<BN_BLINDING> objects no flags are set.
  82 BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
  83
  84 BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
  85 using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
  86 B<m_ctx> can be used to pass special functions for exponentiation
  87 (normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
  88
  89 =head1 RETURN VALUES
  90
  91 BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
  92 or NULL in case of an error.
  93
  94 BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
  95 BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
  96 success and 0 if an error occurred.
  97
  98 BN_BLINDING_is_current_thread() returns 1 if the current thread owns
  99 the B<BN_BLINDING> object, 0 otherwise.
 100
 101 BN_BLINDING_set_current_thread() doesn't return anything.
 102
 103 BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
 104 succeeded or 0 on error.
 105
 106 BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
 107 (a B<unsigned long> value).
 108
 109 BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
 110 parameters or NULL on error.
 111
 112 =head1 HISTORY
 113
 114 BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
 115 deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
 116
 117 =head1 COPYRIGHT
 118
 119 Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved.
 120
 121 Licensed under the OpenSSL license (the "License").  You may not use
 122 this file except in compliance with the License.  You can obtain a copy
 123 in the file LICENSE in the source distribution or at
 124 L<https://www.openssl.org/source/license.html>.
 125
 126 =cut